skills: packaged expertise

the problem skills solve

Module 1 gave you CLAUDE.md: the rules that apply to every session in a project. But some knowledge only matters for some tasks: how to write a good animation, how your team deploys, what a proper email template looks like. Paste that into CLAUDE.md and you pay for it in context (the amount of text the model considers at once – covered in module 1) on every single session, including the ones that never touch it.

A skill (a folder with a SKILL.md instruction file that the agent loads only when the task matches its description) is the fix: packaged expertise that loads on demand. The official docs describe it as a SKILL.md file with instructions: "Claude adds it to its toolkit. Claude uses skills when relevant, or you can invoke one directly with /skill-name."

how a skill actually loads

The mechanism is the whole trick, and it's called progressive disclosure:

1. at session start only the skill's description line enters the context: a sentence, not the manual
2. when a task matches that description, the agent loads the full SKILL.md
3. supporting files (templates, scripts, reference docs) load only if the instructions point to them

So a library of 50 skills costs you 50 sentences of standing context, not 50 manuals. OpenAI's Codex documents the same three-stage pattern. Skills are an open standard that works across agents, not a vendor feature.

anatomy of a SKILL.md

A skill lives at .claude/skills/<name>/SKILL.md (project) or ~/.claude/skills/<name>/SKILL.md (all your projects). Two parts:

• frontmatter – the description decides everything: it is how the agent recognizes "this task is mine". Vague description, dead skill.
• markdown body – the instructions themselves: steps, standards, gotchas, links to supporting files.

Two frontmatter switches worth knowing from day one (reference): disable-model-invocation: true means only you can trigger it with /name. Use it for side-effect workflows like deploys, where the agent shouldn't decide the timing. user-invocable: false is the inverse: background knowledge the agent should apply but that makes no sense as a command.

what it looks like in production

This platform is built under a rule in AGENTS.md: no UI work starts before the design skills are loaded. The skill contents carry the standards; the session just names them:

The skills weren't written that day. They were written once, and every session since starts at that level instead of from zero.

what you take with you

• a skill is packaged knowledge loaded on demand – CLAUDE.md keeps only what is always needed
• the description decides everything: it is how the agent recognizes the task as its own
• side-effect workflows get disable-model-invocation: only you can trigger them

exercise

❯ exercise — write your first skill

Pick one thing you've explained to the agent more than once (a workflow, a standard, a checklist) and turn it into a skill in your own project.

• ○the skill lives at .claude/skills/<name>/SKILL.md with frontmatter and body
• ○the description says what it does AND when to use it – specific enough to trigger
• ○you tested the trigger: a matching request loads the skill without you naming it
• ○side-effect workflows (deploy, publish) got disable-model-invocation: true

0/4 · log in so we can save your progress