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}

## Verification

{How to verify success}

## Examples

{2-5 usage examples}

Frontmatter Reference

Design Checklist

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