skills-write

name	skills:write
description	Create or edit skills with proper structure, task tracking, and naming conventions

Write / Edit Skill

Create new skills or edit existing ones. Both follow the same checklist and conventions.

Worktree Gate

All skill work MUST happen in a worktree. Before proceeding, verify you are in a worktree:

git worktree list

If not in a worktree, create one first:

git fetch upstream main

git worktree add .worktrees/skills-<topic> -b docs/skills-<topic> upstream/main

Table of Contents

• Skill Structure
• Frontmatter
• Content Guidelines
• Task Tracking Standard
• Checklist
• Template

New vs Edit

Action	Steps
New skill	Create directory + SKILL.md from template, fill in content, validate
Edit skill	Read existing file first, apply changes, re-validate, ensure diagram still matches text

For edits: always read the skill FIRST, then edit. Never overwrite without reading.

Skill Structure

.claude/skills/<category>:<skill-name>/
└── SKILL.md

IMPORTANT: Use colon notation in directory names (e.g., auth:my-skill/). Required for Claude Code skill discovery.

Categories should match your repo's tech stack (e.g., ci, git, k8s, orchestrate, rca, skills, tdd)

Frontmatter

---
name: category:skill-name
description: One-line description (what it does, not how)
---

Use colon notation in name: field. Directory name must match.

Content Guidelines

1. Title: # Skill Name
2. TOC: Include for skills over 50 lines
3. Length: Target 80-200 lines (300 max). Split longer skills.
4. Sections:
   • When to Use
   • Steps/Workflow
   • Workflow Diagram (required for workflow/router skills)
   • Task Tracking (required for workflow skills)
   • Troubleshooting
   • Related Skills
5. Style:
   • Imperative voice ("Run X", not "You should run X")
   • Real, copy-pasteable commands
   • Include expected output where helpful

Command Format and Auto-Approve

Skills must classify as sandbox or management to determine command format:

Type	Target	Auto-approve?
Sandbox	Kind cluster, custom HyperShift hosted cluster	YES
Management	Management cluster, AWS resources, git push, destructive ops	NO

Sandbox skills: One command per code block

Claude Code auto-approves commands by matching the first token against .claude/settings.json patterns. Chained commands (&&), multiline scripts, heredocs, and for loops break pattern matching.

IMPORTANT: Write each command as a separate code block:

Check pod status:
```bash
kubectl get pods -n my-namespace

Check logs:

kubectl logs -n my-namespace deployment/my-app

Do NOT chain: `kubectl get pods && kubectl logs ...`

### Management skills: Any format

Commands targeting management clusters or AWS need user approval anyway, so multiline/chained format is acceptable.

### Temporary Files

Skills that download logs, artifacts, or save analysis output should use a session-scoped temp directory:

```bash
mkdir -p /tmp/<project>/<skill-category>

Update settings.json

After writing a skill, verify all sandbox commands are covered by .claude/settings.json patterns. If a new command prefix is used, add it:

{
  "permissions": {
    "allow": [
      "Bash(new-command:*)"
    ]
  }
}

See skills:validate for the full pattern reference table.

Workflow Diagrams

Workflow skills (skills with phases, decision trees, or routing logic) MUST include:

1. Embedded mermaid diagram in the SKILL.md
2. Companion .mmd template file in the skill directory (for debug mode, TDD skills only)
3. Diagram MUST match textual flow exactly
4. Use README color scheme:

Category	classDef
TDD	classDef tdd fill:#4CAF50,stroke:#333,color:white
RCA	classDef rca fill:#FF5722,stroke:#333,color:white
CI	classDef ci fill:#2196F3,stroke:#333,color:white
Test	classDef test fill:#9C27B0,stroke:#333,color:white
Git	classDef git fill:#FF9800,stroke:#333,color:white
K8s	classDef k8s fill:#00BCD4,stroke:#333,color:white
Deploy	classDef deploy fill:#795548,stroke:#333,color:white
Skills	classDef skills fill:#607D8B,stroke:#333,color:white
GitHub	classDef github fill:#E91E63,stroke:#333,color:white
HyperShift	classDef hypershift fill:#3F51B5,stroke:#333,color:white
Playwright	classDef pw fill:#8BC34A,stroke:#333,color:white

Exempt from diagram requirement: pure index parents that only list sub-skills with no routing logic (e.g., git/, k8s/, auth/)

Task Tracking Standard

Every workflow skill (tdd, rca, ci, etc.) MUST include a Task Tracking section. This is the canonical reference for how Claude Code task lists work across all skills.

Task Naming Convention

<worktree> | <PR> | <plan-doc> | <topic> | <phase> | <task description>

• worktree: git worktree name or main repo name
• PR: PR reference (e.g., PR#42) or none
• plan-doc: plan filename or ad-hoc if no plan
• topic: area of work
• phase: from planning doc section/step, or blank if ad-hoc
• task: brief description

Examples:

• my-feature | PR#42 | plan.md | CI setup | Phase 2 | Add lint workflow
• main | none | ad-hoc | skills | | Create new skill

Task Lifecycle

1. On skill invocation:
   - TaskList → check existing tasks for this worktree/PR
   - Update completed items
   - Create new items for discovered work

2. Task metadata:
   - plan: path to plan doc or "ad-hoc" if none
   - runner: main-session | subagent | background

3. Dependencies:
   - Use addBlockedBy for sequential tasks
   - Parallel tasks have no blockers

4. Status reporting - always show plan doc in task name:
   | # | Status | Task (includes plan doc) |
   |---|--------|-------------------------|
   | #1 | in_progress | main \| none \| plan.md \| skills \| Create \| new skill |
   | #2 | completed | my-feature \| PR#42 \| ad-hoc \| CI \| Fix \| lint config |

Plan Doc Reference

Every task should reference its parent planning document:

• Tasks from a plan: metadata.plan = "<plan-file-path>"
• Ad-hoc tasks: metadata.plan = "ad-hoc"
• Tasks without a plan doc indicate work that needs retroactive documentation

Checklist

Before committing a new skill:

• Frontmatter has name and description
• Directory uses colon notation
• Name in frontmatter matches directory name
• TOC included if over 50 lines
• Commands are copy-pasteable
• Task Tracking section present (for workflow skills)
• Troubleshooting section exists
• Related Skills section exists
• Mermaid diagram present (for workflow/router skills)
• Diagram matches textual workflow exactly
• Diagram uses classDef colors from README color legend
• Parent category SKILL.md updated with reference

Template

---
name: category:skill-name
description: Brief description of what this skill does
---

# Skill Name

## When to Use

- Condition 1
- Condition 2

## Workflow

1. Step one
2. Step two

## Workflow Diagram

```mermaid
flowchart TD
    START(["/category:skill"]) --> STEP1["Step 1"]:::category
    STEP1 --> STEP2["Step 2"]:::category

    classDef category fill:#COLOR,stroke:#333,color:white

Task Tracking

On invocation:

1. TaskList - check existing tasks
2. TaskCreate with naming: <worktree> | <PR> | <topic> | <phase> | <task>
3. TaskUpdate as work progresses

Troubleshooting

Problem: Description

Symptom: What you see Fix: How to resolve

Related Skills

• category:related-skill

## Related Skills

- `skills:validate` — Check skill format compliance
- `skills:scan` — Audit skills for gaps and quality