ed/manual_slop
Private
Public Access
0
0
Fork 0
Code Activity

conductor(track): superpowers review section 14 — writing-skills (medium)

Browse Source
This commit is contained in:
ed
2026-07-05 13:31:22 -04:00
parent 16ede50988
commit 0b2bda5271
3 changed files with 75 additions and 242 deletions
Download Patch File Download Diff File Expand all files Collapse all files
conductor/tracks/superpowers_review_20260619/report.md
+75 -1
View File
@@ -857,7 +857,81 @@ The project's master-direct workflow is an intentional ARCH-DIFF. The skill appl
## 14. Writing Skills
<!-- Section 14 medium (100-250 LOC). Skill: writing-skills. Verdict pending. -->
## 14. Writing Skills
### 14.1 What the skill prescribes
The `writing-skills` skill is the meta-skill for creating skills. Core principle: "Writing skills IS Test-Driven Development applied to process documentation." REQUIRED BACKGROUND: superpowers:test-driven-development (the Iron Law applies). Personal skills live in agent-specific directories (`~/.claude/skills/` for Claude Code, `~/.agents/skills/` for Codex).
The TDD Mapping for Skills: Test case = pressure scenario with subagent; Production code = skill document (SKILL.md); Test fails (RED) = agent violates rule without skill (baseline); Test passes (GREEN) = agent complies with skill present; Refactor = close loopholes while maintaining compliance.
When to Create a Skill: Technique wasn't intuitively obvious; you'd reference this again across projects; pattern applies broadly (not project-specific); others would benefit. Don't create for: One-off solutions; standard practices well-documented elsewhere; project-specific conventions (put in CLAUDE.md); mechanical constraints (if enforceable with regex/validation, automate it).
Skill Types: Technique (concrete method with steps); Pattern (way of thinking); Reference (API docs, syntax guides).
SKILL.md Structure: YAML frontmatter (name, description); Overview (what is this, core principle 1-2 sentences); When to Use (small inline flowchart if decision non-obvious); Core Pattern (before/after comparison); Quick Reference (table for scanning); Implementation (inline code or link to separate file); Common Mistakes; Real-World Impact (optional).
Claude Search Optimization (CSO): Rich description field (description = when to use, NOT what the skill does; "Use when..." phrasing; third person; never summarize workflow); keyword coverage (error messages, symptoms, tools); descriptive naming (active voice, verb-first, gerunds); token efficiency (getting-started workflows <150 words; frequently-loaded skills <200 words; other skills <500 words).
Iron Law (same as TDD): NO SKILL WITHOUT A FAILING TEST FIRST. Applies to NEW skills AND EDITS to existing skills. "Write skill before testing? Delete it. Start over." "Edit skill without testing? Same violation."
Bulletproofing Skills Against Rationalization: Close every loophole explicitly; address "spirit vs letter" arguments; build rationalization table; create red flags list; update CSO for violation symptoms.
Skill Creation Checklist: RED (write failing test = pressure scenarios, run baseline, identify rationalizations); GREEN (write minimal skill = YAML frontmatter, "Use when" description, third person, keywords, address baseline failures, code inline or link); REFACTOR (close loopholes = identify NEW rationalizations, add explicit counters, build rationalization table, red flags list, re-test); Quality Checks (small flowchart, quick reference, common mistakes, no narrative); Deployment (commit + push).
### 14.2 Mapping to the project's existing pattern
The project has 5 MMA skills in `.agents/skills/` (mma-orchestrator, mma-tier1-orchestrator, mma-tier2-tech-lead, mma-tier3-worker, mma-tier4-qa) plus the mirrored `.gemini/skills/` (legacy). These are project-specific skills following a similar structure.
| Skill rule | Project equivalent | Where |
|---|---|---|
| "Personal skills live in ~/.agents/skills/" | The project's `.agents/skills/` directory has 5 MMA skills; mirrored in `.gemini/skills/` (legacy from Gemini CLI era) | `.agents/skills/`, `.gemini/skills/` |
| "SKILL.md Structure: name, description, Overview, When to Use, Core Pattern, Quick Reference" | The project's MMA skills follow a similar structure (skill name, persona, scope, responsibilities) but with project-specific headings | `.agents/skills/mma-tier3-worker/SKILL.md` (example) |
| "description = when to use, NOT what the skill does" | The project's MMA skill descriptions are persona-flavored ("Stateless Tier 3 Worker for surgical code implementation and TDD") rather than trigger-focused ("Use when X") | `.agents/skills/mma-tier3-worker/SKILL.md` |
| "REQUIRED BACKGROUND: superpowers:test-driven-development" | The project's MMA skills don't reference a TDD-equivalent skill (the TDD discipline is in `conductor/workflow.md` §"Task Workflow") | — |
| "TDD Mapping: pressure scenarios with subagent" | The project's MMA skills don't have pressure-scenario tests; the skills are documented but not tested via the skill's TDD-for-skills methodology | — |
| "Iron Law: NO SKILL WITHOUT A FAILING TEST FIRST" | n/a — the project's MMA skills were authored without explicit pressure-scenario testing | — |
| "Token efficiency: <150 / <200 / <500 words" | The project's MMA skills are 50-300 lines (~500-3000 words); not strictly enforced | — |
| "Cross-referencing Other Skills: skill name only, no @ links" | The project's MMA skills use markdown links to `conductor/workflow.md` and other doc files; no `@`-syntax force-loading | Project-wide |
| "When to Create a Skill: technique wasn't obvious; reusable; broadly applicable" | The 5 MMA skills were created when the 4-tier MMA was designed; they're stable since the `tier2_autonomous_sandbox_20260616` track | `conductor/tracks/tier2_autonomous_sandbox_20260616/` |
| "Don't create for project-specific conventions (put in CLAUDE.md)" | The project's conductor/ workflow + styleguides + AGENTS.md are the project-specific convention home; the MMA skills are the reusable pattern | Project-wide |
| "Directory Structure: skills/skill-name/SKILL.md" | The project uses `.agents/skills/mma-*/SKILL.md` | `.agents/skills/` |
| "Skills are NOT: Narratives about how you solved a problem once" | The project's MMA skills are principles + scope + responsibilities; not narrative | `.agents/skills/mma-*/SKILL.md` |
### 14.3 Where the project already follows the discipline
- **The `.agents/skills/` directory structure** is skill-compliant.
- **The 5 MMA skills are stable** (created 2026-06-XX, not modified frequently).
- **The cross-referencing pattern** uses markdown links to `conductor/workflow.md`, not `@`-syntax force-loading. This is skill-compliant.
- **The skill names follow verb-first / active-voice conventions**: mma-tier1-orchestrator (gerund form via noun "orchestrator"), mma-tier3-worker (gerund form), mma-orchestrator (gerund). Slightly different from the skill's "verb-first / active-voice" recommendation but consistent with project convention.
### 14.4 Where the project doesn't follow the discipline
- **No pressure-scenario testing.** The MMA skills were authored without explicit baseline-violation tests. The skills may have loopholes that surface under pressure but aren't codified.
- **No token-budget enforcement.** The MMA skills are 50-300 lines (well above the 150/200/500 word targets). They're not "frequently loaded" (the project doesn't auto-load them; they're loaded via Skill tool on demand), but they're longer than the skill recommends.
- **The MMA skill descriptions are persona-flavored** ("Stateless Tier 3 Worker for...") rather than trigger-focused ("Use when X"). Per the skill's CSO rule, "Description = When to Use, NOT What the Skill Does". This is an explicit divergence.
- **The Iron Law "NO SKILL WITHOUT A FAILING TEST FIRST"** is not applied to the project's MMA skills. The deferred rebuild may want to add pressure-scenario testing for each MMA skill.
### 14.5 Recommendations summary
The project follows the skill's structure but diverges on three points: descriptions are persona-flavored not trigger-focused; no pressure-scenario testing; longer than recommended. The deferred rebuild may want to:
- **HIGH:** Add pressure-scenario testing for each MMA skill. The Tier 1 Orchestrator, Tier 2 Tech Lead, Tier 3 Worker, Tier 4 QA, and mma-orchestrator skills should each have a baseline-violation scenario + a skill-with scenario. This is the project's largest gap with the skill.
- **MEDIUM:** Rewrite the MMA skill descriptions to be trigger-focused ("Use when X") rather than persona-flavored. The descriptions are loaded by agents to decide which skill applies; trigger-focused descriptions improve skill-selection accuracy.
- **LOW:** Compress the MMA skills to meet token-budget targets. They're loaded on demand, so the impact is small.
**Verdict.**
| Field | Value |
|---|---|
| **Primary** | `PARTIAL` |
| **Integration tag** | `INTEGRATE-PARTIAL` |
| **Section size** | medium |
| **Cross-refs** | nagent_review_20260608 §10 ("durable work" thesis shapes how skills are written); fable_review_20260617 §13 (project's skill-writing pattern is "genuinely useful"); intent_dsl_survey_20260612 §6 (the MMA skill architecture is documented as an "AI-agent property") |
**Rationale.** The project follows the skill's directory structure and cross-referencing pattern. The 5 MMA skills are stable. Three gaps: persona-flavored descriptions (instead of trigger-focused), no pressure-scenario testing (no Iron Law application), longer than recommended token budgets. The deferred rebuild should add pressure-scenario testing as the highest-priority improvement.
**Recommended change.** Add pressure-scenario testing for each MMA skill (HIGH); rewrite descriptions to be trigger-focused (MEDIUM); compress to token-budget targets (LOW).
## 15. MMA Skills Cluster