---

name: writing-skills description: Creates effective skills that extend AI capabilities through specialized knowledge, workflows, and tools. ALWAYS read before creating or editing any SKILL.md file. This skill should be used when the user asks to "create a skill", "write a skill", "build a skill", "author a skill", "improve a skill description", "make my skill better", "edit a skill", or needs guidance on skill structure, YAML frontmatter, progressive disclosure, or skill authoring best practices. user-invocable: true disable-model-invocation: false

Writing Skills

Create effective skills that extend Claude's capabilities through specialized knowledge, workflows, and tools.

Quick Start

Every skill requires a SKILL.md file with YAML frontmatter:

Copy---
name: skill-name
description: Brief description of what this skill does and when to use it. This skill should be used when the user asks to "trigger phrase 1", "trigger phrase 2", or mentions specific-domain-terms.
---

# Skill Name

[Instructions for Claude to follow]

Core Principles

1. Be Concise

Only add context Claude doesn't already have. Challenge each piece of information:

• Does Claude really need this explanation?
• Does this paragraph justify its token cost?

2. Match Freedom to Fragility

3. Use Progressive Disclosure

Skill Structure

Copyskill-name/
├── SKILL.md           # Required - core instructions (<500 lines)
├── references/        # Optional - detailed documentation
├── examples/          # Optional - working code examples
├── scripts/           # Optional - executable utilities
└── assets/            # Optional - templates, images, fonts

YAML Frontmatter Requirements

Writing Descriptions

Always use third person. The description injects into the system prompt.

Copy# Good - third person, specific triggers
description: Processes PDF files and extracts text. This skill should be used when the user asks to "extract PDF text", "read a PDF", or mentions PDF processing.

# Bad - wrong person, vague
description: Use this skill when working with PDFs.
description: I can help you process PDFs.

Authoring Workflow

Step 1: Gather Concrete Examples

Understand how the skill will be used before writing:

• What would a user say to trigger this skill?
• What are 3-5 specific use cases?
• What context does Claude need that it doesn't already have?

Step 2: Plan Bundled Resources

For each use case, identify reusable resources:

Step 3: Write SKILL.md

Target: 1,500-2,000 words for the body.

1. Start with a quick start section showing basic usage
2. Cover core workflows in imperative form
3. Reference bundled resources clearly
4. Move detailed content to references/

Writing style - use imperative form:

Copy# Good
Extract text using pdfplumber.
Validate the output before proceeding.

# Bad
You should extract text using pdfplumber.
You need to validate the output.

Step 4: Create Bundled Resources

references/ - Documentation loaded on-demand:

• Keep SKILL.md lean by moving details here
• One file per topic (patterns.md, api-reference.md)
• Include table of contents for files >100 lines

scripts/ - Executable utilities:

• Handle errors explicitly, don't punt to Claude
• Document configuration values
• Can execute without loading into context

examples/ - Working code samples:

• Complete, runnable examples
• Show input/output pairs when helpful

Step 5: Validate

Run the validation script:

Copy./scripts/validate-skill.sh /path/to/skill

Or manually verify:

• Description uses third person
• Description includes specific trigger phrases
• SKILL.md body uses imperative form
• SKILL.md under 500 lines
• All referenced files exist
• No time-sensitive information

Step 6: Test and Iterate

1. Use the skill on real tasks
2. Observe where Claude struggles
3. Update instructions or add resources
4. Test again

Common Patterns

Template Pattern

Provide output templates with appropriate flexibility:

Copy## Report Structure

Use this template, adjusting sections as needed:

# [Title]
## Executive Summary
[Overview]
## Key Findings
[Findings]
## Recommendations
[Actions]

Workflow with Checklist

For multi-step processes, provide trackable progress:

Copy## Processing Workflow

Track progress:
- [ ] Step 1: Analyze input
- [ ] Step 2: Validate data
- [ ] Step 3: Process
- [ ] Step 4: Verify output

Conditional Workflow

Guide Claude through decision points:

Copy## Document Workflow

Determine the task type:
- **Creating new?** → See [creation.md](references/creation.md)
- **Editing existing?** → See [editing.md](references/editing.md)

Anti-Patterns to Avoid

Additional Resources

Reference Files

• references/progressive-disclosure.md - Detailed patterns for organizing content
• references/content-guidelines.md - Writing style, terminology, examples
• references/evaluation-iteration.md - Testing strategies and iteration workflow

Examples

• examples/minimal-skill.md - Simplest possible skill
• examples/standard-skill.md - Typical skill with references

Scripts

• scripts/validate-skill.sh - Validate skill structure and content