Add Skill Skill | Agent Skills

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):

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)
Name: lowercase, hyphens only (prefer gerund: processing-pdfs, testing-code)
Purpose: What does it do? (1-2 sentences)
Trigger: When should Claude use it? (keywords, scenarios)
Complexity: Instructions-only, or needs scripts/references?
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:

Inform the user: "The SKILL.md is {N} lines — exceeding the recommended 500-line limit."
Identify splittable sections: detailed references, long examples, advanced features
Move to reference files: references/{topic}.md — one level deep only
Replace in SKILL.md with a short summary + link
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

| Freedom | Use When | Example | |---------|----------|---------| | High (text instructions) | Multiple valid approaches | Code review guidelines | | Medium (pseudocode/params) | Preferred pattern exists | Report generation template | | Low (exact scripts) | Fragile operations, consistency critical | Database migrations |

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)

Agent Skills: Add Skill

Install this agent skill to your local

Skill Files