Skills

Level: 🌿 Intermediate Source: Skills

← Back to Automating Your Workflows

Skills are Markdown instruction files that extend what Claude can do. Create a SKILL.md file with instructions, and Claude adds it to its toolkit. Skills are your primary tool for creating reusable prompts, coding standards, deployment playbooks, and custom workflows.

Note: Slash commands (like custom /deploy or /review) are simply Skills with a name. Built-in slash commands like /compact and /help are covered in the Built-ins page. The .claude/commands/ directory still works, but Skills (in .claude/skills/) are the recommended approach going forward.

Bundled skills — Claude Code ships with several built-in skills: /simplify, /batch, /debug, /loop, and /claude-api. These are always available without any configuration.

When to Use Skills

Think “skills” when you catch yourself saying:

  • “I want Claude to always follow our team’s coding conventions”
  • “I need a repeatable deployment process I can trigger with a command”
  • “Claude should explain code with diagrams and analogies when I ask”
  • “I want a code review checklist that Claude follows every time”
  • “I need a slash command that generates boilerplate for our API endpoints”

Skills are proactive — they teach Claude how to do something, rather than reacting to what Claude does.

Key Concepts

SKILL.md — Every skill needs a SKILL.md file inside a named directory. The file has two parts: YAML frontmatter (between --- markers) for configuration, and Markdown content with instructions.

Frontmatter — Optional YAML that controls skill behavior: name, description, argument-hint, disable-model-invocation, user-invocable, allowed-tools, model, context, agent, and hooks.

Invocation — Skills can be invoked manually via /skill-name or automatically when Claude decides the skill is relevant based on its description.

Arguments — Use $ARGUMENTS in your skill content to accept input. Running /fix-issue 123 replaces $ARGUMENTS with 123. Additional substitutions: $ARGUMENTS[N] or $N for indexed access (e.g., $1 for the first argument), ${CLAUDE_SESSION_ID} for the current session ID, and ${CLAUDE_SKILL_DIR} for the skill’s directory path.

Scope — Skills can be personal (~/.claude/skills/), project-level (.claude/skills/), or enterprise-managed.

Getting Started: Your First Skill

Create a skill that teaches Claude to explain code with diagrams:

1. Create the directory 

mkdir -p .claude/skills/explain-code

2. Write SKILL.md

Create .claude/skills/explain-code/SKILL.md:

---
name: explain-code
description: Explains code with visual diagrams and analogies. Use when explaining how code works.
---

When explaining code, always include:

1. **Start with an analogy**: Compare the code to something from everyday life
2. **Draw a diagram**: Use ASCII art to show the flow or structure
3. **Walk through the code**: Explain step-by-step what happens
4. **Highlight a gotcha**: What's a common mistake or misconception?

3. Test it

Invoke it directly:

/explain-code src/auth/login.ts

Or let Claude invoke it automatically by asking: “How does this code work?”

Common Patterns

Deployment playbook (manual invocation only) 

---
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 disable-model-invocation: true means only you can trigger this with /deploy.

Code review checklist 

---
name: review
description: Review code for quality, security, and best practices
---

Review the code and check:
- Readability and naming
- Error handling
- Security (no exposed secrets, input validation)
- Test coverage
- Performance considerations

Provide feedback organized by priority: Critical, Warnings, Suggestions.

Skill that runs in a sub agent (forked context) 

---
name: deep-research
description: Research a topic thoroughly
context: fork
agent: Explore
---

Research $ARGUMENTS thoroughly:
1. Find relevant files using Glob and Grep
2. Read and analyze the code
3. Summarize findings with specific file references

The context: fork runs this in an isolated sub agent, keeping your main conversation context clean.

Skill with dynamic context injection 

---
name: pr-summary
description: Summarize a pull request
context: fork
agent: Explore
---

## Pull request context
- PR diff: !\`gh pr diff\`
- PR comments: !\`gh pr view --comments\`

Summarize this pull request...

The !\command`` syntax runs shell commands before the skill content is sent to Claude.

Where Skills Live

Location Path Applies to
Personal ~/.claude/skills/<name>/SKILL.md All your projects
Project .claude/skills/<name>/SKILL.md This project only
Enterprise Managed settings All users in your org
Plugin <plugin>/skills/<name>/SKILL.md Where plugin is enabled

Higher-priority locations win when names conflict: enterprise > personal > project.

Controlling Invocation

Frontmatter You can invoke Claude can invoke
(default) Yes Yes
disable-model-invocation: true Yes No
user-invocable: false No Yes

Next Steps

Claude and Claude Code are products of Anthropic, PBC. This guide is a community project and is not affiliated with or endorsed by Anthropic. Original content is licensed under CC BY 4.0 — the license does not cover Anthropic's product or official documentation.

This site uses Just the Docs, a documentation theme for Jekyll.