Skills Maintainer: keeping your instruction files true

Your repository has a CLAUDE.md. Probably an AGENTS.md in a few packages, and a .claude/skills/ folder someone filled in during a good week. They were accurate when they were written. Nobody has read them since.

Stale docs and stale instruction files fail differently. A developer reading bad documentation notices and works around it. An agent reading a stale rule just follows it, on every pull request that touches the path.

What drift looks like

A rule says every API handler must call getAuthorizedUser before touching the database. True when written. Six weeks later the team moves authorization into middleware and handlers stop calling it directly. The rule is now wrong, and it pushes new code back toward a pattern the team deliberately left.

A quieter version: "import Button from @/components." The barrel gets split, the path changes, and agent-written components keep reaching for a path that no longer exists.

Neither is a bug anyone wrote. The file just stopped describing the codebase.

Why it stays broken

There is no failing test for "this rule is no longer true." No linter, no type error, no CI job.

The only signal is the gap between what the file says and what the last few hundred merged pull requests actually did. Nobody runs that comparison by hand, across nine repositories, for files they did not write.

What Skills Maintainer does

It runs the comparison.

It reads the instruction files Baz already discovers for the AI Coding Guidelines reviewer, checks each rule against the current code and the pull requests that came after it, and opens a pull request when a rule no longer holds.

A pull request, not a dashboard. The output is a diff against CLAUDE.md with the reasoning attached, reviewed and merged like anything else.

Three things worth knowing, all in that drawer:

Bounded. You cap how many pull requests it can have open at once. At the cap it stops until you clear some. The failure mode of a tool like this is not bad suggestions, it is fifty good ones on a Monday morning.

Scoped. Pick specific repositories or all of them. Repositories without write access are visibly excluded rather than silently skipped.

Separable. Every pull request gets a title prefix and a branch prefix you choose, so its output is filterable and routable through your branch rules from the first run.

The docs cover setup and how to start a run.

Where the standards come from

Skills Maintainer keeps instruction files honest. It cannot invent them. Point it at a four-line CLAUDE.md and it will have almost nothing to say, correctly.

So where do real standards come from? Awesome Reviewers is our answer: a corpus of review instructions distilled from real code review discussions across production repositories, grouped by domain, published as plain markdown with no key and no rate limit. A domain bundle is one fetch.

https://awesomereviewers.com/raw/bundles/<domain>.md

Drop the bundle for your domain into .claude/skills/ and you start from standards other teams argued their way to. Each instruction links back to the review threads it came from, so "why does this rule exist" has an answer.

Then Skills Maintainer takes over, because borrowed standards drift fastest. They were never grounded in your codebase to begin with.

The three pieces fit together. Awesome Reviewers is where standards come from, the AI Coding Guidelines reviewer enforces them, and Skills Maintainer keeps them true. Enforcement without maintenance is the worst of the three, since it applies yesterday's rules at today's speed.

Start small

Turn it on for one repository you know well. Set the open pull request cap to three. Scan on demand.

Read that first batch carefully. It says less about the agent than about how far your written standards have drifted from your real ones.

Then widen the scope, put it on a schedule, and stop thinking about it.

---

Skills Maintainer is available now in the Baz agents drawer. See the documentation for setup.