skill-writer

name	skill-writer
description	Comprehensive guide for creating high-quality skills for Claude. Use when building a new skill, writing a SKILL.md, designing skill frontmatter, planning skill structure, debugging trigger issues, or reviewing an existing skill for improvements. Covers standalone skills, MCP-enhanced skills, and skill-tree programmatic skills.
metadata	{"author":"skill-tree","version":"1.0.0","category":"meta","tags":["skill-creation","authoring","best-practices"]}

Skill Writer

Create well-structured, effective skills that trigger reliably, follow Anthropic's progressive disclosure model, and produce consistent results.

Core Concepts

A skill is a folder containing instructions that teach Claude to handle specific tasks or workflows. Skills eliminate the need to re-explain preferences, processes, and domain expertise in every conversation.

Progressive Disclosure (Three Levels)

1. YAML frontmatter (always in system prompt): Enough for Claude to decide when to load the skill
2. SKILL.md body (loaded when relevant): Full instructions and guidance
3. Linked files (loaded as needed): References, scripts, assets in subdirectories

This minimizes token usage while maintaining specialized expertise.

Design Principles

• Composability: Skills run alongside other skills. Never assume exclusive context.
• Portability: Skills work across Claude.ai, Claude Code, and API without modification (given environment dependencies are met).
• Progressive complexity: Start simple, add depth through references.

Instructions

Step 1: Define Use Cases

Before writing anything, identify 2-3 concrete use cases.

For each use case, document:

• Trigger: What the user says or does
• Steps: The multi-step workflow required
• Result: The concrete outcome produced

Determine which category the skill falls into:

Category	Purpose	Example
Document/Asset Creation	Consistent, high-quality output	frontend-design, docx, pptx
Workflow Automation	Multi-step processes with methodology	skill-creator, sprint-planner
MCP Enhancement	Workflow guidance for MCP tool access	sentry-code-review

Step 2: Create the Folder Structure

your-skill-name/
├── SKILL.md              # Required - main instruction file
├── scripts/              # Optional - executable code (Python, Bash)
├── references/           # Optional - detailed docs loaded as needed
└── assets/               # Optional - templates, fonts, icons

Critical naming rules:

• Folder: kebab-case only (my-skill-name)
• File: exactly SKILL.md (case-sensitive, no variations)
• No README.md inside the skill folder
• No spaces, underscores, or capitals in folder name

Step 3: Write the YAML Frontmatter

The frontmatter is the most important part - it determines whether Claude loads the skill.

Minimal required format:

---
name: your-skill-name
description: What it does. Use when user asks to [specific phrases].
---

The name Field

• kebab-case only, no spaces or capitals
• Must match the folder name
• Never use "claude" or "anthropic" as a prefix (reserved)

The description Field (Critical)

Structure: [What it does] + [When to use it] + [Key capabilities]

Must include BOTH:

1. What the skill does
2. When to use it (trigger conditions with specific phrases)

Constraints:

• Under 1024 characters
• No XML angle brackets (< or >)
• Include specific tasks/phrases users would actually say
• Mention relevant file types if applicable

Good descriptions:

# Specific + actionable + trigger phrases
description: Analyzes Figma design files and generates developer
  handoff documentation. Use when user uploads .fig files, asks for
  "design specs", "component documentation", or "design-to-code handoff".

# Clear value proposition + triggers
description: End-to-end customer onboarding workflow for PayFlow.
  Handles account creation, payment setup, and subscription management.
  Use when user says "onboard new customer", "set up subscription",
  or "create PayFlow account".

Bad descriptions:

# Too vague - won't trigger
description: Helps with projects.

# Missing triggers - Claude won't know when to load
description: Creates sophisticated multi-page documentation systems.

# Too technical, no user-facing triggers
description: Implements the Project entity model with hierarchical
  relationships.

Optional Fields

license: MIT                              # For open-source skills
compatibility: Requires Python 3.10+      # 1-500 chars, environment needs
allowed-tools: "Bash(python:*) WebFetch"  # Restrict tool access
metadata:                                 # Custom key-value pairs
  author: Your Name
  version: 1.0.0
  mcp-server: server-name
  tags: [automation, productivity]

Security Restrictions

Forbidden in frontmatter:

• XML angle brackets (< >) - prevents prompt injection
• Skills named with "claude" or "anthropic" prefix

Step 4: Write the Instructions Body

After the frontmatter, write instructions in Markdown.

Recommended Structure

# Skill Name

## Instructions

### Step 1: [First Major Step]
Clear explanation of what happens.

Example:
\`\`\`bash
python scripts/fetch_data.py --project-id PROJECT_ID
\`\`\`
Expected output: [describe what success looks like]

(Add more steps as needed)

## Examples

### Example 1: [Common Scenario]
User says: "Set up a new marketing campaign"
Actions:
1. Fetch existing campaigns via MCP
2. Create new campaign with provided parameters
Result: Campaign created with confirmation link

## Troubleshooting

### Error: [Common error message]
Cause: [Why it happens]
Solution: [How to fix]

Writing Style Rules

• Imperative/infinitive form: "To accomplish X, execute Y" or "Load this skill when Z"
• Avoid second person: Do NOT write "You should..." or "If you need..."
• Be specific and actionable: Include exact commands, parameters, expected outputs
• Use bullet points and numbered lists for scanability
• Put critical instructions at the top using ## Important or ## Critical headers

Error Handling

Always include error handling:

## Common Issues

### MCP Connection Failed
If "Connection refused" appears:
1. Verify MCP server is running: Check Settings > Extensions
2. Confirm API key is valid
3. Try reconnecting: Settings > Extensions > [Service] > Reconnect

Progressive Disclosure in Practice

Keep SKILL.md focused on core instructions (under 5,000 words). Move detailed documentation to references/:

Before writing queries, consult `references/api-patterns.md` for:
- Rate limiting guidance
- Pagination patterns
- Error codes and handling

Combating Instruction Drift

For critical validations, prefer bundling a script over relying on language instructions:

CRITICAL: Before calling create_project, verify:
- Project name is non-empty
- At least one team member assigned
- Start date is not in the past

For deterministic checks, use scripts/validate.py instead of prose instructions.

Step 5: Choose an Implementation Pattern

Select the pattern that fits the skill's workflow. See references/patterns.md for detailed examples.

Pattern	Use When
Sequential Workflow	Multi-step processes in specific order
Multi-MCP Coordination	Workflows spanning multiple services
Iterative Refinement	Output quality improves with iteration
Context-Aware Selection	Same outcome, different tools per context
Domain Intelligence	Specialized knowledge beyond tool access

Step 6: Test the Skill

Triggering Tests

Run 10-20 test queries. Target: skill triggers on 90%+ of relevant queries.

Should trigger:

• Obvious task descriptions
• Paraphrased requests
• Domain-specific terminology

Should NOT trigger:

• Unrelated topics
• Queries better served by other skills

Debug triggering: Ask Claude "When would you use the [skill name] skill?" and compare against expected triggers.

Functional Tests

• Valid outputs generated
• API/MCP calls succeed
• Error handling works
• Edge cases covered

Performance Comparison

Compare with and without the skill:

• Number of back-and-forth messages
• Failed API calls
• Total tokens consumed
• User corrections needed

Step 7: Iterate

Skills are living documents. Watch for:

Undertriggering (skill doesn't load when it should):

• Add more trigger phrases to the description
• Include technical keywords and synonyms

Overtriggering (skill loads for unrelated queries):

• Add negative triggers: "Do NOT use for simple data exploration"
• Be more specific about scope
• Clarify boundaries with other skills

Execution issues (inconsistent results):

• Make instructions more specific
• Add error handling
• Move verbose content to references

Skill-Tree Programmatic Skills

When creating skills for the skill-tree library (as opposed to SKILL.md files), structure them with these fields:

{
  id: "kebab-case-id",
  name: "Human-Readable Name",
  version: "1.0.0",
  description: "Short description for semantic matching (1-2 sentences)",
  problem: "What problem this skill solves",
  triggerConditions: [
    { type: "error", value: "Cannot find module", description: "ES module import failure" },
    { type: "keyword", value: "typescript, import", description: "TypeScript imports" },
    { type: "pattern", value: "\\.(ts|tsx)$", description: "TypeScript files" }
  ],
  solution: "Step-by-step solution in imperative form",
  verification: "How to verify the skill worked",
  examples: [
    { scenario: "Description", before: "Before state", after: "After state" }
  ],
  tags: ["typescript", "modules"],
  status: "active"
}

Trigger condition types:

• error: Error message patterns (regex)
• keyword: Comma-separated keywords
• pattern: Regex for file paths or content
• context: Contextual description
• custom: Freeform condition

Quality Checklist

Before shipping, verify against references/quality-checklist.md.

Quick validation:

• Folder is kebab-case, SKILL.md exists (exact spelling)
• Frontmatter has --- delimiters, name and description fields
• Description includes WHAT it does and WHEN to use it
• No XML tags anywhere in frontmatter
• Instructions are specific and actionable (not vague)
• Error handling included for common failure modes
• Examples provided for primary use cases
• SKILL.md is under 5,000 words
• Detailed docs moved to references/
• Tested: triggers correctly, doesn't overtrigger, produces correct output