Agent Skills, and the eight questions the course is really asking

Introduction to agent skills is Anthropic's free, self-paced course on Claude Code skills. Six lessons, no stated prerequisites, and completion certificates for people who finish. The lesson titles below are the course's own.

Here is the part the course does not lead with, and the reason this is worth your evening. Agent Skills is no longer a Claude Code feature. Anthropic released the format as an open standard, and it has been picked up across the industry: GitHub Copilot, VS Code, Cursor, OpenAI Codex, Gemini CLI, Amp, Goose, OpenCode, JetBrains Junie and roughly forty others now read the same SKILL.md.

The pain point is repetition. If you have explained your bug-report format to Claude three times this week, you have found a skill. The rule of thumb from the course is exactly that: anything you have explained three times is a candidate.

A skill is a folder. Inside it, a file called SKILL.md that opens with YAML frontmatter and continues with ordinary Markdown. The frontmatter decides when Claude reaches for the skill. The body decides what happens when it does.

Two details in that picture earn their place. First, the folder name is what you type: a skill at .claude/skills/flaky-triage/ is invoked as /flaky-triage. Second, SKILL.md is that exact spelling, uppercase name and lowercase extension, and it must sit inside the named folder rather than loose at the skills root. Both are common first-attempt mistakes.

This is the single idea the rest of the course rests on, and the one most people get half right.

At startup the agent loads a listing of every available skill: names and descriptions only. That listing is cheap. When your request semantically matches one of those descriptions, the full SKILL.md body is read into the conversation.

The consequence is the thing to remember. The quality of the skill body has no bearing on whether the skill fires. Claude has not read it yet. Only the description is in the room when the decision is made. A brilliant 400-line checklist behind a description that says "helps with testing" will sit there unused all week.

It is also why skills scale where CLAUDE.md does not. A twentieth skill costs one more line in the listing. A twentieth section of CLAUDE.md costs its full length in every conversation you ever have, including the ones about something else entirely.

Given the section above, the description is the highest-leverage line in the file, and it is worth more attention than the body on a first draft.

A good description answers two questions: what does this do, and when should it be used. Write the second half in the words you actually type, not the words you would use in documentation.

description: Helps with docs.

That tells the agent as little as it would tell a new hire. Compare:

description: Writes pull request descriptions in the team format.
  Use when creating a PR, writing a PR, summarising changes on a
  branch, or when asked what changed since main.

Four phrasings, because you will not use the same one twice. Matching is semantic rather than keyword-based, so intent overlap is enough. But breadth still helps: every phrasing you add is another way in.

Two failure modes, and their fixes:

• The skill never fires. Test your own variations. "Why is this slow", "profile this", "make this faster" should all reach a performance skill. Any variation that misses is a phrase to add.
• The wrong skill fires. Two descriptions overlap. Make them distinct rather than merely accurate. frontend-review and api-review beat two skills that both say "reviews code".

Where you put the folder decides who gets it.

On Windows the personal path is C:/Users/<you>/.claude/skills. Use forward slashes in skill content regardless of platform.

When two skills share a name, enterprise beats personal, and personal beats project. Read that middle one twice, because it is the useful one: cloning a repository cannot quietly replace a convention you set for yourself. Plugin skills sit outside the contest entirely, namespaced as plugin-name:skill-name, so they load alongside rather than fighting for the bare name.

There are two answers to "which fields are required", and knowing which one you are being asked about is most of the battle.

The portable answer: the Agent Skills spec

If the skill has to work in Copilot, Cursor, Codex or anything else that reads the open format, the spec is binding and narrow:

The Claude Code answer

Claude Code accepts every spec field plus a long list of its own, and it is looser about what you must supply. In Claude Code all frontmatter fields are optional; description is merely recommended, and name defaults to the directory name. The fields worth knowing beyond the spec:

An activated skill loads its whole SKILL.md. A single 2,000-line file is expensive on every invocation and miserable to maintain. The fix is structural.

Keep SKILL.md to the essential instructions plus pointers, and split the detail into files that get read only when they are needed. The conventional layout is scripts/ for executable code, references/ for documentation, assets/ for templates and data.

The part people miss is the loading condition. Do not just link the file, say when to open it:

For the full architecture, read references/architecture.md.
Read it only when the question is about system design, not
when the question is where to put a new component.

Scripts are the sharper trick. A script can be executed without its contents ever entering context, so only the output costs tokens. That suits environment checks, transformations that must be identical every time, and anything more reliable as tested code than as freshly generated code. The instruction has to say run this, not read this.

The published targets: metadata around 100 tokens, an activated body under about 5,000 tokens, and SKILL.md under 500 lines.

Lesson 4 is a selection problem, and it is the lesson that pays off fastest in a real repository.

The distinction that gets muddled most often is skill against hook. Hooks are event-driven and deterministic; skills are request-driven and advisory. If it must happen every single time regardless of what anyone asks, that is a hook. If it should shape how Claude reasons when the topic comes up, that is a skill.

The second most muddled is skill against subagent. A skill adds knowledge to the conversation you are already in. A subagent goes away, works in its own context, and comes back with a result. Delegation is a subagent. Expertise is a skill.

MCP is not really on this list at all. It is a transport for external tools, not a way to shape behaviour. A mature setup runs all five and lets each do the one thing it is good at.

This is the sharpest gotcha in the course, and it is worth understanding in both directions.

Subagents do not inherit your skills. They start with a fresh context. A skill that works perfectly in normal conversation is simply absent when you delegate to a subagent, and no amount of prompt wording brings it back.

To give a custom subagent specific expertise, list it explicitly. Subagents are Markdown files in .claude/agents, or you can create one with /agents:

---
name: frontend-reviewer
description: Reviews frontend code for accessibility and performance.
tools: Read, Grep, Glob
skills:
  - accessibility-audit
  - performance-check
---

Note what that does: the listed skills are injected in full at subagent startup, not loaded on demand. Every task that agent handles carries them. That is the point, and it is also the cost.

The built-in agents (Explore, Plan, general-purpose, Verify) do not preload skills at all. The course puts this more strongly, saying built-in agents cannot access skills whatsoever; the current documentation is narrower, in that they do not preload, but can still invoke a skill through the Skill tool unless it has been removed from their tools. Either way, if you need guaranteed expertise in delegated work, write a custom subagent.

The reverse direction is newer than the course. Put context: fork on a skill and the skill itself runs in a subagent, with the skill body as the prompt and an agent field choosing the execution environment. That only makes sense for skills that contain an actual task; a skill of guidelines forked into a subagent gives it instructions and nothing to do.

Three channels, in ascending order of how much you are willing to enforce.

Commit it

Put the skill in .claude/skills/ and push. Anyone who clones the repo has it, with no install step, and updates arrive on the next pull. Best for team standards and anything that references your codebase structure. The whole .claude directory travels this way: agents, hooks, skills, settings.

Ship it as a plugin

Mirror the same layout inside a plugin, publish to a marketplace, and other teams can install it. Best when the skill is genuinely useful outside your repository. Plugin skills stay namespaced, so they never collide with what people already have.

Mandate it through managed settings

Enterprise skills carry the highest priority and override personal and project skills of the same name. This is the channel for things that must be uniform: security review standards, compliance workflows. Managed settings also carry related controls, such as restricting which marketplaces plugins may come from:

"strictKnownMarketplaces": [
  { "source": "github", "repo": "acme-corp/approved-plugins" },
  { "source": "npm", "package": "@acme-corp/compliance-plugins" }
]

Pick by the operative word. Committing to a repo is available. A plugin is installable. Managed settings are mandatory, and note that a per-repo skill cannot deliver "no opt-out": a personal skill of the same name would take precedence over it.

Almost every failure resolves to one of four symptoms, and each points at a different file.

Validate before you debug behaviour. It catches the structural faults in seconds:

claude plugin validate ~/.claude/skills
claude plugin validate .claude/skills

For portable skills, the reference implementation of the open standard has its own validator, skills-ref validate ./my-skill.

Skip the PR-description example from the course; you have written one before. Here is a skill that earns its place in a test repository on day one, because flaky triage is the task everyone does inconsistently.

mkdir -p .claude/skills/flaky-triage

---
name: flaky-triage
description: Diagnose and classify a flaky test. Use when a test
  passes locally but fails in CI, when a test fails intermittently,
  when someone says a test is flaky, or when asked to investigate
  a red build that goes green on re-run.
---

When triaging a flaky test:

1. Re-run the test 20 times in isolation and record the failure rate.
   Use scripts/rerun.sh rather than running it by hand.
2. Re-run it 20 times as part of the full suite. A test that only
   fails in the suite is an ordering or shared-state problem.
3. Diff a passing trace against a failing one.
4. Classify it as one of: timing, ordering, shared data, or
   environment. Say which, and give the evidence.
5. Propose the smallest change that removes the race. Do not
   propose a retry, and do not propose an increased timeout,
   unless step 4 concluded the environment is genuinely slow.
6. If the root cause is a product bug rather than a test bug,
   say so plainly and stop.

For the retry and wait patterns this codebase already uses, read
references/retry-patterns.md, but only when proposing a fix.

Four things in there are deliberate, and they are the transferable part:

• The description lists four real phrasings. Nobody walks up and says "perform flaky triage". They say "this keeps failing in CI".
• Step 1 points at a script. Twenty runs is exactly the kind of work that should be executed rather than reasoned about, and the output is all that reaches context.
• Step 5 forbids the lazy fix. Standing instructions are where you encode judgement, not just procedure. A retry that hides a race is how flaky suites become permanent.
• The reference file carries a condition. It is read when proposing a fix, not during diagnosis.

Commit it. Everyone who clones the repo now triages the same way, and the argument about whether to add a retry happens once, in review of this file, rather than every sprint.

The course is sound on concepts. Some of the specifics have moved since it was recorded, and two are worth correcting in your own notes rather than just noting in passing. Take the quiz on the course's answers; build on these.

And the material that simply postdates the course: context: fork and agent for running a skill in a subagent, paths for glob-scoped activation, disable-model-invocation and user-invocable for controlling who can invoke, when_to_use for extra trigger phrases, $ARGUMENTS and argument-hint for parameterised skills, hooks in skill frontmatter, and Skill(name) permission rules for allowing or denying individual skills.

These cover the assessed material rather than reproducing the course's own quiz. Answers are hidden. Try each one before opening it.