agents-md-improver

# 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.