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:

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?

Keep it focused: One Skill = one capability

• Good: "PDF form filling", "Excel data analysis"

• 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) 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.

### 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:
```markdown
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

- 
Restart Claude Code (if running) to load the Skill

- 
Ask relevant questions that match the description:

Can you help me extract text from this PDF?

- 
Verify activation: Claude should use the Skill automatically

- 
Check behavior: Confirm Claude follows the instructions correctly

Step 10: Debug if needed

If Claude doesn't use the Skill:

- 
Make description more specific:

- Add trigger words

- Include file types

- Mention common user phrases

- 
Check file location:

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

- 
Validate YAML:

cat SKILL.md | head -n 10

- 
Run debug mode:

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
\`\`\`

2. 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

- One Skill, one purpose: Don't create mega-Skills

- Specific descriptions: Include trigger words users will say

- Clear instructions: Write for Claude, not humans

- Concrete examples: Show real code, not pseudocode

- List dependencies: Mention required packages in description

- Test with teammates: Verify activation and clarity

- Version your Skills: Document changes in content

- 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

-  Examples are concrete and realistic

-  Dependencies are documented

-  File paths use forward slashes

-  Skill activates on relevant queries

-  Claude follows instructions correctly

Troubleshooting

Skill doesn't activate:

- Make description more specific with trigger words

- Include file types and operations in description

- Add "Use when..." clause with user phrases

Multiple Skills conflict:

- Make descriptions more distinct

- Use different trigger words

- Narrow the scope of each Skill

Skill has errors:

- Check YAML syntax (no tabs, proper indentation)

- Verify file paths (use forward slashes)

- Ensure scripts have execute permissions

- List all dependencies

Examples

See the documentation for complete examples:

- Simple single-file Skill (commit-helper)

- Skill with tool permissions (code-reviewer)

- Multi-file Skill (pdf-processing)

Output format

When creating a Skill, I will:

- Ask clarifying questions about scope and requirements

- Suggest a Skill name and location

- Create the SKILL.md file with proper frontmatter

- Include clear instructions and examples

- Add supporting files if needed

- Provide testing instructions

- Validate against all requirements

The result will be a complete, working Skill that follows all best practices and validation rules.