Add Skill

Create properly structured Claude Code skills from user requirements.

Quick Mode

For rapid creation, user can provide all info at once:

/add-skill name=my-skill purpose="Does X" trigger="when user asks for Y"

Parse and generate without interactive prompts.

Workflow

Step 1: Fetch Latest Documentation

Always fetch official docs first to ensure compliance with current spec:

WebFetch: https://code.claude.com/docs/en/skills
Prompt: Extract skill file format, required fields, naming rules, and best practices

If WebFetch fails, fallback:

WebSearch: "Claude Code skills SKILL.md format site:code.claude.com"

Step 2: Gather Requirements

Ask user (or parse from quick mode):

1. •Scope: Global skill or repo-local skill?
   • •Global → ~/.claude/skills/{skill-name}/ (available in all projects)
   • •Repo-local → .claude/skills/{skill-name}/ (only this repo, committed with code)
2. •Name: lowercase, hyphens only (prefer gerund: processing-pdfs, testing-code)
3. •Purpose: What does it do? (1-2 sentences)
4. •Trigger: When should Claude use it? (keywords, scenarios)
5. •Complexity: Instructions-only, or needs scripts/references?
6. •Freedom level: Rigid (exact steps) vs flexible (general guidance)?

Step 3: Create Skill Structure

{base-path}/skills/{skill-name}/
├── SKILL.md           # Required: Main instructions (<500 lines)
├── scripts/           # Optional: Executable code
│   └── main.py
└── references/        # Optional: Detailed docs (one level deep)
    └── examples.md

Step 4: Generate SKILL.md

---
name: {skill-name}
description: {What it does in third person}. Use when {trigger conditions}.
---

# {Skill Title}

{Brief overview - assume Claude is smart, only add context it doesn't already have}

## Quick Start

{Minimal working example or first step}

## Instructions

{Step-by-step guidance with appropriate freedom level}

## Advanced Features

**Feature A**: See [references/feature-a.md](references/feature-a.md)

Step 5: Check Line Count & Apply Progressive Disclosure

After drafting SKILL.md, count its lines. If approaching or exceeding 500 lines:

1. •Inform the user: "The SKILL.md is {N} lines — exceeding the recommended 500-line limit."
2. •Identify splittable sections: detailed references, long examples, advanced features
3. •Move to reference files: references/{topic}.md — one level deep only
4. •Replace in SKILL.md with a short summary + link
5. •Add table of contents to any reference file over 100 lines

Step 6: Validate

Run through the validation checklist before finalizing.

Step 7: Verify

ls -la ~/.claude/skills/{skill-name}/
cat ~/.claude/skills/{skill-name}/SKILL.md

Test with: claude --debug to check for loading errors.

Naming Rules

• •Length: 1-64 characters
• •Format: lowercase letters, numbers, hyphens only
• •Prefer gerund form: processing-pdfs, testing-code, writing-documentation
• •Acceptable alternatives: pdf-processing, process-pdfs
• •Not allowed: start/end with -, consecutive --, reserved words (anthropic, claude), XML tags
• •Avoid: vague names (helper, utils, tools), overly generic (documents, data)
• •Must match: folder name

Description Rules

• •Maximum: 1024 characters, non-empty, no XML tags
• •Always third person: "Processes Excel files" not "I can help you"
• •Include both: what it does AND when to use it
• •Be specific: Claude uses descriptions to choose from 100+ skills

Good:

description: Extracts text and tables from PDF files, fills forms, merges documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.

Bad: "Helps with documents", "Processes data", "Does stuff with files"

Core Principles

Conciseness

Challenge each piece of information:

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

Degrees of Freedom

Consistent Terminology

Pick one term and use it throughout. Don't mix "API endpoint" / "URL" / "API route".

Patterns

Workflow with Checklist

For complex multi-step operations, provide a copyable checklist.

Feedback Loop

Run validator → fix errors → repeat until passing.

Conditional Workflow

Guide through decision points: Creating new? → "Creation workflow" / Editing existing? → "Editing workflow"

Scripts Best Practices

• •Handle errors explicitly — don't punt to Claude
• •No voodoo constants — justify and document all values
• •List dependencies with install instructions
• •Make execution intent clear: "Run script.py" (execute) vs "See script.py" (reference)
• •Use forward slashes in all file paths
• •MCP tool references — use fully qualified names: ServerName:tool_name

Anti-Patterns

• •Explaining things Claude already knows
• •Offering too many tool/library options — provide a default with escape hatch
• •Time-sensitive information — use <details> tag for old patterns
• •Deeply nested references (file → file → file)
• •Assuming packages are installed without install instructions

Validation Checklist

Core Quality

• • Name: lowercase, numbers, hyphens only, 1-64 chars, no reserved words
• • Description: third person, specific, includes what + when, under 1024 chars
• • SKILL.md body under 500 lines
• • Additional details in separate reference files (one level deep)
• • No time-sensitive information
• • Consistent terminology throughout
• • Concrete examples (not abstract)
• • Progressive disclosure used appropriately

Scripts (if applicable)

• • Scripts handle errors explicitly
• • No voodoo constants (all values justified)
• • Required packages listed with install instructions
• • Forward slashes in all paths

Testing

• • Tested with real usage scenarios
• • Works across target models (Haiku needs more guidance, Opus needs less)

Further Reading

• •Eval-driven development: See references/eval-driven-development.md
• •Examples: See references/examples.md
• •Official docs: https://code.claude.com/docs/en/skills