Create/Refactor Skill

Trigger

• Keywords: create skill, new skill, build skill, refactor skill, update skill, restructure skill

Workflow

┌─────────────────────────────────────────────────────────────────┐
│         Phase 1: Confirm Objective                              │
├─────────────────────────────────────────────────────────────────┤
│ 1. New or Refactor?                                             │
│ 2. Skill name (kebab-case)                                      │
│ 3. Purpose (one sentence)                                       │
│ 4. Trigger keywords                                             │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│         Phase 2: Choose Vehicle                                 │
├─────────────────────────────────────────────────────────────────┤
│ ┌─────────────┬────────────────────────────────────────────┐    │
│ │ Vehicle     │ Applicable Scenario                        │    │
│ ├─────────────┼────────────────────────────────────────────┤    │
│ │ CLAUDE.md   │ Global, always needed, stable rules        │    │
│ │ Skill       │ On-demand, domain knowledge, workflows     │    │
│ │ Hook        │ Every time, zero exceptions (lint, blocks) │    │
│ │ Subagent    │ Heavy file reading, isolated context       │    │
│ └─────────────┴────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│         Phase 3: Design Structure                               │
├─────────────────────────────────────────────────────────────────┤
│ skills/{name}/                                          │
│ ├── SKILL.md              # Workflow (loaded on trigger)        │
│ ├── references/           # Knowledge base (read on demand)     │
│ │   └── *.md                                                    │
│ └── scripts/              # Executable scripts (deterministic)  │
│     └── *.sh                                                    │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│         Phase 4: Write SKILL.md                                 │
├─────────────────────────────────────────────────────────────────┤
│ 1. Frontmatter (name, description, allowed-tools, context)      │
│ 2. When to use / NOT to use                                     │
│ 3. Workflow (step-by-step)                                      │
│ 4. Verification method                                          │
│ 5. Examples (2-5)                                               │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│         Phase 5: Verify                                         │
├─────────────────────────────────────────────────────────────────┤
│ 1. Trigger test: Does keyword correctly load the skill?         │
│ 2. Flow test: Execute complete workflow                         │
│ 3. Edge test: Error input handling                              │
└─────────────────────────────────────────────────────────────────┘

SKILL.md Template

---
name: { kebab-case-name }
description: { One sentence describing purpose and trigger }
allowed-tools: Read, Grep, Glob, Write
context: fork
---

# {Title} Skill

## Trigger

- Keywords: {trigger keywords}

## When NOT to Use

- {scenarios where this skill should not be used}

## Workflow

{Step-by-step flow, using ASCII or Mermaid}

## Output

- `skills/<name>/SKILL.md` — Skill definition with routing signature
- `commands/<name>.md` — Command entry point
- `skills/<name>/references/` — Reference docs (if needed)

## Verification

{How to verify success}

## Examples

{2-5 usage examples}

Frontmatter Reference

Field	Description	Default
name	Unique identifier (kebab-case)	Required
description	Trigger description (with keywords)	Required
allowed-tools	Restrict available tools	All
context	fork (isolated) / none (shared)	Shared
agent	Explore / Plan etc.	None
disable-model-invocation	Prevent model auto-triggering	false
user-invocable	Whether it appears in / menu	true

Design Checklist

Item	Check
Description is clear	One sentence explaining "what it does + when to use"
SKILL.md is concise	Only essential info; extras go to references
Fragile flows are protected	deploy/commit -> disable-model-invocation
Mechanical steps use scripts	With I/O contract documented in SKILL.md
Hard rules use hooks	Not relying on plain text instructions
Has verification method	Tests/lint/command output

Refactoring Pattern

When refactoring an existing skill:

1. Read existing SKILL.md - Understand current structure
2. Identify issues - Too long? Inaccurate triggers? Missing verification?
3. Apply guidelines - Reference references/skill-design-guide.md
4. Simplify content - Move details to references
5. Test triggers - Confirm keywords still work

References

For detailed design guidelines, see: skill-design-guide.md

Related Skills

Skill	Purpose
doc-review	Document review
tech-spec	Technical spec
feature-dev	Feature dev workflow