writing-super-skills

Writing Super Skills

Creating a Super Skill IS TDD applied to process documentation.

REQUIRED BACKGROUND: Understand tdd-verified and verification-before-completion before writing skills. Same Iron Laws apply to documentation.

Authoring fundamentals: CSO (description = triggers only, never workflow summary), token efficiency (< 600 words), flowcharts only for non-obvious decisions, one excellent example over many mediocre ones. This skill focuses on Super Skills–specific requirements and VHEATM quality gates on top of those fundamentals.

---

What Makes a Super Skill Different

A Superskills skill encodes technique. A Super Skill encodes technique + VHEATM verification gates.

Every Super Skill must have:

Element	Superskills	Super Skills
Trigger condition	✅	✅
Workflow steps	✅	✅
Rationalization prevention	✅	✅
Evidence anchors	❌	REQUIRED
Idempotency guard	❌	REQUIRED
Loop/escalation path	❌	if bidirectional
Schema reference	❌	if writing to KB

---

RED-GREEN-REFACTOR for Super Skills

RED: Baseline

Run scenarios WITHOUT the skill. Document exactly:

• What did the agent do wrong?
• What rationalization did it use?
• Did it produce a VHEATM artifact without evidence anchors?
• Did it re-run and append a duplicate section?

GREEN: Write Minimal Skill

Address those specific failures. Structure:

---
name: [verb-noun, e.g., audit-design]
description: Use when [triggering condition only — no workflow summary]
---

# [Skill Name]

[One-sentence core principle]

## [Trigger / When to Use]
[Condition that fires this skill, including any flag checks]

## Idempotency Check
[How to detect if this skill already ran — prevent duplicate output]

## [Main Steps]
[Numbered, each with evidence gate where output is produced]

## Output Format
[Exact format for KB artifacts — reference shared/pattern-debt-schema.md if applicable]

## Red Flags — Never
[Explicit loophole closures]