| 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
- Brainstorm: Diverge (12-20 approaches) → Converge → Synthesize. IF confidence < 9/10 → iterate (max 3 cycles).
- Challenge: List every validator rule optimized for. IF content exists only to pass validation → DELETE it. IF rule produces worse outcomes → FLAG it.
- Review: Apply mutation lens (rotated). Produce Delta Report (Kept/Replaced/Added/Removed).
- Rebuild: Bottom-up reconstruction (Deletion Categories from first-principles-manifesto.md).
- Validate: Run
validate_skill.py (auto-chained unless --skip-validation).
- Verify: IF gates fail → return to step 1. IF gates pass → output results.
Validate Execution Protocol
- Load: Read all artifacts from matched Decision Matrix row.
- Run: Execute
validate_skill.py against target skill.
- 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:
- DID YOU BRAINSTORM? IF no divergent approaches were generated → STOP. You skipped the Process Gate.
- DID YOU APPLY BIG-FISH LENS? IF changes only fix gates without improving output quality → STOP. You optimized for the validator.
- 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 ***
