| name | formax-skill-capture |
| description | Use when we want to turn a just-finished Formax workflow (e.g. commands, overlays, tools, hooks, permissions, UI parity) into a reusable Codex Skill under .codex/skills, including scaffolding, guardrails, and the minimum test checklist. |
Formax skill capture (create skills from our workflow)
What this is
This skill is a Formax-specific wrapper around skill authoring: it helps us reliably convert “we just figured out how to do X” into a repo-local skill under .codex/skills/<skill-name>/.
It complements the built-in skill-creator (system skill) by adding Formax conventions:
- repo-local skills (checked into git)
- “where to change what” file map
- invariants (UI parity, model injection orthogonality, etc.)
- minimum regression tests to lock behavior
When to use
Trigger this when the user says:
- “把这个流程沉淀成 skill”
- “以后别再忘了怎么改 /xxx”
- “给我一个复用的修改清单/固定套路”
Minimal questions to ask (do not proceed until answered)
- Skill name (kebab-case), e.g.
formax-slash-command-workflow
- 1–2 sentence description: when should Codex use it?
- Scope: which subsystem? (pick one)
- slash commands / overlays
- tools (spec/handler/presenter)
- hooks
- permissions/policy
- stability/input routing
- Any explicit “don’t change” constraints? (UI copy/spacing/colors, contracts, etc.)
Output requirements
The resulting skill must include:
- a short “Goal” section
- “Where to change what” (file list)
- “Patterns” (2–4 common patterns)
- “Tests to update” (minimum regression set)
- “Guardrails” (what must not regress)
Avoid long prose; prefer checklists.
Create a new skill (scaffold)
Use the scaffold script:
bash .codex/skills/formax-skill-capture/scripts/new-skill.sh <skill-name> "<description>"
Then fill SKILL.md body with the content above.
Refactor policy for skills
When a skill is created from a workflow we already shipped:
- Do not broaden scope (no extra features)
- Do not rewrite UI (unless explicitly requested)
- Write/extend tests first if behavior has regressed before
