# Agent Skills: Reusable Prompts in Claude Code

> Skills are reusable markdown files that teach Claude Code how to handle specific tasks automatically, so you stop repeating the same instructions every conversation. Each skill is a directory with a SKILL.md declaring name + description, and Claude semantically matches incoming requests against descriptions to load the right skill on demand. The course walks through creating a skill, advanced configuration (allowed-tools, multi-file progressive disclosure), how skills relate to CLAUDE.md, subagents, hooks, and MCP, plus how to share and troubleshoot them.

**Domain:** D1 · Agentic Architectures (27%)
**Difficulty:** intro
**Skilljar course:** Introduction to Agent Skills (6 lessons)
**Canonical:** https://claudearchitectcertification.com/knowledge/agent-skills-intro
**Last reviewed:** 2026-05-06

## Exam mapping

**Blueprint share:** 27% (D1) + 18% (D2)

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.

## What you'll learn

- 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

## Prerequisites

- **Claude Code 101 (knowledge)** (knowledge · `claude-code-101`)
- **Skills (concept)** (concepts · `skills`)
- **CLAUDE.md hierarchy (concept)** (concepts · `claude-md-hierarchy`)

## Lesson outline

### 1. What are skills?

Skills are folders of instructions Claude Code discovers and applies automatically; if you find yourself repeating instructions, that is a skill waiting to be written.

### 2. Creating your first skill

Create a SKILL.md with name + description frontmatter, drop it in ~/.claude/skills/<name>/, restart Claude Code to pick it up.

### 3. Configuration and multi-file skills

Add allowed-tools for capability restriction, use progressive disclosure to keep SKILL.md small and link to supporting files.

### 4. Skills vs. other Claude Code features

Skills are on-demand and request-driven; CLAUDE.md is always-on, subagents are isolated execution, hooks are event-driven, MCP is external tools.

### 5. Sharing skills

Personal in ~/.claude/skills, project (committed) in .claude/skills, plugins for distribution, managed settings for enterprise rollout.

### 6. Troubleshooting skills

Use the skills validator first; if it does not trigger, fix the description; if it does not load, check SKILL.md is in a named directory.

## Our simplification

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.

## Patterns

### Skills vs CLAUDE.md vs subagents vs hooks vs MCP

The single most-tested skills concept is which feature fits which job. Memorize the load model and the trigger.

- **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.
- **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.
- **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.
- **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.
- **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.

## Key takeaways

- Skills are markdown files that Claude Code loads on demand when your request matches their description, so they cost zero context tokens until activated. (`skills`)
- Personal skills go in ~/.claude/skills, project skills go in .claude/skills (committed to git), and the priority hierarchy is Enterprise > Personal > Project > Plugins. (`skills`)
- The description field is the load-bearing decision input; write it to answer two questions: what does the skill do, and when should Claude use it. (`agent-skills-for-enterprise-km`)
- Use allowed-tools to restrict capabilities while a skill is active and use progressive disclosure (sub-500-line SKILL.md plus linked support files) to keep large skills efficient. (`skills`)
- Skills are knowledge-injection; subagents are isolated execution; hooks are event-driven automation; CLAUDE.md is always-on standards; MCP is external tools, and each handles its own specialty. (`agent-skills-for-developer-tooling`)
- When a skill does not trigger, the description is almost always the cause; add the trigger phrases users actually type and run the skills validator first when debugging. (`skills`)

## Concepts in play

- **Skills** (`skills`), Core primitive the course centers on
- **CLAUDE.md hierarchy** (`claude-md-hierarchy`), The always-on alternative skills complement
- **Subagents** (`subagents`), Isolated execution alternative for delegation
- **Hooks** (`hooks`), Event-driven alternative for automation
- **MCP** (`mcp`), External tool surface that pairs with skills

## Scenarios in play

- **Agent skills for enterprise KM** (`agent-skills-for-enterprise-km`), Enterprise rollout pattern: managed settings, shared brand and policy skills
- **Agent skills for developer tooling** (`agent-skills-for-developer-tooling`), Team-shared project skills for code review, commit format, debugging checklists
- **Agent skills with code execution** (`agent-skills-with-code-execution`), Progressive disclosure pattern using scripts that return data without loading source

## Curated sources

- **Equipping agents for the real world with Agent Skills** (anthropic-blog, 2025-10-16): Anthropic's launch announcement framing the why behind skills, including the progressive-disclosure design choice. Pair with the Skilljar lessons for the architectural rationale.
- **Agent Skills: Anthropic Claude Code documentation** (anthropic-blog, 2025-10-20): Canonical reference for the SKILL.md schema, allowed-tools, progressive disclosure, and the priority hierarchy. The doc you bookmark when authoring real skills.

## FAQ

### Q1. 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.

### Q2. 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.

### Q3. 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.

### Q4. 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.

### Q5. 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.

### Q6. 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.

### Q7. 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.

### Q8. 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.

---

**Source:** https://claudearchitectcertification.com/knowledge/agent-skills-intro
**Vault sources:** Course_15/_Course_Overview.md; Course_15/Lesson_01_what-are-skills.md; Course_15/Lesson_02_creating-your-first-skill.md; Course_15/Lesson_03_configuration-and-multi-file-skills.md; Course_15/Lesson_04_skills-vs-other-claude-code-features.md; Course_15/Lesson_05_sharing-skills.md; Course_15/Lesson_06_troubleshooting-skills.md
**Last reviewed:** 2026-05-06