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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 2.9 KB |
| agents/openai.yaml | config | 293 B |
SKILL.md
View on GitHub---
name: "agents-md-maintainer"
description: "AGENTS.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.md` as durable repo guidance, not a task log.
- Run a brief `AGENTS.md` maintenance pass at the end of implementation.
- Do not modify `AGENTS.md` unless the implemented code, tests, and docs state already proves the new rule.
- Update `AGENTS.md` only 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.md` for 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.md` clean, 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.md` limited to broadly applicable guidance. Put scoped rules in the nearest folder-level `AGENTS.md`. Put reusable workflows in skills or referenced docs.
- Ensure every `AGENTS.md` edit matches the current codebase exactly, and remove stale or superseded guidance in the same pass.
- Use `$reducing-entropy`, `$clean-code`, and `$hard-cut` when 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.md` and propose the smallest valid patch.
- Before finishing, verify that each `AGENTS.md` change is:
- durable
- repo-relevant
- non-duplicative
- consistent with current code and tests
- useful to a coding agent starting from zero context
- Leave `AGENTS.md` unchanged if any of those checks fail.
## Workflow
1. Compare the implemented diff against the current `AGENTS.md`.
2. Decide whether the completed work changed durable repo guidance.
3. Stop if the answer is no.
4. If the answer is yes, make the smallest valid patch.
5. Re-check the edited guidance against the current codebase, tests, and docs.
6. Delete or tighten any stale, duplicated, or superseded bullets in the same pass.
## Examples
- Update `AGENTS.md` if the repo now requires a new canonical verification command before completion.
- Do not update `AGENTS.md` if 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: 472k | Updated | Claude CodeCodex | Unverified | 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 |