BjornMelin/dev-skills / skills/agents-md-maintainer
agents-md-maintainer
VerifiedAGENTS.md maintenance rules for deciding when durable repo guidance should be updated after implementation.
Use this skill after nontrivial implementation work and before finalizing when you need to decide whether AGENTS.md should change.
Rules
- Treat
AGENTS.mdas durable repo guidance, not a task log. - Run a brief
AGENTS.mdmaintenance pass at the end of implementation. - Do not modify
AGENTS.mdunless the implemented code, tests, and docs state already proves the new rule. - Update
AGENTS.mdonly for durable repo-wide guidance such as:- required build, test, lint, typecheck, or verification commands
- architecture invariants or hard constraints
- canonical data shapes, contracts, directory ownership, or file locations
- repo-wide coding, review, or release expectations
- recurring failure modes that future sessions must avoid
- Do not update
AGENTS.mdfor one-off feature details, branch context, temporary migrations, issue notes, task plans, historical summaries, or implementation narration. - Keep edits minimal and high-signal. Prefer replacing, tightening, deduplicating, or deleting existing bullets over appending prose.
- Keep
AGENTS.mdclean, concise, and production-facing. - Do not include working-session phrasing such as
Phase,plan,follow-up, or similar developer-tracking language. - Write rules as short, concrete, imperative bullets that a coding agent can apply immediately in a new session with no prior chat context.
- Keep root
AGENTS.mdlimited to broadly applicable guidance. Put scoped rules in the nearest folder-levelAGENTS.md. Put reusable workflows in skills or referenced docs. - Ensure every
AGENTS.mdedit matches the current codebase exactly, and remove stale or superseded guidance in the same pass. - Use
$reducing-entropy,$clean-code, and$hard-cutwhen deciding whether guidance should be added, tightened, or deleted. - If delegation is allowed and helpful, use a small subagent to compare the implemented diff against
AGENTS.mdand propose the smallest valid patch. - Before finishing, verify that each
AGENTS.mdchange is:- durable
- repo-relevant
- non-duplicative
- consistent with current code and tests
- useful to a coding agent starting from zero context
- Leave
AGENTS.mdunchanged if any of those checks fail.
Workflow
- Compare the implemented diff against the current
AGENTS.md. - Decide whether the completed work changed durable repo guidance.
- Stop if the answer is no.
- If the answer is yes, make the smallest valid patch.
- Re-check the edited guidance against the current codebase, tests, and docs.
- Delete or tighten any stale, duplicated, or superseded bullets in the same pass.
Examples
- Update
AGENTS.mdif the repo now requires a new canonical verification command before completion. - Do not update
AGENTS.mdif the work only added a feature-specific route, component, or migration note.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 470k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |