Skillwriting

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](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