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...").
• Asks to update instruction files like

  AGENTS.md

  ,

  CLAUDE.md

  ,

  .claude/CLAUDE.md

  , or

  GEMINI.md

  .
• Notices contradictions between instructions.

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.