howto-skill-workflow

name	howto-skill-workflow
description	Creates and validates skill artifacts with FCIS architecture. Use when the user requests to create, fix, validate, or challenge skills. Do not use for general file editing or installing skill systems. Guarantees FCIS-compliant skills via G1-G9 gate validation and destructive review.
compatibility	claude-code, opencode
metadata	{"version":"6.0.0"}

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 ***