CLAUDE CODE SKILLS

1. What Is a Skill?

Think of a Skill as a reusable instruction pack for Claude Code.

2. When Should You Create a Skill?

• You keep pasting the same instructions.
• You have a repeated checklist or multi-step procedure.
• A large section of CLAUDE.md has become a procedure rather than a fact.
• You want a reusable /command.
• You want Claude to automatically recognize a specialized workflow.

3. Skill Anatomy

.claude/
└── skills/
    └── summarize-changes/
        └── SKILL.md

Every Skill needs SKILL.md. It has YAML frontmatter followed by Markdown instructions.

---
name: summarize-changes
description: Summarize uncommitted changes and flag risks.
---

## Current changes
!`git diff HEAD`

## Instructions
Summarize the changes in 2–3 bullets.
Flag risks and tests that need updating.

4. Create Your First Skill

Step 1 — Create directory

mkdir -p ~/.claude/skills/summarize-changes

Step 2 — Create SKILL.md

---
description: Summarizes uncommitted changes and flags risky changes.
---

## Current changes
!`git diff HEAD`

## Instructions
Summarize the changes in two or three bullets.
List risks such as missing error handling, hardcoded values,
or tests that need updating.

Step 3 — Use it

claude
What did I change?

Or:

/summarize-changes

5. Where Skills Load

6. Monorepos & Nested Skills

Claude Code loads project Skills from the start directory and parent directories up to the repository root. Skills below the start directory can become available when Claude first works with files there; supported versions can also use /add-dir to load them sooner.

repo/
├── .claude/skills/deploy/SKILL.md
└── apps/web/.claude/skills/frontend-test/SKILL.md

If names collide, both can remain available and nested Skills may have qualified commands such as:

/apps/web:deploy

7. Skill Command Names

.claude/skills/deploy-staging/SKILL.md
→ /deploy-staging

For plugins, Skills are namespaced:

/my-plugin:review

8. Frontmatter Reference

9. The Two Most Important Invocation Controls

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

---
name: legacy-context
description: Explains the legacy system
user-invocable: false
---

10. Reference Skill vs Task Skill

11. Supporting Files

my-skill/
├── SKILL.md
├── reference.md
├── examples.md
└── scripts/
    └── helper.py

Keep SKILL.md focused and point Claude to detailed files:

## Additional resources
- Complete API details: reference.md
- Usage examples: examples.md

12. Arguments

$ARGUMENTS

---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
---

Fix GitHub issue $ARGUMENTS.

/fix-issue 123

Indexed arguments

---
name: migrate-component
description: Migrate a component
---

Migrate $0 from $1 to $2.

/migrate-component SearchBar JavaScript TypeScript

13. Named Arguments

---
name: migrate-component
description: Migrate a component
arguments: [component, from, to]
---

Migrate $component from $from to $to.

Run:

/migrate-component SearchBar JavaScript TypeScript

14. Stack Multiple Skills

/write-tests /fix-issue 123

Current Claude Code can expand the first Skill plus up to five more stacked inline user-invocable Skills. Expansion stops when a token is not another inline Skill.

15. Dynamic Context Injection

The !`command` syntax runs a shell command before the Skill content is sent to Claude. The command output replaces the placeholder.

---
name: pr-summary
description: Summarize a pull request
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`

## Task
Summarize this pull request.

16. Multi-line Dynamic Commands

## Environment
```!
node --version
git status --short
npm test
```

Injected commands run before Claude sees the rendered Skill content.

17. Shell Behavior & Failures

18. Useful Claude Variables

Bundled script pattern

---
name: render-chart
description: Render a chart from CSV
allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/render.sh *)
---

Run:
${CLAUDE_SKILL_DIR}/scripts/render.sh data.csv

19. Run Skills in a Subagent

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

Research $ARGUMENTS thoroughly:
1. Find relevant files.
2. Read and analyze them.
3. Summarize findings with file references.

The forked subagent does not receive your conversation history. The Skill content becomes its task. Supported agent choices include Explore, Plan, general-purpose, or a custom subagent.

20. Background Forked Skills

Forked Skills can run in the background in supported interactive contexts. Set background: false when you want to wait for the result. Non-interactive -p, Agent SDK, scheduled tasks, and some settings can change this behavior.

21. Skills + Subagents

22. Restrict Skill Access

# Allow
Skill(commit)
Skill(review-pr *)

# Deny
Skill(deploy *)

Skill(name) matches exactly; Skill(name *) matches the name plus arguments.

23. skillOverrides

{
  "skillOverrides": {
    "legacy-context": "name-only",
    "deploy": "off"
  }
}

24. Skill Content Lifecycle

When a Skill is invoked, its rendered content enters the conversation and stays across later turns. Its instructions persist, but an allowed-tools grant clears when the next user message is sent.

25. Editing & Removing Skills

Claude Code watches supported Skill directories for changes to SKILL.md. Personal/project Skills can be removed by deleting their directories. Plugin Skills are removed by disabling/uninstalling the plugin. Synced Skills are controlled from the account where they were enabled.

26. Bundled Skills

27. /run, /verify & /run-skill-generator

The generator is especially useful when a project needs databases, environment files, graphical sessions, or multiple startup steps.

28. Visual Output with Skills

~/.claude/skills/codebase-visualizer/
├── SKILL.md
└── scripts/
    └── visualize.py

---
name: codebase-visualizer
description: Generate an interactive codebase tree
allowed-tools: Bash(python3 *)
---

Run:
python3 ${CLAUDE_SKILL_DIR}/scripts/visualize.py .

Skills can bundle scripts to create HTML reports, dependency graphs, coverage reports, database diagrams, and other visual output.

29. Sharing Skills

30. Skills vs CLAUDE.md

31. Skills vs Commands, Agents, Hooks & MCP

32. Real-World Example — Next.js

API Review Skill

.claude/skills/api-review/SKILL.md

---
name: api-review
description: Review Next.js API routes for validation, auth, errors, and response consistency.
---

Check:
1. Input validation
2. Authentication/authorization
3. Error handling
4. HTTP status codes
5. Response shape
6. Database access
7. Logging
8. Tests

Staging Deployment Skill

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

1. Run tests.
2. Build.
3. Verify environment.
4. Deploy.
5. Check deployment.
6. Report status.

Use:

/api-review
/deploy-staging

33. Real-World Example — Spring Boot

.claude/skills/spring-boot-review/SKILL.md

---
name: spring-boot-review
description: Review Spring Boot code for services, transactions, JPA, validation, and exceptions.
---

Check:
- Controller/service/repository separation
- DTO boundaries
- Transaction boundaries
- JPA fetching and N+1 risks
- Validation
- Exception handling
- Logging
- Tests

34. Best Practices

35. Common Mistakes

36. Evaluate a Skill

A Skill triggering does not prove it works well. Test two things separately:

1. Does Claude invoke it when it should?
2. Does the output match the intended behavior?

Use realistic prompts in fresh sessions and compare with the Skill enabled and disabled.

/plugin install skill-creator@claude-plugins-official

The current skill-creator workflow can help with test cases, isolated runs, grading, benchmarks, version comparison, and description tuning.

37. Troubleshooting — Not Triggering

1. Use natural keywords in the description.
2. Check that the Skill appears in the available list.
3. Rephrase the request.
4. Try /skill-name directly.
5. Check YAML frontmatter.
6. Use --debug for parsing issues.

38. Troubleshooting — Triggering Too Often

• Make the description more specific.
• Add clearer use conditions.
• Use disable-model-invocation: true for manual-only workflows.

39. Troubleshooting — Too Many Skills

Skill descriptions are included in the listing Claude uses to know what is available. If many Skills exist, descriptions can be shortened to fit the listing budget. Current Claude Code provides /skill-doctor in supported versions to inspect Skill usage/context costs.

40. Complete Skill Design Pattern

.claude/
└── skills/
    └── release/
        ├── SKILL.md
        ├── checklist.md
        ├── examples.md
        └── scripts/
            └── verify-release.sh

---
name: release
description: Prepare a production release by checking tests, versioning, changelog, and readiness.
disable-model-invocation: true
allowed-tools:
  - Bash(git status *)
  - Bash(git diff *)
  - Bash(npm test *)
---

# Release
1. Check branch.
2. Run tests.
3. Review changes.
4. Read checklist.
5. Verify version.
6. Prepare release summary.

41. Mental Model

42. Quick Decision Guide

43. Interview Questions

44. Practice Exercises

45. Final Cheat Sheet

46. Final Takeaway

Start simple: create a Skill directory, add SKILL.md, write a strong description, and put the reusable procedure in the body. As the workflow grows, add arguments, supporting files, dynamic context, tool permissions, or a forked subagent.