Writing Skills

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

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.

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

Pressure-Test Before Committing

1. RED: Give a fresh agent the trigger scenario without the skill. Record what it does wrong and the rationalizations it uses verbatim.
2. GREEN: Write the minimal skill addressing those specific failures. Re-run — agent should now comply.
3. REFACTOR: Find new rationalizations, add explicit counters (rationalization table, red-flags list). Repeat until bulletproof.

For a technique/reference skill whose commands an agent must run (not just a discipline rule), the single-pass RED-GREEN-REFACTOR above is not enough — iterate it as a loop against a known-answer fixture until a literal run is deterministic, then minimize. Use the pressure-testing-skills skill for that method.

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

• Ran pressure test without skill — documented baseline failure
• name is kebab-case, no special chars
• description starts with "Use when", lists symptoms, no workflow summary
• Single excellent example (not multi-language)
• Rationalization table (if discipline skill)
• wc -w under target
• No duplication with CLAUDE.md or other skills
• Re-ran pressure test with skill — agent complies