- name
- skill-acquisition
- description
- Create, document, or revise Codex skills, including deciding when to add scripts/references/assets, structuring SKILL.md content, enforcing the 500-line rule, and updating repo references (AGENTS.md, kanban evidence).
Skill Acquisition
Scope
- Document or update a skill in this repo.
- Keep skill guidance concise while covering structure, resources, and validation.
Workflow
- Confirm the skill goal, triggers, and expected outputs.
- Pick a short, hyphenated skill name (folder name and frontmatter
namematch). - Create
skills/<skill-name>/SKILL.mdwith YAML frontmatter:
- name: skill name. - description: when to use the skill and what it enables.
- Draft the SKILL.md body in imperative form:
- Keep to actionable steps, not general explanations. - Prefer short checklists and decision points.
- Decide on bundled resources:
- scripts/ for repeated deterministic steps. - references/ for long or variant-specific guidance. - assets/ for templates or files used in outputs.
- Enforce the 500-line rule:
- Keep SKILL.md under 500 lines. - Split large guidance into references/ and link it from SKILL.md. - Optionally run scripts/check-file-lengths.sh.
- Update repo references:
- Add the skill path to AGENTS.md (skills block). - Update the relevant kanban card with summary and evidence link.
Structure Checklist
skills/<skill-name>/SKILL.mdexists and uses required frontmatter only.- SKILL.md includes: scope, workflow, resource guidance, and 500-line rule.
- Resources exist only when needed; avoid unused folders.
- References are linked directly from SKILL.md (one level deep).
Troubleshooting
- Missing init script: create the folder and SKILL.md manually.
- SKILL.md too long: move detailed sections into
references/and link them. - Evidence missing: add direct paths in the kanban card links section.