majiayu000 Skill Writing
Quick Start
Every skill needs a SKILL.md file with YAML frontmatter and markdown body:
---
name: Task Name (gerund form preferred)
description: What it does and when to use it (third person, specific)
---
# Task Name
[Concise instructions here]
Core Workflow
Copy and track your progress:
Skill Creation:
- [ ] Step 1: Identify the reusable pattern
- [ ] Step 2: Draft concise instructions
- [ ] Step 3: Add metadata (name, description)
- [ ] Step 4: Test with target model(s)
- [ ] Step 5: Iterate based on usage
Step 1: Identify the reusable pattern
What context do you repeatedly provide? What procedural knowledge is needed?
Step 2: Draft concise instructions
Start minimal. Claude is already smart - only add what Claude doesn't know.
Challenge each piece of information:
- Does Claude really need this explanation?
- Can I assume Claude knows this?
- Does this paragraph justify its token cost?
Step 3: Add metadata
Write description in third person, including:
- What the skill does
- When to use it (key terms and triggers)
description: Extract text from PDFs, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
Step 4: Test with target model(s)
- Haiku: Does it provide enough guidance?
- Sonnet: Is it clear and efficient?
- Opus: Does it avoid over-explaining?
Step 5: Iterate based on usage
Observe how Claude uses the skill. Watch for:
- Unexpected exploration paths
- Missed connections
- Overreliance on certain sections
- Ignored content
Set Appropriate Degrees of Freedom
Match specificity to task fragility:
High freedom (text instructions): Multiple approaches valid, context-dependent Medium freedom (pseudocode/templates): Preferred pattern exists, variation acceptable Low freedom (exact scripts): Operations fragile, consistency critical
Progressive Disclosure
Keep SKILL.md body under 500 lines. Split into separate files:
# SKILL.md
## Quick start
[Basic usage here]
## Advanced features
**Form filling**: See [FORMS.md](FORMS.md)
**API reference**: See [REFERENCE.md](REFERENCE.md)
Important:
- Keep references one level deep from SKILL.md
- Use forward slashes in paths (not backslashes)
- Add table of contents for files >100 lines
Common Patterns
Workflow pattern (complex tasks):
## Workflow
Copy this checklist:
- [ ] Step 1: Do first thing
- [ ] Step 2: Do second thing
[Detailed steps below]
Feedback loop (quality-critical):
1. Create output
2. Validate: `python scripts/validate.py`
3. If validation fails, fix and repeat
4. Only proceed when validation passes
Template pattern (consistent output):
ALWAYS use this exact structure:
[Template here]
Anti-Patterns to Avoid
❌ Windows-style paths (scripts\\helper.py)
✓ Unix-style paths (scripts/helper.py)
❌ Too many options ("You can use X, or Y, or Z...") ✓ Provide default with escape hatch ("Use X. For special case, use Y instead.")
❌ Time-sensitive info ("Before August 2025...") ✓ Use "Current method" and "Old patterns" sections
❌ Inconsistent terminology (mix "field", "box", "element") ✓ Choose one term, use consistently
❌ Deeply nested references (SKILL.md → advanced.md → details.md) ✓ One level deep (SKILL.md → details.md)
For Skills with Code
Utility scripts: Provide pre-made scripts rather than having Claude write them
- More reliable than generated code
- Save tokens and time
- Ensure consistency
Package dependencies: List required packages and verify availability
Visual analysis: Convert to images for Claude to analyze layouts
Verifiable outputs: Create plan files that get validated before execution
Quick Reference
Naming: Use gerund form ("Processing PDFs", "Analyzing Data")
Description: Third person, specific, includes when to use
File limit: Keep SKILL.md under 500 lines
Structure: YAML frontmatter + markdown body
Testing: Test with all target models
Conciseness: Assume Claude is smart, only add what's needed
Detailed Reference
For comprehensive guidance, see specs/skills-best-practices.md:
- Complete examples for all patterns
- Advanced progressive disclosure techniques
- Evaluation-driven development
- Runtime environment details
- MCP tool references