| 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
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
- Title:
# Skill Name
- TOC: Include for skills over 50 lines
- Length: Target 80-200 lines (300 max). Split longer skills.
- Sections:
- When to Use
- Steps/Workflow
- Workflow Diagram (required for workflow/router skills)
- Task Tracking (required for workflow skills)
- Troubleshooting
- Related Skills
- 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:
- Embedded mermaid diagram in the SKILL.md
- Companion
.mmd template file in the skill directory (for debug mode, TDD skills only)
- Diagram MUST match textual flow exactly
- 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 workflowmain | 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:
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:
- TaskList - check existing tasks
- TaskCreate with naming:
<worktree> | <PR> | <topic> | <phase> | <task>
- TaskUpdate as work progresses
Troubleshooting
Problem: Description
Symptom: What you see
Fix: How to resolve
Related Skills
## Related Skills
- `skills:validate` — Check skill format compliance
- `skills:scan` — Audit skills for gaps and quality
