Introduction to Agent Skills: teaching notes

Side-by-side notes for 08-praxis-introduction-to-agent-skills.html (9 slides). This is the deep dive on the idea Praxis calls the heart of the method: the plain-English skill file as institutional memory (framings.md: skill file as institutional memory; patterns.md). Claude 101 (course 02) and AI Fluency (course 05) both point here. The deck is a developer course; these notes hold the framing for the nine non-technical archetypes, because the plain-English SKILL.md is exactly what makes Skills land for them. Written from the deck and 08-introduction-to-agent-skills-lessons.txt, against the Praxis teaching library. Method: teaching-notes-method.md.

How to use these notes

Blocks marked Back to your card, Brief it like a new hire and Run it live are the three moves from T0, how we teach Praxis. Use the names and tasks on the group's Use Case Cards wherever you see [name].
Guidance, not a script. Teach the person, not the slides.
Each teaching slide has a Pause, then ask block. Put the question, then stop. Do not fill the silence. If they freeze, one line: "Take your time, type anything when you're ready, including 'I don't know'." Then wait again.
By background gives a line per archetype (tutor/scenarios.md). Reach for the one that matches whoever is in front of you and ignore the rest. A palette, not a checklist.
This is the most technical course in the set. Two confusions are near-certain and the notes flag them: the "I can't read code / what is it doing" fear (objections.md: can't read code), and conflating the Claude Code skill taught here with the app skill from Claude 101. The cure for both is the same: the intelligence lives in the plain-English SKILL.md, not in any code.
Hold the voice (train-the-trainer.md Part 4): no "great question", no emoji, one term only: Claude Code. Underclaim. Cost is "about twenty dollars a month" and stop.
Do not read code aloud. If they ask what a line does, point at the skill file, not the script (framings.md: voice, what never to say).

Title

Teach Claude Code something once. It remembers when it matters.

The idea

Set the frame: six ideas, one per screen, and the whole course is one move: turn a thing you keep explaining into a thing Claude loads by itself. The watching is the lesson, so take the silences.

Say it like this

"Six ideas, one screen each. The whole course is one move: anything you find yourself explaining to Claude over and over, you write down once, and from then on it loads itself the moment it's relevant. I'll show you, then stop and ask where it fits your work."

Open with

The task they named in intake, the one they do the same way every time. "By the end, that's the skill we'll have described."

Spine

The whole course on one screen

The idea

Four moves: grasp what a skill is, build one, place it among the other tools and share it, then fix it when it misbehaves. Orient, don't teach.

Say it like this

"Here's the shape. First, what a skill actually is. Then we build one. Then we place it next to the other ways to customise Claude Code and we share it. Then we fix it when it doesn't fire. If you lose the thread, this is the map back."

Cue

Twenty seconds, then move. Lesson 1 is the centrepiece; everything else serves it.

Lesson 1 (if you take one thing away)

If you keep explaining it, write it down once

The centrepiece. If they take one thing away, it's this.

The idea

A skill is a folder of instructions. Claude holds only its one-line description until your request matches, then it loads the rest. The rule of thumb: if you keep repeating an instruction, that's a skill waiting to be written.

Say it like this

"This is the idea the whole programme has been building to. The rules your best person carries in their head, written down once, so the work comes out their way every time. That written-down thing is a skill: a folder with a plain-English file in it. Claude keeps only its one-line description in mind, and the moment your request matches, it pulls in the full instructions. Up to now those rules walked out the door at six o'clock. The skill file pulls them out of the head and onto disk." (framings.md: skill file as institutional memory; adapt "best person" to their role.)

Pause, then ask

"What's a task you do the same way every time, where the 'right way' lives in someone's head?"
"If that person left tomorrow, what would walk out the door with them?"

(wait: this lands hard for regulated and professional rooms.)

By background (the skill they'd write down once)

Investigator: the house report rules: eight sections, cite every source, never infer.
Analyst: the vendor-comparison method: fixed columns, mark blanks "no data".
Designer: the asset-manifest method: read each brief, list every variant, flag specs.
Knowledge worker: the invoice-to-CSV method: the schema, and "leave blanks blank".
Reporter: the weekly-briefing method: the five sections, attribute every line.
Content: the house-voice rules: hook, problem, argument, close; no off-voice lines.
Form-filler: the receipt-allocation method: one section each, totals must reconcile.
Outreach: the proposal method: five sections, one per customer, no invented numbers.
Exec: the exec-brief method: revenue, at-risk, decisions, steady; facts not editorial.

Brief it like a new hire

On the map: the written procedure you hand a new starter for a job that comes back every week. If you keep explaining it, write it down once.

Back to your card

What's the part of your card's task you'd explain every single time? That's your first skill.
[name], explain to [name] how that's different from putting the same instructions in a Project.

Watch for

Two confusions. First, the caption's point: a skill is not CLAUDE.md (which loads every conversation) and not a slash command (which you type). A skill activates itself on a match. Name that difference. Second, this is the Claude Code skill, the plain-English SKILL.md you write, not the built-in app skill from Claude 101 that made you a spreadsheet. If they sat course 02, say so out loud or they'll merge the two (train-the-trainer.md: module 6 vs module 14).

Lesson 2

Build one: folder, file, restart

The idea

Three steps: make a directory, write SKILL.md (a name and a description, then the instructions), restart. Claude loads every skill's name and description at startup and matches your request to them. When two skills share a name, priority decides: Enterprise, then Personal, then Project, then Plugins.

Say it like this

"Building one is three steps: a folder, a file called SKILL.md, restart. The file is plain English: a name, a one-line description of when to use it, then the instructions. You build it just by talking to Claude Code; you don't write the file by hand. On restart it reads every skill's name and description, and from then on it matches what you ask against them." (framings.md: Claude as translator; the work is describing the rules, not coding.)

Pause, then ask

"If you had to write the one-line description, when should Claude reach for your skill?"
"What would you call it, so you'd know it from any other?"

(wait)

By background (the description they'd write: "use this when...")

Investigator: "...building a subject background report from a case folder."
Analyst: "...comparing vendor or provider responses into a like-for-like table."
Designer: "...listing every asset and variant a campaign brief needs."
Knowledge worker: "...pulling a folder of invoices into a clean CSV."
Reporter: "...consolidating the team's updates into the Monday briefing."
Content: "...drafting a post in our house voice from the back catalogue."
Form-filler: "...allocating a folder of receipts to the filing template."
Outreach: "...drafting one proposal per customer from their file."
Exec: "...turning the board inputs into a one-page brief."

Run it live

Kick off: Build a skill for one card: make the folder, write SKILL.md with the group, restart, then ask for the task.
Expect: About five minutes.
While it runs: Get the group to write the one-line description. Point out the moment Claude picks the skill up.
When it lands: Ask for the task a second way and see if it still triggers.

Watch for

The priority ladder (Enterprise > Personal > Project > Plugins) reads as corporate plumbing to a solo operator. Don't oversell it. The one line that matters for them is the caption's: keep names distinct, because if two skills share a name, priority silently picks the winner. Also reassure: Claude asks you to confirm before it loads the full skill, so nothing fires behind your back (objections.md: permission / auto).

Lesson 3

Keep SKILL.md lean: split the rest out

The idea

Two fields are required (name, description), two optional (allowed-tools, model). Past about 500 lines, move detail into supporting files Claude opens only when it needs them: scripts to run, references to read, assets to use. This is progressive disclosure: a table of contents in context, not the whole document.

Say it like this

"Keep the main file short. Two things are required, the name and the description, and a couple are optional. When a skill grows, you don't cram it into one giant file. You split the detail into side files Claude only opens when it actually needs them. And two controls earn their place even for non-technical work: you can fence a skill to read-only with allowed-tools, and you tell Claude to run a script rather than read it, so only the result costs anything, never the source." (Ties to framings.md: the context window: the folder is the memory, and you keep the working memory clean.)

Pause, then ask

"In your method, what's the one-page summary, and what's the thick reference you'd only pull out for the odd case?"
"Is there a part of your work where you'd want it strictly read-only: look, don't touch?"

(wait)

By background (the lean SKILL.md vs the side file it points to)

Investigator: the eight-section rules in SKILL.md; the source-classification guide in a reference, read only on an odd source. Read-only on the case folder fits here.
Analyst: the column set in SKILL.md; the comparability rules in a reference.
Designer: the manifest format in SKILL.md; the retailer spec sheets as assets.
Knowledge worker: the CSV schema in SKILL.md; the known supplier quirks in a reference.
Reporter: the five sections in SKILL.md; the team roster as an asset.
Content: the voice rules in SKILL.md; the back catalogue as reference posts.
Form-filler: the allocation rules in SKILL.md; the category definitions in a reference.
Outreach: the proposal format in SKILL.md; the knowledge base as a reference.
Exec: the brief format in SKILL.md; the KPI definitions in a reference.

Back to your card

For your card, what's the one-page summary and what's the thick reference you'd only open for the odd case?

Watch for

This is the slide where "I can't read code" surfaces: frontmatter, YAML, allowed-tools all look like gibberish. Head it off: "Don't read the code. The intelligence lives in the plain-English skill file. The rest is enforcement, and Claude writes and maintains it." (objections.md: can't read code; what is it doing.) Some technical slides here (the exact metadata fields) genuinely don't vary by domain; give the one shared example and don't force nine.

Lesson 4

Five tools, five jobs

The idea

Skills load on demand when your request matches. The other four customisations solve different problems: CLAUDE.md is always loaded; subagents are work you delegate to an isolated context; hooks fire on an event like a file save; MCP connects external tools. Each fires at a different moment. Most real setups use several at once.

Say it like this

"Five ways to shape Claude Code, and they're not rivals. A skill fires when your request matches it. CLAUDE.md is the always-on house rules. Subagents are work you hand off to run on its own. Hooks fire on an event, like saving a file. Connectors, MCP, plug in your outside tools. The skill is the right reach when the knowledge should apply automatically the moment the topic comes up. Pick by when each one fires." (CLAUDE.md is the project's standing rules; the skill is the on-demand method.)

Pause, then ask

"Of your rules, which are 'always, every time' and which are 'only when this task comes up'?"
"Which of your tools or systems would you most want Claude to reach into?"

(wait)

By background (the always-on rule vs the on-demand skill)

Investigator: always-on: "cite sources, never infer"; on a match: the full report method.
Analyst: always-on: "no recommendations, comparison only"; on a match: the table build.
Designer: always-on: the brand tokens; on a match: the asset manifest.
Knowledge worker: always-on: "currency as written, never guess"; on a match: the CSV extract.
Reporter: always-on: "attribute every line"; on a match: the weekly briefing.
Content: always-on: the house-voice don'ts; on a match: the post draft.
Form-filler: always-on: "never drop a receipt"; on a match: the allocation run.
Outreach: always-on: "no invented numbers"; on a match: the per-customer proposal.
Exec: always-on: "facts, not editorial"; on a match: the board brief.

Watch for

The five-box grid invites "do I need all of this?" The honest answer: no, not to start. They need one skill on one painful task. Subagents, hooks and MCP are where this goes later, not the first build (patterns.md: set one concrete step). Resist the urge to teach all five.

Lesson 5

Three ways to share: widest reach last

The idea

A skill gets more valuable the more it's shared. Three reaches: commit it to the repo so your team gets it on clone; ship it as a plugin so the community can install it; or push it through enterprise-managed settings so the whole organisation has it at highest priority, for the standards that must be consistent.

Say it like this

"A skill one person uses is handy. The same skill shared across a team is a standard. Three ways out, by reach. Drop it in the project folder and everyone who opens that folder has it. Package it as a plugin for anyone to install. Or, for a firm, an admin pushes it to everyone, at top priority, for the rules that aren't optional. This is the upgrade from 'a tool I use' to 'how our firm works'." (framings.md: skill file as institutional memory; this is where it becomes an institutional asset, not a personal one.)

Pause, then ask

"If your method became the firm's standard, whose work would come out more like yours?"
"Is there a rule in your world that shouldn't be optional for anyone?"

(wait)

By background (what becomes the shared standard)

Investigator: the firm-wide report rules, so every analyst files the same shape.
Analyst: the standard comparison, so every review is defensible the same way.
Designer: the brand and spec rules, shared across the studio on every campaign.
Knowledge worker: the extraction schema, so every month's CSV matches.
Reporter: the briefing format, so every squad's update reads the same.
Content: the house voice, enforced for everyone who writes.
Form-filler: the allocation rules, so no one files differently at quarter end.
Outreach: the proposal format, shared across the BD team.
Exec: the brief format and KPI definitions, standard across every operator.

Watch for

The caption's gotcha is easy to miss and matters once they delegate: subagents start with a clean context and don't inherit your skills, so you list them in the agent's skills: field, and the built-in agents can't use skills at all. Name it once; don't dwell, it's a later concern. For most rooms, the live point is the first reach: commit to the folder, and the team has it.

Lesson 6

When it breaks, it's one of five things

The idea

Run the skills validator first, it catches structure before you debug logic. Then match symptom to fix: not triggering (improve the description, add phrases you'd really type), not loading (named dir, file named exactly SKILL.md, valid YAML), wrong skill used (make descriptions distinct), being shadowed (priority clash, rename or ask the admin), runtime error (deps, chmod +x, forward slashes). Most "won't trigger" problems are just the description.

Say it like this

"When a skill doesn't fire, don't panic and don't read the code. It's almost always the description: Claude couldn't see the link between what you typed and what the skill says it's for. The fix is to add the exact phrases you'd really use. Test it the way you'd actually ask, and any wording that fails to trigger, you add to the description. That single fix solves most of it." (Echoes Claude 101's slide 5: when it's off, it's almost always fixable, and the fix is context the description didn't carry.)

Pause, then ask

"What are the three different ways you'd actually phrase this task out loud?"
"When AI has missed your intent before, was it really wrong, or did it just not know what you meant?"

(wait)

By background (the trigger phrases to feed the description)

Investigator: "background check", "due diligence", "screen this subject", "run the file".
Analyst: "compare these providers", "build the comparison", "vendor review".
Designer: "what assets does this campaign need", "list the variants", "asset manifest".
Knowledge worker: "pull these invoices", "extract to CSV", "process the inbox".
Reporter: "do the Monday briefing", "consolidate the updates", "weekly summary".
Content: "draft a post", "write this up in our voice", "blog this".
Form-filler: "allocate these receipts", "fill the template", "categorise these".
Outreach: "write proposals for these customers", "draft outreach", "one per account".
Exec: "give me the board brief", "one-pager from these inputs", "what needs a decision".

Back to your card

[name], read your skill's description out.
Group, give three ways you'd actually ask for this task. Would it trigger for each?

Watch for

This is the slide that most invites "what is it doing under the hood". Redirect every time: the description is plain English, the validator and claude --debug report by name, and if you want to change behaviour you change the skill file in English, not the code (objections.md: can't read code; what is it doing). The runtime-error row (deps, chmod, slashes) is genuinely developer territory and doesn't vary by domain; flag it as "your developer's department, not yours" and move on rather than forcing nine examples.

Write it once. Describe it well. Let Claude load it when it fits.

The idea

The whole course in one line: a folder and a SKILL.md turn a repeated instruction into automatic, shareable expertise, built lean, placed among the other tools, fixed by its description. The work is the describing, not the coding.

Say it like this

"If you keep one thing: write your method down once, describe well when it should fire, and let Claude load it when it fits. Everything today was a way to make that durable, sharable, and reliable. The rules that lived in someone's head now live on disk, and they come out the same every time."

Close with

Their skill from slide 1, and the next concrete step: "Next time we open your real folder and write that one." Then the session-improvement habit: "at the end, tell it to look back at what we did badly today and save how we fixed it" (framings.md: the system improves through use). For Praxis students, this is where Claude 101 and AI Fluency land: the skill file is the how behind "describe what good looks like, once".