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

Skill Name

Instructions

[How to use the skill]

Examples

[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

• 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