Creating Skills in Claude Code

This skill guides you through creating effective skills for Claude Code. Skills are markdown files that teach the agent how to perform specific tasks: reviewing PRs, generating commit messages, querying databases, or any specialized workflow.

Phase 1 — Gather Requirements

Before creating a skill, gather essential information. If $ARGUMENTS provides a name and description, infer what you can. For anything unclear, ask the user.

Required information

1. skill-name: lowercase, hyphen-separated (e.g., tf-plan-review). Max 64 chars.
2. Purpose: What specific task or workflow should this skill help with?
3. Trigger scenarios: When should the agent automatically apply this skill? What would the user say?
4. Key domain knowledge: What specialized information does the agent need that it wouldn't already know?

Optional information

1. Output format: Are there specific templates, formats, or styles required?
2. Reference files needed? Environment-specific config, runbooks, API docs → references/ subfolder (Tier 3)
3. Deterministic scripts needed? Status checks, linters, formatters → scripts/ subfolder
4. Existing patterns: Are there existing examples or conventions to follow?

Inferring from context

If you have previous conversation context, infer the skill from what was discussed. Create skills based on workflows, patterns, or domain knowledge that emerged in the conversation.

If skill-name is missing from $ARGUMENTS, stop and ask.

Phase 2 — Check for Conflicts

1. Glob .claude/skills/ to list existing skills
2. If a skill with the same name exists, stop and tell the user
3. Quick overlap check: does an existing skill already cover this purpose? If so, suggest updating it instead

Phase 3 — Design the Skill

Directory layout

Skills are stored as directories containing a SKILL.md file:

text
1.claude/skills/<skill-name>/
2├── SKILL.md              # Required — main instructions
3├── references/           # Optional — Tier 3, loaded only on explicit request
4│   ├── README.md
5│   └── <env-specific>.md
6└── scripts/              # Optional — deterministic checks/formatters only
7    └── <script-name>.sh

Writing the description (critical for discovery)

The description determines when Claude applies the skill. It must include both WHAT and WHEN.

Rules:

• Write in third person (injected into system prompt)
• Be specific, include trigger terms the user would naturally say
• Include Turkish trigger phrases if the user works in Turkish
• Max 1024 chars

Good examples:

yaml
1# Concise and trigger-rich
2description: >
3  Review Terraform plan output for cost, security, and drift issues. Use when
4  the user says "review plan", "tf plan check", or pastes terraform plan output.
5
6# Multi-language triggers
7description: >
8  Generate conventional commit messages by analyzing staged changes. Use when
9  the user says "commit message", "write commit", or "commit yaz".

Bad examples:

yaml
1# Too vague — agent won't know when to trigger
2description: "Helps with infrastructure"
3
4# First person — wrong voice
5description: "I review your Terraform plans"

Choosing the right degree of freedom

Match specificity to the task's fragility:

Phase 4 — Create Files

4a. Create .claude/skills/<skill-name>/SKILL.md

Use this template — fill in every field, no placeholders left blank:

markdown
1---
2name: <skill-name>
3description: >
4  <One sentence. What it does + when to trigger. Include natural trigger phrases.>
5argument-hint: "<what arguments this skill accepts, if any>"
6allowed-tools: <comma-separated — only tools this skill actually needs>
7disable-model-invocation: true
8---
9
10# <Skill title>
11
12## Purpose
13
14<One paragraph. What does this skill do and why does it exist?>
15
16## When to use
17
18- <Trigger scenario 1>
19- <Trigger scenario 2>
20
21## Inputs
22
23- <Input 1: what it is, where it comes from>
24
25## Process
26
271. <Step 1 — clear action>
282. <Step 2>
293. <Step 3>
304. <Step 4 — what to produce and where>
31
32## Output
33
34<What the skill produces. Format, location, naming convention.>
35
36## Quality bar
37
38<Minimum standard for acceptable output. What does "done" look like?>

Key authoring principles

Concise is key. The context window is shared with conversation history, other skills, and user requests. Every token competes for space. The agent is already smart — only add context it doesn't already have.

Challenge each piece of information:

• "Does the agent really need this?"
• "Can I assume the agent knows this?"
• "Does this paragraph justify its token cost?"

Keep SKILL.md under 500 lines. Use progressive disclosure — put essential info in SKILL.md, detailed reference in separate files.

markdown
1## Additional resources
2
3- For complete API details, see [reference.md](references/api.md)
4- For usage examples, see [references/examples.md](references/examples.md)

Keep references one level deep — link directly from SKILL.md. Deeply nested references may result in partial reads.

Common SKILL.md patterns

Template pattern — when output format matters

markdown
1## Report structure
2
3\`\`\`markdown
4
5# [Analysis Title]
6
7## Executive summary
8
9[One-paragraph overview]
10
11## Key findings
12
13- Finding 1 with data
14- Finding 2 with data
15
16## Recommendations
17
181. Actionable recommendation
19   \`\`\`

Examples pattern — when output quality depends on seeing examples

markdown
1## Commit format
2
3**Example 1:**
4Input: Added JWT authentication
5Output: `feat(auth): implement JWT-based authentication`
6
7**Example 2:**
8Input: Fixed timezone bug in reports
9Output: `fix(reports): correct date formatting in timezone conversion`

Workflow pattern — when steps must happen in order

markdown
1## Checklist
2
3- [ ] Step 1: Analyze input
4- [ ] Step 2: Generate mapping
5- [ ] Step 3: Validate
6- [ ] Step 4: Produce output
7- [ ] Step 5: Verify

Feedback loop pattern — for quality-critical tasks

markdown
11. Make edits
22. **Validate**: `scripts/validate.sh output/`
33. If validation fails → fix → re-validate
44. Only proceed when validation passes

4b. If references needed — create references/README.md

markdown
1# <skill-name> references
2
3Add environment-specific reference files here. These are Tier 3 — loaded only on explicit request.
4
5Example files:
6
7- `staging.md` — staging environment details
8- `production.md` — production environment details
9- `runbook.md` — step-by-step operational runbook

4c. If scripts needed — create scripts/<name>.sh

Scripts must be:

• Deterministic status checks or formatters only
• NOT reconstruction of logic Claude should reason through
• Executable — remind user to chmod +x
• Document required packages/dependencies

Phase 5 — Update Parent Agent (if applicable)

1. Glob .claude/agents/ for directories (not .md files — those are Type A agents)
2. For each agent directory, read its AGENT.md
3. If the skill matches the agent's domain, ask: "This looks related to <agent-name>. Should I add this skill to its AGENT.md Skills table?"
4. If yes, also ask which goal it serves — do not guess

Phase 6 — Print Summary

text
1Created:
2  .claude/skills/<skill-name>/SKILL.md
3  [.claude/skills/<skill-name>/references/README.md]  ← if applicable
4  [.claude/skills/<skill-name>/scripts/<name>.sh]      ← if applicable
5
6[Updated: .claude/agents/<agent-name>/AGENT.md]        ← if applicable
7
8Trigger phrases: "<from description>"
9
10Next steps:
11  → Fill in the Process steps with your actual workflow
12  → Add reference files to references/ if you need env-specific config
13  → Test the skill by invoking its trigger phrases

Anti-Patterns to Avoid

Complete Example

text
1pr-review/
2├── SKILL.md
3└── references/
4    └── standards.md

SKILL.md:

markdown
1---
2name: pr-review
3description: >
4  Review pull requests for quality, security, and maintainability. Use when
5  the user says "review PR", "check this PR", or "PR review".
6argument-hint: "<PR number or URL>"
7allowed-tools: Read, Glob, Grep, Bash
8disable-model-invocation: true
9---
10
11# PR Review
12
13## Purpose
14
15Review code changes in a pull request against team standards, checking for
16correctness, security, readability, and test coverage.
17
18## Process
19
201. Fetch PR diff via `gh pr diff <number>`
212. Identify changed files and categorize (new, modified, deleted)
223. For each file, check against standards in [standards.md](references/standards.md)
234. Produce review summary
24
25## Output
26
27Structured review with severity levels:
28
29- 🔴 **Critical** — must fix before merge
30- 🟡 **Suggestion** — consider improving
31- 🟢 **Nitpick** — optional enhancement
32
33## Quality bar
34
35Every critical issue must include: file path, line number, what's wrong, and a fix suggestion.

Verification Checklist

Before finalizing, verify:

• Description is specific, includes trigger terms, written in third person
• SKILL.md body is under 500 lines
• Consistent terminology throughout
• allowed-tools lists only what the skill actually needs
• File references are one level deep
• No time-sensitive information
• Scripts (if any) are deterministic, not reasoning
• No conflict with existing skills