| name | write-teach-commit |
| description | Draft `teach:` commit messages for `.github/workflows/improve-add-skill.yml`. Use when preparing or reviewing a correction commit that should trigger the Improve Add Skill workflow from `$add` categorization feedback, including moved plugin entries, removed or excluded plugins, changed `.reason.md` categories, or review-approved rationale that should be generalized into `.codex/skills/add/**`. |
Write Teach Commit
Overview
Write a commit message that both triggers the workflow and gives $improve-add-skill enough context to learn the reusable correction.
The workflow only runs on pushes to branches matching ai-* when the head commit message starts with teach:. If the correction should not update .codex/skills/add/**, do not use a teach: subject.
Workflow
- Inspect the user-provided diff, staged changes, PR review comments,
.reason.md, and changed plugin list entries.
- Identify the actual correction: a plugin moved between categories, an exclusion, a changed category path, or explicit rationale for why
$add was wrong.
- Separate evidence from the lesson: evidence may name repositories and files; the lesson should describe the reusable placement rule.
- Draft a subject that starts exactly with
teach: and names the generic lesson, not just the repository touched.
- Add a short body when the subject alone cannot explain the correction.
Message Shape
Prefer this structure:
teach: <generic add-skill lesson>
Correction:
- <owner/repo>: <old category or decision> -> <new category or decision>
Reusable lesson:
- <category/exclusion rule that would have prevented the mistake>
Evidence:
- <short source, such as review comment, .reason.md row, or file path>
Keep the subject concise. Use the body for category paths and details.
Quality Rules
- Start the first line with
teach: exactly; Teach:, fix: teach, and body-only markers will not trigger the workflow.
- Use full category paths from
.reason.md or the markdown heading hierarchy when available.
- Make the reusable lesson domain-based, such as user workflow or plugin purpose, rather than implementation surface.
- For exclusions, state the exclusion trigger explicitly, such as fork, colorscheme, no README, non-English README, config repo, or sample plugin.
- Do not use
teach: for formatting-only, ordering-only, badge-only, typo-only, or ambiguous corrections.
Output
When the user asks for a commit message, output one message only. Prefer a fenced text block unless the user requests a command.
If there is no safe reusable lesson, say that teach: should not be used and provide a normal non-triggering commit subject instead.
