Keep the reason beside the code, or where the whole repository can find it (#｀ε´#ゞ
A workaround with no explanation gets tidied away, a deliberate deviation gets "corrected" back to the default, and a trap with a plausible result costs the next maintainer the same debugging session. The explanation has to survive, but putting every reason into a catch-all document only moves the ambiguity elsewhere
This skill decides when the reason belongs in an inline comment and when it needs a repository-wide WORKAROUNDS.md, DEVIATIONS.md or PITFALLS.md. It also defines what each entry owes the person who has to remove it, keep it or avoid it, and only a workaround ever says when it can go
npx skills add -g rokokol/maintainer-docs-skill # for you, everywhere
npx skills add rokokol/maintainer-docs-skill # for the project you are standing inClaude Code also takes it as a plugin:
/plugin marketplace add rokokol/skills
/plugin install maintainer-docs@rokokol-skills
or by hand — clone into whichever skills directory your agent reads:
git clone https://github.com/rokokol/maintainer-docs-skill ~/.claude/skills/maintainer-docsNote
A skill has no version to pin. It is read at whatever revision you have checked out, so git pull is the whole upgrade path
The decision tree and the contracts of all three documents are in SKILL.md, where the agent reads them. They are not copied into a second table here
The short form is the boundary rather than the taxonomy: a reason owned by one line stays beside that line, while a reason shared by several places or anchored to none gets one repository-wide home
Choosing between a workaround, a deviation and a pitfall is a reading task. A script can demand headings and fields, but it cannot tell whether an entry preserved the real mechanism or merely filled in the form, so this skill deliberately ships no checker