srnnkls/skill

Skill Creation

Create well-structured skills using progressive disclosure and project conventions.

Reference: best-practices.md for comprehensive guidance, reference.md for project patterns and frontmatter specs.

---

Workflow

Step 1: Understand Use Cases

Gather concrete examples of how the skill will be used:

• What tasks will it handle?
• What would users say to trigger it?
• What variations exist?

Skip this step only when usage patterns are already clearly understood.

Step 2: Plan Contents

Analyze each use case to identify reusable resources:

| Resource Type | When to Use | Example | |---------------|-------------|---------| | scripts/ | Same code rewritten repeatedly | rotate_pdf.py | | reference/ | Domain knowledge Claude needs | schema.md, api.md | | assets/ | Files used in output | template.html, logo.png | | templates/ | Document structure patterns | report.md |

Step 3: Choose Frontmatter

Required fields:

name: skill-name          # Lowercase, hyphens, max 64 chars
description: |            # Max 1024 chars
  [What it does]. Use when [context].

Optional fields:

| Field | Purpose | Example | |-------|---------|---------| | context | Run in forked subagent | context: fork | | agent | Specify agent type | agent: haiku | | user-invocable | Hide from slash menu | user-invocable: false | | allowed-tools | Restrict available tools | See reference.md | | hooks | Lifecycle hooks (PreToolUse, PostToolUse, Stop) | See reference.md |

Naming pattern: <namespace>[-<subnamespace>]-<action>

• dispatch, scope, git worktree

Description format: Third person, what + when.

• "Generate GitHub issue drafts from spec directories. Use when converting specs to GitHub issues."

Step 4: Create Structure

mkdir -p .claude/skills/{skill-name}

Standard structure:

.claude/skills/{skill-name}/
├── SKILL.md              # Main instructions (<500 lines)
├── templates/            # Document templates (.md)
├── scripts/              # Executable code (.sh, .py)
└── reference/           # Extended documentation

Step 5: Implement & Test

Write SKILL.md:

• Keep under 200 lines (500 max)
• Progressive disclosure: SKILL.md → reference/
• Include concrete examples, no emojis
• Reference authoritative docs (don't duplicate)

Test with real tasks:

1. Does the description trigger correctly?
2. Can Claude find bundled resources?
3. Does the workflow complete successfully?

---

Degrees of Freedom

Match specificity to task fragility:

High freedom - Multiple approaches valid, context-dependent:

## Code review
1. Analyze structure and organization
2. Check for bugs and edge cases
3. Suggest improvements

Low freedom - Operations fragile, consistency critical:

## Database migration
Run exactly: `python scripts/migrate.py --verify --backup`
Do not modify flags.

---

Skill Types

| Type | Characteristics | Examples | |------|-----------------|----------| | Operational | Multi-step workflow, state changes, document templates | scope | | Generation | Transform input → structured output, format templates | docs-implement | | Guidance | Imperative instructions, code patterns | implement, loqui |

---

Success Criteria

• Name follows <namespace>[-<subnamespace>]-<action>
• Description is third person with what + when
• SKILL.md under 200 lines (500 max)
• Workflow steps numbered and actionable
• Templates extracted to separate files
• References point to authoritative sources
• No emojis (text markers only)

---

Reference

• best-practices.md - Core principles, patterns, checklist
• reference.md - Project patterns, frontmatter specs, anti-patterns