skill-writer

Skill Writer

This Skill helps you create well-structured Agent Skills for Claude Code that follow best practices and validation requirements.

When to use this Skill

Use this Skill when:

• Creating a new Agent Skill
• Writing or updating SKILL.md files
• Designing skill structure and frontmatter
• Troubleshooting skill discovery issues
• Converting existing prompts or workflows into Skills

Instructions

Step 1: Determine Skill scope

First, understand what the Skill should do:

1. Ask clarifying questions:

• What specific capability should this Skill provide?
• When should Claude use this Skill?
• What tools or resources does it need?
• Is this for personal use or team sharing?

1. Keep it focused: One Skill = one capability
2. Good: "PDF form filling", "Excel data analysis"
3. Too broad: "Document processing", "Data tools"

Step 2: Choose Skill location

Determine where to create the Skill:

Personal Skills (~/.claude/skills/):

• Individual workflows and preferences
• Experimental Skills
• Personal productivity tools

Project Skills (.claude/skills/):

• Team workflows and conventions
• Project-specific expertise
• Shared utilities (committed to git)

Step 3: Create Skill structure

Create the directory and files:

# Personal
mkdir -p ~/.claude/skills/skill-name

# Project
mkdir -p .claude/skills/skill-name

For multi-file Skills:

skill-name/
├── SKILL.md (required)
├── reference.md (optional)
├── examples.md (optional)
├── scripts/
│   └── helper.py (optional)
└── templates/
    └── template.txt (optional)

Step 4: Write SKILL.md frontmatter

Create YAML frontmatter with required fields:

---
name: skill-name
description: Brief description of what this does and when to use it
---

Field requirements:

• name:

• Lowercase letters, numbers, hyphens only
• Max 64 characters
• Must match directory name
• Good: pdf-processor, git-commit-helper
• Bad: PDF_Processor, Git Commits!

• description:
• Max 1024 characters
• Include BOTH what it does AND when to use it
• Use specific trigger words users would say
• Mention file types, operations, and context

Optional frontmatter fields:

• allowed-tools: Restrict tool access (comma-separated list)

``yaml allowed-tools: Read, Grep, Glob `` Use for:

• Read-only Skills
• Security-sensitive workflows
• Limited-scope operations

Step 5: Write effective descriptions

The description is critical for Claude to discover your Skill.

Formula: [What it does] + [When to use it] + [Key triggers]

Examples:

✅ Good:

description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.

✅ Good:

description: Analyze Excel spreadsheets, create pivot tables, and generate charts. Use when working with Excel files, spreadsheets, or analyzing tabular data in .xlsx format.

❌ Too vague:

description: Helps with documents
description: For data analysis

Tips:

• Include specific file extensions (.pdf, .xlsx, .json)
• Mention common user phrases ("analyze", "extract", "generate")
• List concrete operations (not generic verbs)
• Add context clues ("Use when...", "For...")

Step 6: Structure the Skill content

Use clear Markdown sections:

# Skill Name

Brief overview of what this Skill does.

## Quick start

Provide a simple example to get started immediately.

## Instructions

Step-by-step guidance for Claude:

1. First step with clear action
2. Second step with expected outcome
3. Handle edge cases

## Examples

Show concrete usage examples with code or commands.

## Best practices

- Key conventions to follow
- Common pitfalls to avoid
- When to use vs. not use

## Requirements

List any dependencies or prerequisites:

pip install package-name

Advanced usage

For complex scenarios, see [reference.md](reference.md).

### Step 7: Add supporting files (optional)

Create additional files for progressive disclosure:

**reference.md**: Detailed API docs, advanced options
**examples.md**: Extended examples and use cases
**scripts/**: Helper scripts and utilities
**templates/**: File templates or boilerplate

Reference them from SKILL.md:

For advanced usage, see [reference.md](reference.md).

Run the helper script: \\\bash python scripts/helper.py input.txt \\\

### Step 8: Validate the Skill

Check these requirements:

✅ **File structure**:

- [ ] SKILL.md exists in correct location
- [ ] Directory name matches frontmatter `name`

✅ **YAML frontmatter**:

- [ ] Opening `---` on line 1
- [ ] Closing `---` before content
- [ ] Valid YAML (no tabs, correct indentation)
- [ ] `name` follows naming rules
- [ ] `description` is specific and < 1024 chars

✅ **Content quality**:

- [ ] Clear instructions for Claude
- [ ] Concrete examples provided
- [ ] Edge cases handled
- [ ] Dependencies listed (if any)

✅ **Testing**:

- [ ] Description matches user questions
- [ ] Skill activates on relevant queries
- [ ] Instructions are clear and actionable

### Step 9: Test the Skill

1. **Restart Claude Code** (if running) to load the Skill

2. **Ask relevant questions** that match the description:

   ```
   Can you help me extract text from this PDF?
   ```

3. **Verify activation**: Claude should use the Skill automatically

4. **Check behavior**: Confirm Claude follows the instructions correctly

### Step 10: Debug if needed

If Claude doesn't use the Skill:

1. **Make description more specific**:

   - Add trigger words
   - Include file types
   - Mention common user phrases

2. **Check file location**:

   ```bash
   ls ~/.claude/skills/skill-name/SKILL.md
   ls .claude/skills/skill-name/SKILL.md
   ```

3. **Validate YAML**:

   ```bash
   cat SKILL.md | head -n 10
   ```

4. **Run debug mode**:
   ```bash
   claude --debug
   ```

## Common patterns

### Read-only Skill

name: code-reader description: Read and analyze code without making changes. Use for code review, understanding codebases, or documentation. allowed-tools: Read, Grep, Glob

### Script-based Skill

name: data-processor description: Process CSV and JSON data files with Python scripts. Use when analyzing data files or transforming datasets.

Data Processor

Instructions

1. Use the processing script:

\\\bash python scripts/process.py input.csv --output results.json \\\

1. Validate output with:

\\\bash python scripts/validate.py results.json \\\

### Multi-file Skill with progressive disclosure

name: api-designer description: Design REST APIs following best practices. Use when creating API endpoints, designing routes, or planning API architecture.

API Designer

Quick start: See [examples.md](examples.md)

Detailed reference: See [reference.md](reference.md)

Instructions

1. Gather requirements
2. Design endpoints (see examples.md)
3. Document with OpenAPI spec
4. Review against best practices (see reference.md)

## Best practices for Skill authors

1. **One Skill, one purpose**: Don't create mega-Skills
2. **Specific descriptions**: Include trigger words users will say
3. **Clear instructions**: Write for Claude, not humans
4. **Concrete examples**: Show real code, not pseudocode
5. **List dependencies**: Mention required packages in description
6. **Test with teammates**: Verify activation and clarity
7. **Version your Skills**: Document changes in content
8. **Use progressive disclosure**: Put advanced details in separate files

## Validation checklist

Before finalizing a Skill, verify:

- [ ] Name is lowercase, hyphens only, max 64 chars
- [ ] Description is specific and < 1024 chars
- [ ] Description includes "what" and "when"
- [ ] YAML frontmatter is valid
- [ ] Instructions are step-by-step