Creating a New Skill

Follow this workflow when creating a new Claude Code Skill.

0) Fetch latest best practices (REQUIRED)

Before writing any skill content, you MUST fetch and read the latest documentation:

1. Skills overview: https://code.claude.com/docs/en/skills
2. Best practices: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices

Use WebFetch to retrieve these pages and extract key guidelines before proceeding.

1) Gather requirements

Ask the user:

• What task should this skill automate?
• What triggers should activate this skill? (keywords, file types, contexts)
• Should it be project-scoped (.claude/skills/) or personal (~/.claude/skills/)?
• What tools does it need? (Read, Grep, Glob, Bash, WebFetch, Write, etc.)

2) Review existing skills for patterns

Check existing skills in the project for naming conventions and structure:

ls -la .claude/skills/

Read similar skills if they exist to maintain consistency.

3) Create skill structure

Directory structure

.claude/skills/<skill-name>/
├── SKILL.md              # Main instructions (required)
├── reference/            # Optional: detailed docs
│   └── *.md
└── scripts/              # Optional: utility scripts
    └── *.py|*.sh

SKILL.md format (required fields)

---
name: skill-name-in-kebab-case
description: Brief description of what this Skill does and when to use it. Include specific trigger keywords.
allowed-tools: Read, Grep, Glob  # Optional: restrict tool access
---

# Skill Title

## Instructions
Clear, step-by-step guidance...

4) Apply best practices checklist

Naming

• Use gerund form: processing-pdfs, analyzing-code, creating-commits
• Max 64 chars, lowercase letters/numbers/hyphens only
• No reserved words: "anthropic", "claude"

Description

• Write in third person ("Processes...", not "I can help..." or "You can use...")
• Include what it does AND when to use it
• Include specific trigger keywords users would say
• Max 1024 chars

Content

• Keep SKILL.md body under 500 lines
• Be concise - Claude is already smart
• Use progressive disclosure: put detailed content in separate files
• Keep file references one level deep from SKILL.md
• Use Unix-style paths (forward slashes)
• Avoid time-sensitive information

Structure

• Provide concrete examples, not abstract descriptions
• Use consistent terminology throughout
• Include workflows for complex tasks
• Add validation/feedback loops for quality-critical tasks

5) Output the skill

After gathering requirements and applying best practices:

1. Create the skill directory
2. Write SKILL.md with proper frontmatter
3. Add reference files if needed (for content > 500 lines)
4. Summarize what was created

Example: Simple skill

---
name: generating-commit-messages
description: Generates clear commit messages from git diffs. Use when writing commit messages or reviewing staged changes.
---

# Generating Commit Messages

## Instructions

1. Run `git diff --staged` to see changes
2. Suggest a commit message with:
   - Summary under 50 characters
   - Detailed description
   - Affected components

## Best practices

- Use present tense
- Explain what and why, not how

Anti-patterns to avoid

• Vague descriptions like "Helps with documents"
• Multiple approaches without clear defaults
• Assuming packages are installed without listing them
• Windows-style paths (\ instead of /)
• Deeply nested file references (keep one level deep)
• Over-explaining what Claude already knows