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)
- Read
AGENTS.md.
- Identify the user's correction and translate it into a durable, repo-specific instruction.
- 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.
- Draft the exact text change(s) as a small patch/snippet.
- 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:
- Scan
AGENTS.md for conflicts with the new correction.
- If a conflict exists, include conflict resolution in the proposed patch by rewriting/removing the conflicting lines.
- 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:
- Propose a consolidation patch to
AGENTS.md.
- 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).
- 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.
1---2name: agents-md-improver3description: 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.4license: MIT5metadata:6 source: https://skillmd.com/skills/ericmjl/agents-md-improver7---89# AGENTS.md improver1011This 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`.1213## Usage1415Use this skill anytime the user:1617- Corrects the agent ("don't do X", "do Y instead", "from now on...", "remember to...", "add a rule that...").18- Asks to update instruction files like `AGENTS.md`, `CLAUDE.md`, `.claude/CLAUDE.md`, or `GEMINI.md`, or to align or consolidate those files.19- Notices contradictions, duplication, or drift between repository instruction files.2021## Requirements2223- Repo-local file access to read and edit `AGENTS.md`.24- If present in the repo, read access to `CLAUDE.md` and/or `.claude/CLAUDE.md`.2526## What It Does2728- Proposes a patch to incorporate the user's correction into `AGENTS.md` seamlessly.29- Looks for contradictions and resolves them in the proposal (or asks for clarification when needed).30- 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.3132## How It Works3334### Scope3536This skill is repo-specific.3738- Only consider repo-local instruction files:39 - `AGENTS.md`40 - `CLAUDE.md` (repo root)41 - `.claude/CLAUDE.md`42 - `GEMINI.md` (repo root and/or repo subdirectories if present)43- Ignore system-wide instructions and files under the user's home directory (for example `~/.claude/`, `~/.gemini/`, `~/.config/`, etc.).4445### Propose-first workflow (do not auto-edit)46471. Read `AGENTS.md`.482. Identify the user's correction and translate it into a durable, repo-specific instruction.493. Decide where it belongs:50 - Prefer editing the most relevant existing section.51 - If it introduces a genuinely new topic, propose a new `##` section near related content.524. Draft the exact text change(s) as a small patch/snippet.535. Ask for confirmation before applying:54 - "Apply these changes to `AGENTS.md`? (y/n)"5556Only apply edits after the user confirms.5758### Seamless integration rules5960- Do not add dated changelog entries like "YYYY-MM-DD: correction".61- Update the existing prose/bullets/steps so the rule reads like it has always been part of the document.62- Keep formatting consistent with the surrounding `AGENTS.md` style.6364### Contradiction checks6566Before proposing a patch:67681. Scan `AGENTS.md` for conflicts with the new correction.692. If a conflict exists, include conflict resolution in the proposed patch by rewriting/removing the conflicting lines.703. If resolution is ambiguous, ask a single targeted question before proposing a patch.7172Then scan repo-local guidance (if present):7374- Compare `AGENTS.md` against `CLAUDE.md` and `.claude/CLAUDE.md`.75- Flag duplication and conflicts.76- Prefer consolidating into `AGENTS.md` as the canonical source of truth.7778### Consolidation flow for CLAUDE.md files (if present)7980If `CLAUDE.md` and/or `.claude/CLAUDE.md` exists in the repo:81821. Propose a consolidation patch to `AGENTS.md`.832. After the user approves the `AGENTS.md` patch, propose what to do for each CLAUDE file:84 - Delete the file.85 - Replace the file with a symlink pointing to `AGENTS.md`.86 - Replace the file contents with a small stub that points humans/tools to `AGENTS.md` (fallback when symlinks are undesirable).873. Confirm destructive actions (deletes) in a separate prompt.8889Symlink directions (when chosen):9091- `CLAUDE.md` -> `AGENTS.md`92- `.claude/CLAUDE.md` -> `../AGENTS.md`9394### Notes for multi-instruction environments9596Some 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.