AGENT SKILL

agents-md-improver

Maintain AGENTS.md-based project instructions for tools that support AGENTS.md. Use for instruction audits, session learnings, AGENTS.md updates, or migrating useful CLAUDE.md rules into a shared instruction source. Not for general docs, code review, runtime debugging, or global memory unless asked.

使用场景代码审查
License 许可
Apache-2.0
最近更新
2026-11-14
Stars
★ 1.6k
Forks
491

01 前言 Front Matter

name
agents-md-improver
description
Maintain AGENTS.md-based project instructions for tools that support AGENTS.md. Use for instruction audits, session learnings, AGENTS.md updates, or migrating useful CLAUDE.md rules into a shared instruction source. Not for general docs, code review, runtime debugging, or global memory unless asked.

02 资源文件 2

03 SKILL.md 正文

AGENTS.md Improver

Overview

Maintain concise project instructions for AGENTS.md-compatible tools such as Codex, Copilot, Cursor, and similar coding agents.

Core principle: Find the effective instruction source -> extract durable learnings -> propose compact diffs -> apply approved changes only.

Announce at start: "I'm using the agents-md-improver skill to maintain concise AGENTS.md project instructions."

Prerequisites

  • A repository or workspace with AGENTS.md, nested AGENTS.md, or compatible instruction files.
  • A user request to audit, improve, revise, migrate, or capture learnings into project instructions.

Workflow

Phase 1: Identify Instruction Targets

Find instruction files from the repository root:

find . \( -name "AGENTS.md" -o -name "CLAUDE.md" -o -name ".claude.local.md" \) 2>/dev/null | head -50

Use these targeting rules:

  • ./AGENTS.md: primary shared project instructions for AGENTS.md-compatible tools.
  • Nested AGENTS.md: module-specific instructions; update only when the learning applies to that subtree.
  • Include-only AGENTS.md: if it contains only an include such as @./CLAUDE.md, read the target and treat that target as the effective source. Update the target only when the repository intentionally shares one instruction file across tools.
  • CLAUDE.md: Claude Code-specific instructions, or a shared source when AGENTS.md intentionally points to it. Do not update it just because it exists.
  • .claude.local.md: personal Claude Code local notes. Do not create or edit it for shared AGENTS.md project memory.
  • User/global instruction files, such as ~/.codex/AGENTS.md: update only when the user explicitly asks for global behavior.
  • .project_context/: historical exploration, plans, and execution summaries. Use it for trace records, not agent steering instructions.

If no AGENTS.md exists, propose creating the narrowest useful one, usually ./AGENTS.md.

Phase 2: Choose The Mode

Choose exactly one primary mode before scanning or proposing edits:

  • Repository Audit Mode: use when the user asks whether instructions are stale, incomplete, inaccurate, outdated, or should be refreshed against the current repository. Then read references/repository-audit.md.
  • Session Learning Mode: use when the user asks to capture this session's learnings, revise instructions from the current conversation, or preserve newly discovered repo-specific behavior. Then read references/session-learning.md.
  • Migration Mode: use when moving useful guidance from CLAUDE.md or another tool-specific instruction file into an AGENTS.md-compatible source. Reuse Session Learning Mode for extraction rules, but keep tool-only slash commands, hooks, or UI shortcuts in tool-specific files unless the user asks to make them shared.

Phase 3: Draft Compact Updates

AGENTS.md is prompt context. Prefer dense, operational bullets.

Good format:

- Use `rg` for repo-wide search; fall back only if unavailable.
- Run `pnpm test -- --runInBand` for flaky integration tests in this repo.
- Keep API compatibility normalization in the service layer unless a spec explicitly changes request validation.

Avoid adding:

  • generic engineering advice;
  • one-off debugging details unlikely to recur;
  • unverified assumptions or stale guesses;
  • long explanations, logs, secrets, tokens, private URLs, or machine-specific credentials;
  • duplicates of existing instructions.

Phase 4: Propose Before Editing

Always show proposed changes before modifying files. Group proposals by target file.

Use this format:

### Update: ./AGENTS.md

Why: <one-line reason this helps future agent sessions>

```diff
+ <concise addition>
```

If multiple files could be updated, explain the placement tradeoff:

  • root AGENTS.md for project-wide behavior;
  • nested AGENTS.md for module-local behavior;
  • .project_context/ for historical records;
  • CLAUDE.md only for Claude Code-specific behavior or an intentional shared source.

Ask for approval before editing. If the user already explicitly said to apply changes, proceed with the smallest safe patch.

Phase 5: Apply Carefully

When approved:

  • use minimal patches and preserve the file's existing organization;
  • insert under an existing relevant heading when possible;
  • create a short new heading only if no suitable section exists;
  • do not reorder unrelated content;
  • do not remove or rewrite existing instructions unless the user asked for cleanup or the instruction is clearly obsolete;
  • after editing, re-read the changed section and report exactly what changed.

Common Mistakes

  • Treating .project_context/ as agent steering context. It is for traceability, not instructions that should load every session.
  • Updating CLAUDE.md for a shared AGENTS.md request when the repo does not intentionally share one source file.
  • Missing an include-only AGENTS.md and patching the wrapper instead of the effective source.
  • Capturing logs, secrets, private URLs, or one-off debugging notes as durable instructions.
  • Adding broad best practices that any competent agent already knows.

Output

For Repository Audit Mode, provide the quality report format from references/repository-audit.md.

For Session Learning Mode or Migration Mode, provide:

  • files changed;
  • concise summary of additions;
  • any skipped proposals and why.

References

  • repository-audit.md - Repository scan scope, quality criteria, and report template for stale or incomplete instructions.
  • session-learning.md - Session learning extraction rules and concise update proposal template.

04 同仓库更多 Skills

hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-review-with-annotations

Create, inspect, reply to, update, or resolve situated Worktable annotations. Use when feedback belongs to a Doc section, block, text range, or HTML Doc, or when the user asks to address existing review feedback and coordinate a requested artifact edit.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-find-and-synthesize-context

Find, assess, and synthesize context from Worktable Docs and Records. Use when the user asks what a workspace contains, wants workspace-backed research, needs current facts reconciled across artifacts, or requests a cited synthesis without changing workspace state.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-create-or-update-docs

Create, edit, rename, or maintain narrative Worktable Docs. Use for plans, decisions, briefs, notes, research syntheses, and other durable prose when the user requests a new artifact or a safe update to an existing one.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-create-or-manage-records

Organize repeated structured information as durable Worktable Records. Use for research datasets, inventories, directories, pipelines, trackers, and other collections whose items need identity, fields, filtering, links, validation, or individual updates.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-create-or-manage-interactive-html

Create or improve durable visual and interactive artifacts in Worktable. Use for dashboards, trackers, calculators, mini apps, slide presentations, and other requests that benefit from a polished HTML Doc.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-collaborate-threads

Read, answer, and hand off messages through durable Worktable threads with users or other authenticated participants. Use when the user asks to check addressed messages, reply to a participant, continue a thread, request another agent's help, wait briefly for a response, or watch for comments and messages sent to the agent.

★ 1.6k