Writing Skills

Create skill files with proper frontmatter + imperative step-by-step instructions.

Steps

1. Parse Arguments

Extract from $ARGUMENTS:

• •Skill name (kebab-case)
• •Brief description

Ask user if either is missing.

2. Gather Requirements

If unclear from description, ask:

• •Trigger phrases for description field
• •Orchestration (delegates to Task subagents) or direct (edits files itself)?
• •Arguments accepted?

3. Reference Existing Skills

Read 2-3 existing skills for current conventions:

ls skills/*/SKILL.md

Match the frontmatter style, heading structure, and tool lists used in the codebase.

4. Create Skill File

mkdir -p skills/{skill-name}

Write skills/{skill-name}/SKILL.md with this structure:

---
name: {skill-name}
description: >
  {What it does + when to use.}
  Triggers: '{trigger1}', '{trigger2}'.
allowed-tools: {Tool1}, {Tool2}
argument-hint: "{args}"
---

# {Skill Title}

{One-line summary.}

## Arguments

- `<arg>` — description
- `--flag` — description

## Steps (or ## Workflow)

### 1. {First Step}

{Imperative instructions.}

5. Verify

• •name matches directory name
• •description includes trigger phrases
• •allowed-tools is comma-separated on one line (current convention), minimal for the task
• •Instructions use imperative voice
• •Prose wrapped at 80 characters
• •No user-invocable field (removed from convention)

6. Tool Selection Reference

Pick minimal tool set based on skill type:

Notes:

• •Orchestration skills use Task to spawn subagents for heavy work (see explore, review, implement)
• •Direct-action skills edit files themselves
• •Team tools only needed for multi-agent swarm coordination
• •Most skills also include Glob and Grep for search

Beads Integration

Skills that create or track work should use the bd CLI for state storage instead of filesystem documents.

Common Patterns

• •Create a tracking bead: bd create "<title>" --type task with --description containing acceptance criteria
• •Validate: bd lint <id> after creation — fix with bd edit <id> --description if lint fails
• •Store findings: bd update <id> --design "<content>" for plans, exploration results, or review findings
• •Store notes: bd update <id> --notes "<content>" for branch links, session notes, or metadata
• •Track status: bd update <id> --status in_progress and bd close <id> when done
• •Read context: bd show <id> --json to extract fields

When to Integrate Beads

• •Skill creates trackable work → create a bead
• •Skill produces structured output → store in design field
• •Skill needs to resume across sessions → use beads as state store
• •Skill is fire-and-forget (e.g., git-only) → skip beads

Bead Description Format

Always include acceptance criteria in descriptions:

bd create "Review: feature-branch" --type task --priority 2 \
  --description "$(cat <<'EOF'
## Acceptance Criteria
- Specific, testable outcomes
- Stored in bead design field
EOF
)"