Tmb docs conventions

Skill trustmybot/plugin/skills/tmb_docs-conventions

Loaded when editing prompt files (agents, skills, CLAUDE.md, workflow markdown) or updating user-visible docs. Carries the editing judgment — what to delete, what to preserve, and where ripples land when a rename or restructure happens.From its SKILL.md

Install

npx -y skills add trustmybot/plugin --skill tmb_docs-conventions

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

6 stars6 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

2.0 KB, as published. Nobody here has run it

Docs Conventions — Editing Discipline

When editing prompt files or user-visible docs, follow these rules.

Docs-update expectation

When functionality changes, the same PR updates the user-visible docs that describe it. The PR-reviewer flags missing doc updates at the push gate. This is a judgment call (what counts as user-visible?).

When docs and code disagree

If a doc you're updating contradicts the code, halt and surface it — pick the side that matches the intended behaviour, update the other, and flag the discrepancy first. Ground in the code itself (and the world model), not in the prose that describes it.

Editing prompt files (agents, skills, CLAUDE.md, workflow markdown)

Delete before you add. A shorter prompt is usually clearer. Prefer removal over addition when both achieve the goal.
Preserve operational meaning. Copy constraints, prohibitions, and weighted examples verbatim — e.g. a LOAD-BEARING-SAFETY comment, a "HALT" rule, or an exact wire-format string — unless the request explicitly changes them.
Match tone and structure. Edits blend into the target file; they don't impose a different style.
Stay in scope. Correct what was asked; don't opportunistically rewrite adjacent content.
Update referenced paths. When you rename or move a file the prompt cites, grep for every reference and update it in the same commit.
Diff, don't rewrite. Produce edits as a focused diff unless a full rewrite was explicitly requested.

Escalation

Ambiguous rewrite request → ask specific questions, don't guess.
Target file has internal contradictions → quote them, flag to the caller.
Change would break files that reference this one → flag the ripple before proceeding.