Before You Start
Both Skills and Subagents are just Markdown files with YAML frontmatter. No build step, no compile step — save the file and Claude Code picks it up from the next session.
Two scopes are available.
| Scope | Skill | Subagent |
|---|---|---|
| User-global | ~/.claude/skills/{name}/SKILL.md | ~/.claude/agents/{name}.md |
| Project | .claude/skills/{name}/SKILL.md | .claude/agents/{name}.md |
Project-scope files get committed to Git and shared with the team.
Writing a Skill
Directory Layout
A Skill is managed as a directory. The folder name becomes the Skill name, and SKILL.md is required inside.
.claude/skills/commit-helper/
├── SKILL.md # required: instructions
├── templates/ # optional: reference templates
│ └── message.txt
└── scripts/ # optional: executable scripts
└── build.shFrontmatter Fields
---
name: commit-helper # required: lowercase, hyphens, max 64 chars
description: > # required: third person, explicit about when to use
Writes commit messages following the Conventional Commits spec.
Invoked when the user wants to commit their changes.
allowed-tools: ["Read", "Bash"] # optional: restrict available tools
license: "MIT" # optional
---| Field | Required | Notes |
|---|---|---|
name | ✅ | Becomes the slash command (/commit-helper) |
description | ✅ | The single most important field — drives auto-invocation accuracy |
allowed-tools | ❌ | If omitted, the Skill uses all parent-session tools |
license / compatibility | ❌ | Metadata for distribution |
Example: a Commit Helper Skill
---
name: commit-helper
description: >
Writes commit messages in Conventional Commits format.
Invoked when the user says "please commit" or runs /commit-helper.
allowed-tools: ["Bash"]
---
# Commit Helper
## Procedure
1. Run `git status --short` to list changes
2. Run `git diff --staged` to inspect staged diffs
3. Pick a type based on scope of changes:
- New feature → `feat`
- Bug fix → `fix`
- Refactor → `refactor`
- Docs only → `docs`
4. Write a ≤50-char summary + optional body
5. Execute `git commit -m "..."`
## Format
```
<type>(<scope>): <summary>
<body - optional>
```
## Caveats
- If changes mix multiple types, propose splitting the commit
- If files contain secrets, stop and warn the user — do not commitTips for the description Field
description is the only signal Claude uses to auto-invoke a Skill. Follow these rules.
| Bad | Good |
|---|---|
| ”For commits" | "Writes Conventional Commits messages when the user wants to commit changes" |
| "Tests" | "Writes Jest unit tests and maintains 80%+ coverage" |
| "Code review" | "Inspects just-written code for security and readability. Auto-invoked right after edits” |
The bad examples are too short — they don’t specify when the Skill should fire.
Writing a Subagent
File Layout
A Subagent is a single .md file — not a directory.
.claude/agents/
├── code-reviewer.md
├── security-auditor.md
└── test-writer.mdFrontmatter Fields
---
name: code-reviewer # required
description: > # required
Reviews just-changed code for quality and security.
Use immediately after any code modification.
tools: Read, Grep, Glob, Bash # optional: comma-separated tools
model: sonnet # optional: haiku | sonnet | opus | inherit
---| Field | Required | Notes |
|---|---|---|
name | ✅ | Agent identifier, used at invocation |
description | ✅ | Drives auto-invocation decisions |
tools | ❌ | If omitted, inherits all parent-session tools. Comma-separated list to restrict |
model | ❌ | If omitted, inherits the parent model |
Model selection guide:
| Model | Use for |
|---|---|
haiku | Simple lookup/summary (fast, cheap) |
sonnet | General coding work (balanced) |
opus | Complex design/debugging (deep reasoning) |
inherit | Same model as the parent session |
Example: a Code Reviewer Agent
---
name: code-reviewer
description: >
Code reviewer invoked right after code changes. Checks security,
readability, performance, and test coverage; reports issues
classified as CRITICAL / HIGH / MEDIUM / LOW.
tools: Read, Grep, Glob, Bash
model: sonnet
---
# Code Reviewer
You are a senior engineer with 10 years of experience. Inspect
the just-changed code and report issues organized by severity.
## Review Checklist
### CRITICAL
- Hardcoded secrets, API keys
- SQL injection, XSS, command injection
- Missing authN / authZ
### HIGH
- Missing error handling (empty catch, etc.)
- Resource leaks (unclosed files/DB connections)
- Possible infinite loops
### MEDIUM
- Long functions (>50 lines)
- Deep nesting (>4 levels)
- Magic numbers
### LOW
- Naming consistency
- Comment quality
## Output Format
Pin each issue to file:line. If nothing is found, just report
"No issues." — keep it short.Example: a Read-Only Explorer Agent
---
name: explorer
description: >
Read-only codebase exploration agent. Maps the file structure,
dependencies, and primary entry points; returns only a summary.
No write access.
tools: Read, Grep, Glob
model: haiku
---
# Explorer
## Mission
1. Walk the directory tree from the project root
2. Identify dependencies via package manifests (package.json /
requirements.txt / etc.)
3. Locate primary entry points (main, index, app, ...)
4. Return a ≤200-word summary
## Constraints
- No file modifications (Write/Edit not in tools)
- Target completion within 3 minutesHaiku model + read-only tools deliver fast and cheap exploration.
Testing Your Work
After saving, restart Claude Code and verify.
# Inside Claude Code CLI
/commit-helper # direct Skill invocation
# Or trigger auto-invocation with natural language
"Write a commit message for the files I just changed"For agents, trigger them with natural language like “use the code-reviewer agent to review”, or let Claude auto-invoke based on description matching.
Common Mistakes and Fixes
| Mistake | Fix |
|---|---|
description is vague like “helper tool” | Add explicit “invoked when …” conditions |
Agent tools missing a required tool | Walk through the workflow and list every tool needed |
| Project-scope Skill not committed | Don’t put .claude/skills/ in .gitignore |
| Same-name Skill in both user and project scope | Check the scope precedence (Enterprise/Personal/Project) and tidy up based on intent |
Wrap-up
Writing Skills and Subagents ultimately boils down to a precise description and the right permission boundary. First decide whether the thing is a book of rules or a colleague you delegate to. Then grant only the minimum allowed-tools / tools needed. Committing .claude/ to your repo gives the entire team the same shared AI assistants.