Skills: Teach Your Agent One Thing Well

Agent skills are reusable, composable instruction packages that make your AI agent reliably good at one specific job - without burning context or repeating yourself.

TL;DR: A skill is a small folder with a SKILL.md file that packages instructions, scripts, and context into a named, reusable behavior. Instead of re-explaining "how to deploy" every session, you write it once and invoke it with /deploy. Skills compose, load on-demand, and can run in an isolated subagent so they never clog your main conversation.

What a Skill Actually Is

Think of a skill like an onboarding guide for a new hire - except the hire is your agent, and the guide loads itself whenever it's relevant.

Under Claude Code's skills system, a skill is a directory with one required file: SKILL.md. That file has two parts:

  1. YAML frontmatter between --- markers - tells the agent when to use the skill and how to invoke it.
  2. Markdown body - the actual instructions the agent follows when the skill runs.

The directory name becomes the slash command. Drop a folder at ~/.claude/skills/summarize-changes/SKILL.md and you get /summarize-changes - available across every project you open.

my-skill/
├── SKILL.md         # instructions (required)
├── reference.md     # detailed docs loaded on demand
└── scripts/
    └── helper.py    # scripts Claude can run

Skills follow the open Agent Skills standard, which works across multiple AI tools including Cursor, GitHub Copilot, Gemini CLI, and many others. Claude Code adds extras on top: invocation control, subagent execution, and dynamic context injection.

How Skills Differ from Raw Prompting

When you paste instructions into chat, two things happen: the instructions burn context tokens on every turn, and they disappear the moment you start a new session. Skills solve both problems.

Progressive disclosure - load only what you need

A skill's content loads in layers for default skills:

A 2,000-line reference doc costs almost nothing until the skill activates. That's the opposite of dumping everything into CLAUDE.md, where every word loads every session whether or not you're doing anything related. Note: skills marked disable-model-invocation: true are hidden entirely until you explicitly invoke them - their description doesn't even load into context.

Persistent across sessions

Raw prompting dies when the tab closes. A skill file stays on disk. Your next session - or a teammate opening the same project - gets identical behavior without you repeating yourself.

Safe by design

Skills declare which tools they're allowed to use. An allowed-tools field in the frontmatter pre-approves only the specific commands a skill needs, so Claude doesn't prompt you for permission mid-workflow. A deploy skill can approve specific git commands without opening the door to everything else.

Writing Your First Skill

Here's a real skill that summarizes uncommitted git changes. It uses dynamic context injection - the !`git diff HEAD` line runs a shell command and inserts its output into the prompt before Claude reads it, so the response is grounded in your actual working tree.

---
description: Summarizes uncommitted changes and flags anything risky.
  Use when the user asks what changed, wants a commit message,
  or asks to review their diff.
---

## Current changes

!`git diff HEAD`

## Instructions

Summarize the changes above in two or three bullet points,
then list any risks such as missing error handling, hardcoded
values, or tests that need updating. If the diff is empty,
say there are no uncommitted changes.

Save that to ~/.claude/skills/summarize-changes/SKILL.md and you can trigger it two ways:

That's the whole pattern. One folder, one file, one slash command.

Controlling Who Invokes a Skill

Not every skill should auto-fire. A skill that deploys to production should never run because Claude thought your code "looked ready." Two frontmatter fields give you control:

---
name: deploy
description: Deploy the application to production
disable-model-invocation: true
---

Deploy $ARGUMENTS to production:
1. Run the test suite
2. Build the application
3. Push to the deployment target
4. Verify the deployment succeeded

The $ARGUMENTS placeholder gets replaced with whatever you type after the command. Running /deploy staging sends "Deploy staging to production..." to Claude.

When to Write a Skill vs. Just Asking

The signal is repetition. If you've pasted the same instructions more than twice, it's time for a skill. More specifically:

Where Skills Live and Who Gets Them

Skills can be scoped to you personally or to a specific project:

When skill names collide across levels, enterprise overrides personal, and personal overrides project. Any skill at any of these levels can also override a bundled skill with the same name - for example, a code-review skill in your personal ~/.claude/skills/ or your project's .claude/skills/ replaces the built-in /code-review, letting you override built-in behavior without touching global config.

Claude Code also watches skill directories for changes. Edit a SKILL.md and the updated version takes effect in your current session without a restart.

Advanced Patterns Worth Knowing

Run a skill in an isolated subagent

Add context: fork to the frontmatter and the skill runs in a separate context window. It won't have access to your conversation history, which keeps heavy work from bloating your main session.

---
name: pr-summary
description: Summarize changes in a pull request
context: fork
agent: Explore
allowed-tools: Bash(gh *)
---

## Pull request context
- PR diff: !`gh pr diff`
- PR comments: !`gh pr view --comments`
- Changed files: !`gh pr diff --name-only`

## Your task
Summarize this pull request in plain language...

Pass arguments by position

Use $ARGUMENTS[N] for positional arguments by 0-based index, or the shorthand $N (where $0 is the first argument, $1 the second, and so on). Running /migrate-component SearchBar React Vue with a skill that says "Migrate the $0 component from $1 to $2" fills in exactly what you'd expect.

Reference supporting files

Keep SKILL.md under 500 lines. Move detailed API docs, style guides, or example collections into separate files (reference.md, examples/) and link to them from SKILL.md. Claude loads them only when needed - the skill stays lean, the detail is still there.

Key Takeaways

Try this next: once you have a skill working for a single workflow, learn how to package multiple skills together with hooks and MCP servers into a distributable unit. Agent Plugins: Bundle and Share Your Skills covers the full plugin format so your team - or the community - can install your workflow in one step.

LearntoolkitSkills: Teach Your Agent One Thing Well
Guidetoolkitcore7 min read

Skills: Teach Your Agent One Thing Well

Agent skills are reusable, composable instruction packages that make your AI agent reliably good at one specific job - without burning context or repeating yourself.

CREATORS OF TODAY.
@creatorsoftoday
320

TL;DR: A skill is a small folder with a SKILL.md file that packages instructions, scripts, and context into a named, reusable behavior. Instead of re-explaining "how to deploy" every session, you write it once and invoke it with /deploy. Skills compose, load on-demand, and can run in an isolated subagent so they never clog your main conversation.

What a Skill Actually Is

Think of a skill like an onboarding guide for a new hire - except the hire is your agent, and the guide loads itself whenever it's relevant.

Under Claude Code's skills system, a skill is a directory with one required file: SKILL.md. That file has two parts:

  1. YAML frontmatter between --- markers - tells the agent when to use the skill and how to invoke it.
  2. Markdown body - the actual instructions the agent follows when the skill runs.

The directory name becomes the slash command. Drop a folder at ~/.claude/skills/summarize-changes/SKILL.md and you get /summarize-changes - available across every project you open.

my-skill/
├── SKILL.md         # instructions (required)
├── reference.md     # detailed docs loaded on demand
└── scripts/
    └── helper.py    # scripts Claude can run

Skills follow the open Agent Skills standard, which works across multiple AI tools including Cursor, GitHub Copilot, Gemini CLI, and many others. Claude Code adds extras on top: invocation control, subagent execution, and dynamic context injection.

How Skills Differ from Raw Prompting

When you paste instructions into chat, two things happen: the instructions burn context tokens on every turn, and they disappear the moment you start a new session. Skills solve both problems.

Progressive disclosure - load only what you need

A skill's content loads in layers for default skills:

  • Layer 1 (discovery): The skill's name and description load into context so the agent knows the skill exists and when to use it.
  • Layer 2 (activation): The full SKILL.md body loads when you invoke the skill or when the agent decides it's relevant.
  • Layer 3 (execution): Supporting files referenced in SKILL.md load only when Claude actually needs them.

A 2,000-line reference doc costs almost nothing until the skill activates. That's the opposite of dumping everything into CLAUDE.md, where every word loads every session whether or not you're doing anything related. Note: skills marked disable-model-invocation: true are hidden entirely until you explicitly invoke them - their description doesn't even load into context.

Persistent across sessions

Raw prompting dies when the tab closes. A skill file stays on disk. Your next session - or a teammate opening the same project - gets identical behavior without you repeating yourself.

Safe by design

Skills declare which tools they're allowed to use. An allowed-tools field in the frontmatter pre-approves only the specific commands a skill needs, so Claude doesn't prompt you for permission mid-workflow. A deploy skill can approve specific git commands without opening the door to everything else.

Writing Your First Skill

Here's a real skill that summarizes uncommitted git changes. It uses dynamic context injection - the !`git diff HEAD` line runs a shell command and inserts its output into the prompt before Claude reads it, so the response is grounded in your actual working tree.

---
description: Summarizes uncommitted changes and flags anything risky.
  Use when the user asks what changed, wants a commit message,
  or asks to review their diff.
---

## Current changes

!`git diff HEAD`

## Instructions

Summarize the changes above in two or three bullet points,
then list any risks such as missing error handling, hardcoded
values, or tests that need updating. If the diff is empty,
say there are no uncommitted changes.

Save that to ~/.claude/skills/summarize-changes/SKILL.md and you can trigger it two ways:

  • Type /summarize-changes to invoke it directly.
  • Ask "what did I change?" and Claude loads it automatically because the description matches.

That's the whole pattern. One folder, one file, one slash command.

Controlling Who Invokes a Skill

Not every skill should auto-fire. A skill that deploys to production should never run because Claude thought your code "looked ready." Two frontmatter fields give you control:

  • disable-model-invocation: true - only you can trigger it by typing /skill-name. Claude cannot invoke it on its own, and its description is removed from Claude's context entirely so it's completely invisible to the model until you call it. Use this for anything with side effects: deploy, commit, send-message. It also prevents the skill from being preloaded into subagents.
  • user-invocable: false - only Claude can invoke it. Use this for background reference knowledge that shouldn't show up in the slash menu. A skill explaining your legacy system's quirks is useful context for the agent, but /legacy-context isn't a meaningful action for you.
---
name: deploy
description: Deploy the application to production
disable-model-invocation: true
---

Deploy $ARGUMENTS to production:
1. Run the test suite
2. Build the application
3. Push to the deployment target
4. Verify the deployment succeeded

The $ARGUMENTS placeholder gets replaced with whatever you type after the command. Running /deploy staging sends "Deploy staging to production..." to Claude.

When to Write a Skill vs. Just Asking

The signal is repetition. If you've pasted the same instructions more than twice, it's time for a skill. More specifically:

  • Write a skill when you keep retyping the same procedure, checklist, or multi-step workflow.
  • Write a skill when a section of your CLAUDE.md has grown into a step-by-step procedure rather than a fact about the project. Procedures belong in skills; facts belong in CLAUDE.md.
  • Write a skill when you need the agent to run a script deterministically - things like extracting form fields from a PDF or validating a schema are better handled by code than by token-by-token reasoning.
  • Just ask when the task is one-off, context-specific, or you're still figuring out what the instructions should even be. Skills are for crystallized knowledge, not exploration.

Where Skills Live and Who Gets Them

Skills can be scoped to you personally or to a specific project:

  • ~/.claude/skills/<skill-name>/SKILL.md - personal, available in all your projects
  • .claude/skills/<skill-name>/SKILL.md - project-level, checked into the repo so your whole team gets it
  • Enterprise-managed skills load for all users in an organization

When skill names collide across levels, enterprise overrides personal, and personal overrides project. Any skill at any of these levels can also override a bundled skill with the same name - for example, a code-review skill in your personal ~/.claude/skills/ or your project's .claude/skills/ replaces the built-in /code-review, letting you override built-in behavior without touching global config.

Claude Code also watches skill directories for changes. Edit a SKILL.md and the updated version takes effect in your current session without a restart.

Advanced Patterns Worth Knowing

Run a skill in an isolated subagent

Add context: fork to the frontmatter and the skill runs in a separate context window. It won't have access to your conversation history, which keeps heavy work from bloating your main session.

---
name: pr-summary
description: Summarize changes in a pull request
context: fork
agent: Explore
allowed-tools: Bash(gh *)
---

## Pull request context
- PR diff: !`gh pr diff`
- PR comments: !`gh pr view --comments`
- Changed files: !`gh pr diff --name-only`

## Your task
Summarize this pull request in plain language...

Pass arguments by position

Use $ARGUMENTS[N] for positional arguments by 0-based index, or the shorthand $N (where $0 is the first argument, $1 the second, and so on). Running /migrate-component SearchBar React Vue with a skill that says "Migrate the $0 component from $1 to $2" fills in exactly what you'd expect.

Reference supporting files

Keep SKILL.md under 500 lines. Move detailed API docs, style guides, or example collections into separate files (reference.md, examples/) and link to them from SKILL.md. Claude loads them only when needed - the skill stays lean, the detail is still there.

Key Takeaways

  • A skill is a folder with a SKILL.md file. The directory name becomes a slash command.
  • Skills load progressively - descriptions cost almost nothing; full content only loads when invoked. With disable-model-invocation: true, even the description is hidden from Claude until you explicitly call it.
  • Use disable-model-invocation: true for anything with side effects. Never let an agent auto-deploy.
  • Personal skills live at ~/.claude/skills/. Project skills live at .claude/skills/ and can be committed to the repo. Any level can override a bundled skill by using the same name.
  • The write-a-skill trigger is repetition: if you've pasted the same instructions twice, codify it.
  • Skills compose naturally. Claude can load multiple skills together for tasks that cross domains.
  • Supporting files (reference.md, scripts) can be bundled in the skill folder and load on demand - no context cost until you actually need them.

Try this next: once you have a skill working for a single workflow, learn how to package multiple skills together with hooks and MCP servers into a distributable unit. Agent Plugins: Bundle and Share Your Skills covers the full plugin format so your team - or the community - can install your workflow in one step.

References & sources

Reviews

Only verified humans can leave reviews. It keeps every rating real.

Verify to review

No reviews yet. Be the first to share your take.