MCAF: Skill Curation

MCAF: Skill Curation

Outputs

• New/​updated skill folders under your agent’s skills directory with valid SKILL.md frontmatter and lean workflows
• Updated YAML description triggers for correct matching
• A generated <available_skills> block (metadata only) for your agent runtime
• A validation report (script output)

Workflow

1. Read the repo’s sources of truth:
   • AGENTS.md (commands + hard rules)
   • docs/​Architecture/​Overview.md (modules/​boundaries) if present
2. Inventory skills and identify drift:
   • list all */​SKILL.md under your skills directory (Codex: .codex/​skills/​*/​SKILL.md, Claude Code: .claude/​skills/​*/​SKILL.md)
   • verify folder name == YAML name
   • look for “template cruft” inside skill folders (README/​INSTALL/​CHANGELOG) and remove it
3. Update skills to match reality (no guessing):
   • ensure each skill references real commands (from AGENTS.md)
   • ensure each skill’s YAML description includes trigger keywords that match how users ask for the task
   • ensure workflows reference real modules/​boundaries (from architecture overview)
4. Create new skills for repeated/​fragile workflows:
   • keep one workflow per skill (split mega-skills)
   • copy the closest existing skill and adapt (folder/​name, triggers, outputs, workflow)
   • use scripts/ for deterministic or fragile steps
   • use references/ only for copy/​paste templates and structured checklists (avoid “reading lists”)
5. Validate skills (fix errors before shipping):
   • run the bundled validator from the repo root:
     • python3 <skills-dir>/​mcaf-skill-curation/​scripts/​validate_skills.py <skills-dir>
     • Codex: python3 .codex/​skills/​mcaf-skill-curation/​scripts/​validate_skills.py .codex/​skills
     • Claude: python3 .claude/​skills/​mcaf-skill-curation/​scripts/​validate_skills.py .claude/​skills
6. Generate a metadata-only skills block for your agent runtime:
   • run the bundled generator from the repo root:
     • python3 <skills-dir>/​mcaf-skill-curation/​scripts/​generate_available_skills.py <skills-dir> --absolute
     • Codex: python3 .codex/​skills/​mcaf-skill-curation/​scripts/​generate_available_skills.py .codex/​skills --absolute
     • Claude: python3 .claude/​skills/​mcaf-skill-curation/​scripts/​generate_available_skills.py .claude/​skills --absolute
   • paste the output into your agent configuration (system/​developer prompt)
7. When user feedback is about skills:
   • update the relevant <skills-dir>/<skill-name>/​SKILL.md (especially YAML description triggers) so the fix is permanent

Bundled scripts

• scripts/​validate_skills.py — validates frontmatter + folder/​name rules and flags common spec violations.
• scripts/​generate_available_skills.py — prints an <available_skills> XML block from your skills directory */​SKILL.md metadata.

Guardrails

• Don’t turn a skill into a wiki: keep SKILL.md procedural and short.
• Don’t add extra docs inside skill folders (README.md, INSTALLATION_GUIDE.md, CHANGELOG.md, etc.).
• Prefer updating triggers (description) over adding more and more body text.
• YAML is strict: if a value contains : or other YAML-significant characters, wrap it in quotes.

Examples (trigger phrases)

• "update our skills to match the repo"
• "this skill triggers wrong, fix the description"
• "generate available_skills block"
• "validate skills frontmatter"