| name | writing-skills |
| description | Use when creating or editing a SKILL.md file under .claude/skills/. Defines the TDD-for-documentation discipline, structure, and CSO rules that every amd-smi skill must follow. |
Writing Skills — amd-smi
Skills are reusable reference guides agents load on demand. They are NOT narratives, NOT one-off notes, NOT project-specific runbooks (those go in CLAUDE.md or repo memory).
Iron Law: NO SKILL WITHOUT A FAILING PRESSURE TEST FIRST.
If you have not watched an agent fail without the skill, you do not know what the skill needs to teach. Same RED-GREEN-REFACTOR cycle as TDD, applied to documentation.
When to Create a Skill
| Create when | Don't create when |
|---|
| Technique applies across multiple amd-smi tasks | One-off solution |
| Same mistake keeps recurring across sessions | Standard practice already in CLAUDE.md |
| Pattern needs judgment (not enforceable by lint/regex) | Mechanical rule — automate it instead |
| Captures hard-won amd-smi-specific knowledge | Pure VS Code/git/bash trivia |
Skill Types
- Technique — concrete steps (e.g.,
amdsmi-build-install, systematic-debugging)
- Discipline — enforces a rule under pressure (e.g.,
test-driven-development, verification-before-completion)
- Reference — lookup tables, API mappings, command catalogs (e.g.,
personal-bash-deploy)
File Layout
.claude/skills/<skill-name>/
SKILL.md # required
<supporting>.md # only for heavy reference (100+ lines) or reusable scripts
Naming: kebab-case, verb-first or gerund preferred. Prefix with amdsmi- only if the skill is amd-smi-domain-specific (build, test runner, packaging). Generic workflow skills (TDD, debugging, planning) stay unprefixed.
SKILL.md Template
---
name: skill-name
description: "Use when [specific triggering symptoms]. [What problem it addresses]."
---
# Skill Name
[1-2 sentence purpose. Core principle.]
## When to Use
- [Concrete symptom or trigger]
- [Another trigger]
**Don't use when:** [counter-cases]
## [Core content — table, checklist, or step-by-step]
## Common Mistakes
| Mistake | Fix |
|---------|-----|
| ... | ... |
Description Field Rules (CSO — Critical for Discovery)
The description is what determines whether an agent loads the skill. Get it wrong and the skill is invisible.
| ❌ Bad | ✅ Good |
|---|
"For TDD work" (vague) | "Use when implementing any feature or bugfix, before writing implementation code" |
"Write test → watch fail → minimal code → refactor" (summarizes workflow — agent will skip the body) | "Use when implementing any feature or bugfix, before writing implementation code" |
"I help with debugging" (first person) | "Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes" |
"For async tests" (no symptoms) | "Use when tests have race conditions, timing dependencies, or pass/fail inconsistently" |
Rules:
- Start with
"Use when ..."
- Third person, ≤ 500 chars
- Describe triggers/symptoms, NOT the workflow
- Include error-message keywords, tool names, file patterns agents would search for
- If amd-smi-specific, say so explicitly
Cross-Referencing Other Skills
**REQUIRED SUB-SKILL:** Use the `test-driven-development` skill before implementation.
**REQUIRED BACKGROUND:** You MUST understand `systematic-debugging` before using this.
Never @-link — that force-loads the file and burns context.
Token Budget
- Frequently-loaded skills: < 200 words
- Other skills: < 500 words
- Heavy reference: separate file, linked by relative path
Run wc -w SKILL.md before committing.
Anti-Patterns
| Anti-Pattern | Why Bad |
|---|
| Narrative ("In session 2026-04-12 we found...") | Not reusable |
| Multi-language examples (JS + Python + Go) | Maintenance burden, dilutes signal |
Restating project conventions already in CLAUDE.md | Duplication, drift |
| Workflow summary in description | Agent follows description, skips body |
applyTo frontmatter on a skill | Skills are on-demand — applyTo belongs on .claude/rules/*.md and .github/instructions/*.md |
Pressure-Test Before Committing
- RED: Give a fresh agent the trigger scenario without the skill. Record what it does wrong and the rationalizations it uses verbatim.
- GREEN: Write the minimal skill addressing those specific failures. Re-run — agent should now comply.
- REFACTOR: Find new rationalizations, add explicit counters (rationalization table, red-flags list). Repeat until bulletproof.
Discipline-Skill Hardening
If the skill enforces a rule (TDD, verification, root-cause-first), add:
- The Iron Law — single bold rule at the top
- Rationalization table — every excuse you've seen → reality counter
- Red Flags list — phrases that mean "STOP, you're rationalizing"
- "Violating the letter is violating the spirit" — cuts off the spirit-vs-letter loophole
Skill Creation Checklist
