PMTL Skill Governance
Purpose
Keep the PMTL skill system aligned with the repo taxonomy and the operating model scope -> skill -> execute -> verify -> evolve.
Use When
- Creating a new repo-local skill.
- Auditing whether an existing skill is still only prompt prose.
- Consolidating overlapping skills or legacy aliases.
- Adding missing verification, templates, gotchas, or changelog notes to a skill.
Required Inputs
- The target skill name or the subset of skills under review.
- The taxonomy slot the skill should belong to.
- The repeated task, failure mode, or workflow the skill must serve.
Expected Output
- A skill folder with a usable
SKILL.md. - Supporting assets where needed:
references/,scripts/,templates/,verification/,examples/. - Evolution assets:
gotchas.mdandchangelog.md. - An audit result that shows what is still missing.
Execution Approach
- Confirm the taxonomy slot in
docs/architecture/skills-taxonomy.md. - Start from
templates/SKILL.template.mdinstead of free-writing a long prompt. - Add executable or reusable assets before adding more prose.
- Attach a verification checklist and at least one evolution artifact.
- Run
py infra/tools/codex_actions.py skill-auditand record the gaps.
Quality Criteria
- One skill owns one operational job.
- The folder contains enough context to reuse without re-explaining the task.
- Verification is explicit and repeatable.
- The skill teaches from past failures instead of forgetting them.
- Routing stays clear; new skills do not overlap existing taxonomy slots without a reason.
Verification
- Run
py infra/tools/codex_actions.py skill-audit. - Check
verification/checklist.mdbefore treating the skill as complete. - If the skill runs commands, prefer a wrapper in
scripts/orinfra/tools/codex_actions.py.
Edge Cases
- Legacy compatibility skills may intentionally stay lighter than canonical skills.
- Design-library skills can keep dense references, but still need a clear trigger and routing note.
- If two skills overlap, merge or demote one to compatibility instead of keeping both canonical.
References
templates/SKILL.template.mdverification/checklist.mdexamples/sample-skill-outline.mdgotchas.mdchangelog.md