agentsclimarketplace

Maintaining agents md

Skill qte77/claude-code-plugins/plugins/docs-governance/skills/maintaining-agents-md

A Claude Code plugin marketplace providing skills, rules, and scripts extracted from a production development workflow.

Install
npx -y skills add qte77/claude-code-plugins --skill maintaining-agents-md

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

  • 2 stars2 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.

What its author says it does

Copied from the file, not written here

Maintains AGENTS.md, AGENT_LEARNINGS.md, AGENT_REQUESTS.md, and CONTRIBUTING.md governance files in sync with codebase changes. Use when updating governance files, during sprint reviews, or after structural changes.

SKILL.md

3.3 KB, as published. Nobody here has run it

Maintain Agent Governance Files

Scope: $ARGUMENTS

Keeps agent governance files synchronized with codebase state. Detects stale references, missing updates, and promotion candidates.

Governance Files

FileAuthorityPurpose
AGENTS.mdBehavioralRules, role boundaries, compliance requirements
CONTRIBUTING.mdTechnicalWorkflows, commands, coding standards
AGENT_LEARNINGS.mdKnowledgeAccumulated patterns and solutions
AGENT_REQUESTS.mdEscalationActive blockers requiring human input

When to Use

  • After PRs that change project structure, commands, or patterns
  • At sprint start/end for governance health check
  • When promoting patterns from AGENT_LEARNINGS.md to .claude/rules/
  • After make validate pipeline or Makefile changes
  • When adding/removing skills or plugins

Modes

audit (default)

Scan governance files for staleness and inconsistencies.

Checks:

  1. Stale paths: Grep governance files for src/, docs/, tests/ paths. Verify each path still exists.
  2. Stale commands: Parse CONTRIBUTING.md command reference table. Verify each make recipe exists in Makefile.
  3. Missing learnings: Check recent git log for patterns not yet in AGENT_LEARNINGS.md. If ralph/docs/LEARNINGS.md exists, check it too.
  4. Resolved requests: Check AGENT_REQUESTS.md entries — flag any whose referenced files/issues no longer exist.
  5. Role boundary drift: Verify AGENTS.md role definitions match current .claude/skills/ inventory.

Output: Findings table with file, line, issue type, description.

sync

Fix staleness found by audit. For each finding:

  1. Propose the specific edit
  2. Apply on user approval
  3. Follow priority order: AGENTS.md > CONTRIBUTING.md > AGENT_LEARNINGS.md > AGENT_REQUESTS.md

promote

Evaluate AGENT_LEARNINGS.md entries for promotion per the criteria in .claude/rules/compound-learning.md (3rd occurrence → rule, recurring → skill).

Procedure:

  1. Read AGENT_LEARNINGS.md entries
  2. Grep codebase for each pattern's problem statement
  3. If pattern appears in 3+ locations or has been referenced in 3+ commits, recommend promotion to .claude/rules/
  4. Draft the rule file content for user approval

full

Run all three modes in sequence: audit → sync → promote.

Maintenance Priority Order

When multiple files need updates, follow this order to prevent hierarchy conflicts:

  1. AGENTS.md — behavioral rules first (highest impact)
  2. CONTRIBUTING.md — technical standards second
  3. AGENT_LEARNINGS.md — patterns third (high-value, low-risk)
  4. AGENT_REQUESTS.md — escalations last (time-sensitive, not structural)

References

  • .claude/rules/compound-learning.md — promotion path
  • CONTRIBUTING.md "Documentation Hierarchy" — authority structure
  • AGENTS.md "Decision Framework" — anti-redundancy rules

Keep looking

Skills are one crate of 328,083. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.