agents-md-improver

name	agents-md-improver
description	Proposes updates to AGENTS.md so repo-local coding-agent instructions stay accurate, non-contradictory, and consolidated. Use when the user corrects the agent (e.g. do not do X, always do Y, from now on, remember this), asks to edit or sync AGENTS.md, CLAUDE.md, .claude/CLAUDE.md, or GEMINI.md, wants one canonical instruction file or to deduplicate agent docs, or flags conflicting or outdated repository agent rules.
license	MIT

AGENTS.md improver

This skill helps keep repository instructions accurate and consistent. When a user corrects the coding agent's behavior, treat it as a potential update to the repo's instruction files and propose a clean, integrated edit to AGENTS.md.

Usage

Use this skill anytime the user:

• Corrects the agent ("don't do X", "do Y instead", "from now on...", "remember to...", "add a rule that...").
• Asks to update instruction files like AGENTS.md, CLAUDE.md, .claude/CLAUDE.md, or GEMINI.md, or to align or consolidate those files.
• Notices contradictions, duplication, or drift between repository instruction files.

Requirements

• Repo-local file access to read and edit AGENTS.md.
• If present in the repo, read access to CLAUDE.md and/or .claude/CLAUDE.md.

What It Does

• Proposes a patch to incorporate the user's correction into AGENTS.md seamlessly.
• Looks for contradictions and resolves them in the proposal (or asks for clarification when needed).
• If repo-local CLAUDE.md or .claude/CLAUDE.md exists, proposes consolidating instructions into AGENTS.md, then offers follow-up options to delete, symlink, or stub those files.

How It Works

Scope

This skill is repo-specific.

• Only consider repo-local instruction files:
  • AGENTS.md
  • CLAUDE.md (repo root)
  • .claude/CLAUDE.md
  • GEMINI.md (repo root and/or repo subdirectories if present)
• Ignore system-wide instructions and files under the user's home directory (for example ~/.claude/, ~/.gemini/, ~/.config/, etc.).

Propose-first workflow (do not auto-edit)

1. Read AGENTS.md.
2. Identify the user's correction and translate it into a durable, repo-specific instruction.
3. Decide where it belongs:
   • Prefer editing the most relevant existing section.
   • If it introduces a genuinely new topic, propose a new ## section near related content.
4. Draft the exact text change(s) as a small patch/snippet.
5. Ask for confirmation before applying:
   • "Apply these changes to AGENTS.md? (y/n)"

Only apply edits after the user confirms.

Seamless integration rules

• Do not add dated changelog entries like "YYYY-MM-DD: correction".
• Update the existing prose/bullets/steps so the rule reads like it has always been part of the document.
• Keep formatting consistent with the surrounding AGENTS.md style.

Contradiction checks

Before proposing a patch:

1. Scan AGENTS.md for conflicts with the new correction.
2. If a conflict exists, include conflict resolution in the proposed patch by rewriting/removing the conflicting lines.
3. If resolution is ambiguous, ask a single targeted question before proposing a patch.

Then scan repo-local guidance (if present):

• Compare AGENTS.md against CLAUDE.md and .claude/CLAUDE.md.
• Flag duplication and conflicts.
• Prefer consolidating into AGENTS.md as the canonical source of truth.

Consolidation flow for CLAUDE.md files (if present)

If CLAUDE.md and/or .claude/CLAUDE.md exists in the repo:

1. Propose a consolidation patch to AGENTS.md.
2. After the user approves the AGENTS.md patch, propose what to do for each CLAUDE file:
   • Delete the file.
   • Replace the file with a symlink pointing to AGENTS.md.
   • Replace the file contents with a small stub that points humans/tools to AGENTS.md (fallback when symlinks are undesirable).
3. Confirm destructive actions (deletes) in a separate prompt.

Symlink directions (when chosen):

• CLAUDE.md -> AGENTS.md
• .claude/CLAUDE.md -> ../AGENTS.md

Notes for multi-instruction environments

Some harnesses merge multiple instruction sources and may apply conflicting rules non-deterministically. Prefer a single canonical source (AGENTS.md) and reduce parallel instruction files via consolidation + delete/symlink/stub.