howto-skill-workflow

Howto Skill Workflow

1. Mode & Protocol

MODE: AUSTERE REFERENCE (Diataxis) ROLE: Skill Lifecycle Orchestrator CONSTRAINT: Thin FCIS shell. Load references per-intent only.

*** PROCESS GATE — MANDATORY BEFORE ANY EDIT *** BEFORE touching any file: (1) BRAINSTORM — diverge 12-20 approaches, converge, confirm confidence ≥ 9/10. (2) BIG-FISH CHECK — ask "Does this change improve the skill's ability to produce better skills?" IF answer is "it just passes gates" → STOP, rethink. (3) ONLY THEN proceed to Decision Matrix. FAILURE TO BRAINSTORM FIRST = PROCESS VIOLATION. The validator catches structural errors. Nothing else catches process errors. This gate is your only enforcement. *** END PROCESS GATE ***

---

2. Global Invariants

MUST enforce on every execution. NEVER skip.

Invariant	Rule
UID Gate	Every reference file MUST have uid (8-char hex) + # NO LEETSPEAK. Mismatch → STOP.
FCIS Separation	Frontmatter = tooling shell; body = pure LLM dispatch; references/ = on-demand knowledge.
4-Part Description	Every skill MUST use WHAT/WHEN/DO NOT/Guarantee format; ≤350 chars.
Auto-Validation	Every create/edit route chains to validate_skill.py unless --skip-validation.
Recursion Guard	Track call depth. IF depth > 2 → STOP, return cached analysis.
Self-Reference	IF target is howto-skill-workflow → Bootstrap Mode: load skillscore-rubric + boolean-gates + validation-pyramid, apply stricter thresholds.
Brainstorm-First	Every create/edit route MUST execute structured-brainstorm (diverge → converge) before execution. Iterate until confidence ≥ 9/10.
Skill Boundary	General file editing → general tools. Installing skill systems → not supported. Blockchain/auth/observability → delegate to domain skills.
Big-Fish Lens	Every change MUST improve the skill's ability to produce better skills. IF gates pass but outcome didn't improve → question the gates.

---

3. Decision Matrix

Locate matching row. Load ALL files in Artifacts column.

User Intent	Action	Complexity/Risk	Artifacts
"Create a skill for X"	Load artifacts → brainstorm → init_skill.py → validate	High/Low	references/first-principles-manifesto.md, references/architecture-anatomy.md, references/authoring-standards.md, references/process-enforcement.md
"Edit/fix my skill"	Load artifacts → brainstorm → destructive review → rebuild	High/Medium	references/first-principles-manifesto.md, references/materiality-gate.md, references/process-enforcement.md
"Validate skill quality"	Load artifacts → run validate_skill.py → report	Low/Low	references/skillscore-rubric.md, references/boolean-gates.md, references/validation-pyramid.md
"Challenge my skill assumptions"	Load artifacts → brainstorm → destructive review (inline, no delegation)	High/Medium	references/first-principles-manifesto.md, references/materiality-gate.md
General file editing	STOP — Redirect to general file tools	—	—
"Install skill system"	STOP — Not supported	—	—
Delete a skill	STOP — Manual deletion required	—	—
"List all skills"	STOP — Use glob directly	—	—

Create/Edit Execution Protocol

1. Brainstorm: Diverge (12-20 approaches) → Converge → Synthesize. IF confidence < 9/10 → iterate (max 3 cycles).
2. Challenge: List every validator rule optimized for. IF content exists only to pass validation → DELETE it. IF rule produces worse outcomes → FLAG it.
3. Review: Apply mutation lens (rotated). Produce Delta Report (Kept/Replaced/Added/Removed).
4. Rebuild: Bottom-up reconstruction (Deletion Categories from first-principles-manifesto.md).
5. Validate: Run validate_skill.py (auto-chained unless --skip-validation).
6. Verify: IF gates fail → return to step 1. IF gates pass → output results.

Validate Execution Protocol

1. Load: Read all artifacts from matched Decision Matrix row.
2. Run: Execute validate_skill.py against target skill.
3. Report: Output skill_name, skillscore, gates_passed, verdict.

---

4. Contrastive Exemplars

✅ CORRECT: Thin FCIS Shell

Phase	Content
Trigger	User: "Create a skill for Docker optimization"
SKILL.md	80 lines: frontmatter + Invariants + Routing + Exemplars
Result	Skill loads fast, routing clear, maintainable

❌ FAIL: Thick Shell with Embedded Logic

Phase	Content
Trigger	User: "Create a skill for Docker optimization"
SKILL.md	400 lines with full step-by-step procedures
Result	Violates FCIS; workflow logic belongs in references/

Why: Thick shells dilute attention, violate P1 (token economy), make routing ambiguous.

✅ CORRECT: Intent Disambiguation

User Says	Routed To
"Create a skill for X"	create_skill
"Fix my skill, it's broken"	edit_skill
"Validate this skill"	validate_skill
"Challenge my skill"	apply_mutation_lens
"Rebuild from scratch"	edit_skill (bottom-up)
"Brainstorm improvements"	edit_skill (brainstorm-only)

❌ FAIL: Ambiguous Routing

User Says	Problem
"Check my skill"	validate or edit? Clarify first.
"Make my skill better"	edit or mutation lens? Clarify first.

Resolution: Load first-principles-manifesto.md + materiality-gate.md → classify via materiality test.

❌ FAIL: Skipped Brainstorm (Process Violation)

Phase	Content
Trigger	User: "Improve this skill recursively"
Action	Read all files → immediately start editing boolean-gates.md, skillscore-rubric.md
Result	Fixed doc/validator mismatches but missed the actual problem: unenforced process invariants

Why: Agent read "MUST brainstorm" as documentation to fix, not as an instruction to follow. Declarative invariants in the attention-attenuated middle have no enforcement mechanism. Process gates MUST use directive syntax in primacy/recency positions (Sandwich Pattern from directive-prompting.md).

---

5. Anti-Patterns

Pattern	Status	Reason
Loading references not in matched intent	FORBIDDEN	Violates FCIS loading rule
Generating before loading artifacts	FORBIDDEN	Misses structural constraints
Skipping UID verification	FORBIDDEN	Broken cross-references
Weak modals (should, could, consider)	FORBIDDEN	Ambiguous instructions
Mixing REFERENCE and HOW-TO modes	FORBIDDEN	Diataxis violation
Recursing beyond depth 2	FORBIDDEN	Infinite loop risk
Delegating mutation_lens externally	FORBIDDEN	Must be inline only
Editing without brainstorm divergence	FORBIDDEN	Misses better approaches
Optimizing for validator over quality	FORBIDDEN	Closed-loop delusion
NEVER skip validate_skill.py on create	NEVER	Unvalidated skills are unsafe

*** RUNTIME CONTRACT — RECENCY ENFORCEMENT *** BEFORE generating final output, verify:

1. DID YOU BRAINSTORM? IF no divergent approaches were generated → STOP. You skipped the Process Gate.
2. DID YOU APPLY BIG-FISH LENS? IF changes only fix gates without improving output quality → STOP. You optimized for the validator.
3. Run validate_skill.py. Output MUST include gates_passed and Delta Report if edits occurred. The validator catches structural errors. This contract catches process errors. Both MUST pass. *** END RUNTIME CONTRACT ***