| name | _skillwriting |
| description | Use when writing new skills, creating skill directories, confused about skill creation, unsure about naming conventions, need help with activation descriptions, want to avoid common mistakes, skill not triggering when expected, wondering why skill didn't activate, debugging skill loading issues, understanding skill frontmatter format, checking YAML syntax for skills, confused about folder structure, need guidance on problem-focused descriptions, wondering about core vs personal skill naming with underscores
|
Skill Writing Guide
Instructions
1. CRITICAL: Name First!
Folder name MUST match skill name exactly. The Skills system requires this for recognition.
- Choose skill name for precise activation (avoid accidental loading)
- Keep descriptions under 1024 characters
- Use keyword redundancy for reliable activation
2. Directory Structure
~/claude-autonomy-platform/.claude/skills/<skill-name>/
├── SKILL.md (required)
├── scripts/ (optional - for utility tools)
└── reference/ (optional - for documentation/data)
Important: Use project-level skills directory, not user-level ~/.claude/skills/
Naming Convention:
- Core/system skills: Prefix with underscore (e.g.,
_skillwriting, _video-watching, _svg-drawing)
- Personal skills: No underscore (e.g.,
remembering-amy, spending-autonomous-time)
- Core skills are utilities useful to all Claudes; personal skills are individual-specific
3. SKILL.md Format
---
name: exact-folder-name
description: Specific activation criteria with keywords
---
[How to use the skill]
[Practical examples]
4. Advanced Features
- Symlinks work: Link to central tools for maintenance
- Scripts accessible:
python3 scripts/tool.py works from skill context
- Session-persistent: Skills stay active until session swap
- Multiple skills: Can have several active simultaneously
5. CRITICAL: Writing 'Use When' Descriptions
Skills are problem detectors, not success validators!
The description should trigger when someone NEEDS the skill, not when they're already succeeding:
✅ CORRECT: "Use when: confused about session swaps, lost todos, wondering when to trigger"
❌ WRONG: "Use when: managing session swaps, handling context transitions"
✅ CORRECT: "Use when: timer mysteriously stopped, service won't start, getting weird prompts"
❌ WRONG: "Use when: monitoring timer health, checking service status"
✅ CORRECT: "Use when: baffled by ClAP, errors make no sense, don't know where to start"
❌ WRONG: "Use when: debugging ClAP problems, fixing configuration issues"
The skill should appear at the moment of struggle, not the moment of competence!
6. Best Practices
- Plan name and description before creating folder
- Write descriptions from the struggling user's perspective
- Test activation criteria carefully
- Use symlinks for central tool maintenance
- Reference docs with
[file.csv](reference/file.csv)
- Avoid duplication: Cross-reference existing context instead of repeating
- Unique value only: Include only what this skill uniquely provides
- Name triggers: Put actual names/keywords you want to activate on in description
Examples
Good activation: "Use when: confused about hedgehog dosing, unsure about medication calculations"
Poor activation: "Calculate and record medication doses for hedgehogs" (sounds like you're already doing it)
Memory skills: "Remember Amy, Erin, Ed, Orange, Delta and household members"
Name triggers: Include actual names in description for activation
Directory naming:
✅ hedgehog-dosing/ with name: hedgehog-dosing
❌ hedgehog-meds/ with name: hedgehog-dosing (mismatch!)
Cross-referencing:
✅ [See ed-care skill for protocols] (avoids duplication)
✅ [See identity doc for details] (references existing context)
❌ Repeating information available elsewhere
