What Anthropic teaches in this course
Skills exist because every Claude Code user eventually notices they are typing the same instructions over and over. Every PR review, you re-describe how you want feedback structured. Every commit, you remind Claude of your message format. Skills fix this by letting you write a markdown file once that Claude applies automatically the next time the task comes up. The mental model is npm install for Claude's task-specific knowledge: scoped, on-demand, version-controlled.
Mechanically a skill is a directory containing a SKILL.md. The file has YAML frontmatter declaring at minimum name and description, then markdown instructions below. The description is load-bearing: at startup Claude Code loads only the names and descriptions of every available skill (cheap, no token cost). When you make a request, Claude semantically matches your phrasing against those descriptions and loads the full body of the matching skill into context. You see a confirmation prompt before the load. Skills are inert until they match.
Skills live in two places: personal at ~/.claude/skills/<skill-name>/ (follows you across all projects on your machine) and project at .claude/skills/<skill-name>/ inside a repo (committed to git, shared with everyone who clones). When names conflict, the priority hierarchy is Enterprise → Personal → Project → Plugins. Use personal for your own commit-message style or PR-review preferences; use project for team standards like coding conventions, brand guidelines, or framework-specific debugging checklists. Restart Claude Code after creating or editing a skill so it picks up the change.
Advanced configuration unlocks the production-grade use cases. allowed-tools restricts which tools Claude can use while the skill is active; set [Read, Grep, Glob] for a code-review skill so the reviewer cannot edit files even if the prompt drifts. model lets a skill request a specific Claude model. Progressive disclosure is the technique that keeps skills efficient: keep SKILL.md under 500 lines, and put deep references, scripts, and assets in sibling files that Claude reads on demand. The trick: Claude can execute a script and consume only its output, never the script's source, so a 2,000-line tax-rules-by-state lookup costs zero context tokens until the output lands.
Skills versus everything else is the question every team asks and the exam loves to test. CLAUDE.md loads into every conversation; use it for project-wide always-on standards (TypeScript strict mode, never modify the schema). Skills load on demand; use them for task-specific expertise that would clutter every conversation if it lived in CLAUDE.md. Subagents run in an isolated context with their own tool access; use them when you want delegation, not knowledge injection. Hooks fire on events (file save, tool call); use them for automation, not reasoning. MCP provides external tools; a different category entirely from skills. The right setup combines all of them.
Sharing scales the value. A personal skill stays on your machine. A project skill gets committed alongside the code; the next teammate who clones the repo gets it free. Plugins package a set of related skills (plus optional commands and config) for distribution outside a single repo. Managed settings let an enterprise admin push a skill set to every user's Claude Code installation, with the highest priority in the hierarchy. The shape that emerges is: personal skills are your habits, project skills are your team's standards, plugin skills are community contributions, enterprise skills are policy.
Troubleshooting follows a predictable pattern. Run the skills validator first; it catches structural problems (missing frontmatter, wrong filename, directory shape) faster than any other technique. If a skill does not trigger, the description is almost always the cause; add the trigger phrases users actually type. If it does not load, check that SKILL.md lives inside a named directory and that the filename is exactly SKILL.md (case-sensitive). If the wrong skill activates, two descriptions are too similar; disambiguate. For runtime errors in skill scripts, check dependencies, file permissions (chmod +x), and use forward slashes in paths. The exam treats skills as a recognition problem more than a creation problem. You will see scenarios describing team pain (a brand-guidelines doc Claude keeps missing, a PR-review style that drifts) and be asked which Claude Code feature solves it. Skill is the right answer when the knowledge is task-specific and on-demand; CLAUDE.md when it should always apply; subagent when you want isolation; hook when an event triggers automation; MCP when you need an external system.
You'll walk away with
- What a skill is, where it lives (personal ~/.claude/skills vs project .claude/skills), and how Claude Code matches one to a request
- How to author a SKILL.md with name, description, and instructions that reliably trigger when the task comes up
- Advanced fields: allowed-tools for restricting capabilities and model for routing to a specific Claude model
- Progressive disclosure: keeping SKILL.md under 500 lines and linking to supporting files Claude reads only when needed
- When to use skills versus CLAUDE.md, subagents, hooks, or MCP, and how they complement each other
- How to share skills via repo commits, plugins, or enterprise managed settings, and how to troubleshoot when one does not trigger
6 lessons, with our annotations
6 ideas to carry into practice
Lines worth keeping
CLAUDE.md: always-on standards
Loads into every conversation. Use for project-wide constraints (TypeScript strict, never modify schema, framework preferences). Token cost on every turn, so keep it tight.
Related concept →Skills: on-demand, request-driven
Loads only when Claude matches a request to the skill's description. Use for task-specific expertise (PR review style, commit format, debugging checklists). Cost is zero until activated.
Related concept →Subagents: isolated execution
Runs in a separate context window with its own tool access; returns only a summary. Use for delegation, not knowledge injection. Cleaner parent context, less debuggability.
Related concept →Hooks: event-driven automation
Fires on events (file save, tool call). Use for side effects: linters, validators, telemetry. Not for reasoning. Configured in settings.json, not markdown.
Related concept →MCP: external tools
Provides callable capabilities from a separate server. Use for connecting Claude to systems outside the conversation. A different category entirely; complement skills, do not replace them.
Related concept →How this course shows up on the exam
Direct prep for D1 task statements on Claude Code customization features and D2 questions on choosing the right primitive for the job. Skills appear in agent-skills-for-enterprise-km, agent-skills-for-developer-tooling, and agent-skills-with-code-execution scenarios.
Blueprint weight27% (D1) + 18% (D2)Check the pattern
A teammate's PRs use a different code style than yours. They have rules in ~/.claude/CLAUDE.md but not in the repo. What is the architectural fix?
Frequently asked
What are agent skills in Claude Code and how are they different from CLAUDE.md?
Skills are reusable markdown files that Claude Code loads on demand when your request matches the skill's description. CLAUDE.md loads into every conversation always. Use CLAUDE.md for project-wide standards that always apply (TypeScript strict mode); use skills for task-specific expertise that would clutter every conversation if it lived in CLAUDE.md.
How do I create my first skill in Claude Code?
Create a directory at ~/.claude/skills/<skill-name>/ (personal) or .claude/skills/<skill-name>/ (project). Inside, create a SKILL.md with YAML frontmatter declaring name and description, then write the instructions below the frontmatter. Restart Claude Code so it discovers the new skill. Verify it loads by making a request that should trigger it; you will see a confirmation prompt.
Why is my skill not triggering when I make a request?
The cause is almost always the description. Claude matches your request semantically against skill descriptions, so vague or generic descriptions miss real-world phrasings. Add the trigger phrases users actually type ('use when reviewing PRs', 'use when writing commit messages'). Also run the skills validator first; it catches structural issues (missing frontmatter, wrong filename, wrong directory shape) before you waste time on the description.
Where do skills live and how does Claude Code find them?
Personal skills go in ~/.claude/skills/<skill-name>/ and follow you across every project on your machine. Project skills go in .claude/skills/<skill-name>/ inside a repo and are committed to version control so the team shares them. At startup Claude Code loads only the names and descriptions of every skill it finds; the full body loads on demand when a request matches.
What is progressive disclosure in agent skills?
Progressive disclosure is the technique of keeping SKILL.md small (under 500 lines) and linking to supporting files Claude reads only when needed. The trick: Claude can execute a script and consume only its output, not the script's source. A 2,000-line lookup table costs zero context tokens until the output lands. Use this pattern for any skill that would otherwise bloat the context window.
When should I use a skill versus a subagent versus a hook?
Use a skill when you want to inject task-specific knowledge into the current conversation. Use a subagent when you want to delegate work to a separate context with its own tool access (returns only a summary). Use a hook when you want automated side effects on events (file save, tool call). Skills inform reasoning; subagents do work; hooks do automation. They are complementary, not alternatives.
How do I share a skill with my team?
Put the skill directory in .claude/skills/<skill-name>/ inside the repo and commit it. Anyone who clones the repo gets the skill automatically. For broader distribution, package related skills as a plugin. For enterprise-wide rollout, use managed settings to push skills to every user's Claude Code installation; managed-setting skills sit at the top of the priority hierarchy.
Can I restrict which tools a skill is allowed to use?
Yes. Add an allowed-tools field to the skill's frontmatter listing only the tools Claude can use while the skill is active. For a code-review skill, set allowed-tools: [Read, Grep, Glob] so the reviewer cannot edit files even if the prompt drifts. The whitelist is your safety contract; relying on prompt-only constraints is the canonical anti-pattern.