agents-md-optimizer

分类: 测试与安全 | 上传者: MSApps-Mobile | 下载: 0 | 版本: v1.0（最新）

审核臃肿的代理指令文件（CLAUDE.md、AGENTS.md 及其本地/用户级变体）并精简重写它们，或者按照 200 行“食谱”原则从头开始编写一个新文件。每当用户提到 CLAUDE.md、AGENTS.md、代理指令文件、项目内存文件、上下文文件、代币预算、上下文膨胀、“我的 CLAUDE.md 太大”、修剪 CLAUDE.md、审核 AGENTS.md、为新项目编写 AGENTS.md 或任何有关代理指令文件层次结构（企业、项目、用户级、项目本地）。当这样的文件在上下文中显示并且明显很长（超过 200 行）或包含反模式（例如嵌入式 API 文档、否定的“不要做 X”规则、分步教程或抢占式文件预加载指令）时也会触发 - 即使用户没有明确要求优化，也会主动提出使用它。

更新日志: Source: GitHub https://github.com/MSApps-Mobile/claude-plugins

目录结构

当前层级: tree/main/plugins/agents-md-optimizer/skills/agents-md-optimizer/

📁 references/
- 📄 anti-patterns.md 6.1 KB
- 📄 template.md 3.9 KB
📁 scripts/
- 📄 audit.py 8.0 KB
📄 SKILL.md 10.0 KB

SKILL.md

---
name: agents-md-optimizer
description: Audit bloated agent-instruction files (CLAUDE.md, AGENTS.md, and their local/user-level variants) and rewrite them lean, or author a new one from scratch following the 200-line "recipe book" principle. Use this skill whenever the user mentions CLAUDE.md, AGENTS.md, agent instruction file, project memory file, context file, token budget, context bloat, "my CLAUDE.md is too big", trimming CLAUDE.md, auditing AGENTS.md, writing AGENTS.md for a new project, or any discussion of what belongs in the agent-instruction-file hierarchy (enterprise, project, user-level, project-local). Also trigger when such a file is shown in context and is visibly long (over 200 lines) or contains anti-patterns like embedded API docs, negative "Don't do X" rules, step-by-step tutorials, or preemptive file-preload instructions — even if the user doesn't explicitly ask for optimization, proactively offer to use it.
---

# agents-md-optimizer

## What this skill does

`CLAUDE.md` is loaded into every Claude session for the project it belongs to. That means every line is a recurring tax on the context window — paid before any real work starts, across every session, forever. Most `CLAUDE.md` files drift into bloat: people copy-paste API docs, write step-by-step tutorials, hoard historical state, stack negative "don't do X" rules. The result is a ~2,000-token baseline cost that degrades focus and wastes budget.

The fix is to treat `CLAUDE.md` like a focused recipe book: essential guidance only, everything else extracted to a location that loads on-demand. This skill does two things:

1. **Audit mode** — read an existing `CLAUDE.md`, diagnose what's bloat, and produce a slimmed rewrite plus an extraction plan (what moves where).
2. **Author mode** — interview about a new project and write a lean `CLAUDE.md` from scratch using the template.

## When to pick a mode

Detect mode from input:

- **The user points at an existing file, or one is visible in context** → audit mode.
- **The user wants a fresh `CLAUDE.md` for a new or undocumented project** → author mode.
- **Both** (they showed a file but also want a rewrite philosophy applied to a second project) → run audit first, carry the principles into the author pass.

If it's ambiguous, ask one clarifying question: "Are we trimming an existing one, or writing a new one?"

## The four-layer hierarchy — know where things actually belong

Every recommendation in this skill depends on understanding that `CLAUDE.md` isn't monolithic. Claude loads four layers in precedence order:

1. **Enterprise policy** — organization-wide, set by admins.
2. **`./CLAUDE.md`** — project-level, committed to the repo. This is what most people mean by "CLAUDE.md." Shared with every collaborator.
3. **`~/.claude/CLAUDE.md`** — user-level, personal defaults that apply across every project. Communication prefs, your own account info, your shell aliases.
4. **`./CLAUDE.local.md`** — project-local overrides, gitignored. Personal notes about this specific repo that shouldn't be shared with collaborators.

When you find content that doesn't belong in the project `CLAUDE.md`, the right extraction target is usually one of these other layers, not just "delete it."

**Rule of thumb for extraction:**
- Personal communication style, cross-project aliases, "I prefer X" → `~/.claude/CLAUDE.md`
- Ephemeral state (gcloud auth status, current sprint number, active branch) → `./CLAUDE.local.md`
- Team-shared conventions, tech stack, boundaries → stays in `./CLAUDE.md`
- Deep reference material (API docs, architecture deep-dives, runbooks) → `docs/`, referenced by path
- Repeatable multi-step workflows → extract into a Skill

## What belongs in project CLAUDE.md (the lean template)

A good project `CLAUDE.md` fits on roughly one screen (~200 lines max). See `references/template.md` for the full skeleton. The essential sections:

- **Project identity** — 2–3 sentences: what this codebase does and who it's for.
- **Tech stack** — language, framework, key APIs, deploy target, testing tool. One line each.
- **Code conventions** — the 3–7 house rules a new contributor would genuinely need on day one. Written as positive directives, not prohibitions.
- **Output preferences** — how Claude should present solutions in this repo (diff format, code-block length, explanation style).
- **Boundaries** — hard stops: files that should never be modified, secrets that should never be committed, commands that must run before finishing (lint/typecheck/test).
- **Quick reference** — pointers to main entry files, test locations, and `docs/` for anything deeper.

Everything else is bloat. If it's not needed on *every* interaction with this repo, it belongs somewhere that loads on demand.

## Audit mode — how to run it

### Step 1: Read the file and quantify

Read the target `CLAUDE.md`. Run `scripts/audit.py <path>` to get a structured report:

```bash
python3 scripts/audit.py <path-to-CLAUDE.md>
```

The script reports: line count, estimated token count (~4 chars/token heuristic), detected anti-patterns with line numbers, and section-by-section classification (essential / extract / delete).

If the file is already ≤200 lines and the audit finds no anti-patterns, tell the user it's already lean and stop. Don't invent problems.

### Step 2: Classify every section

For each section of the file, decide: **keep**, **extract**, or **delete**.

- **Keep** if it's essential project identity, a convention that affects every interaction, an output preference, or a hard boundary.
- **Extract** if it's useful but specific to a subset of interactions. Name the destination explicitly (`docs/hooks.md`, `~/.claude/CLAUDE.md`, `CLAUDE.local.md`, a new skill).
- **Delete** if it's obsolete, duplicated elsewhere (e.g., already in an installed skill), or a "just in case" note that's never actually referenced.

### Step 3: Apply the anti-pattern fixes

See `references/anti-patterns.md` for the full list and rewrite patterns. Summary:

- **Negative rules → positive rules.** "Don't use `var`" becomes "Use `const`/`let`." Positive instructions compile to shorter mental models and avoid reinforcing the thing you're trying to prevent.
- **Embedded reference docs → links.** A 200-line API schema inside `CLAUDE.md` becomes `See docs/api-reference.md for endpoint schemas.`
- **Tutorials / step-by-step procedures → Skills.** If it reads like a runbook, it belongs in `.claude/skills/<name>/SKILL.md` where it loads only when relevant.
- **Preemptive file preloads → removed.** Instructions like "Read `src/config.ts` at session start" are almost always wasteful; Claude can read files on demand when the task requires them.
- **Historical state / status tables → `CLAUDE.local.md`.** Anything dated (gcloud auth status from 3 weeks ago, "current sprint goal") is ephemeral and doesn't belong in a shared file.

### Step 4: Produce two outputs

1. **The rewritten `CLAUDE.md`** — the full replacement file, lean and ready to drop in.
2. **The extraction plan** — a clear list: "Lines X–Y (topic) → destination Z, because …" so the user can act on the extractions (create those docs, move content to user-level, etc.).

Show the before/after stats at the top of the plan: original line count, new line count, estimated token delta, percent reduction.

Do not silently lose content. Every deleted or moved section must appear somewhere in the extraction plan, so the user can audit the move.

## Author mode — how to run it

### Step 1: Interview

Ask the user about:
- **Identity**: What does the codebase do? (2–3 sentence answer)
- **Stack**: Language, framework, APIs, deploy target, test tool.
- **House rules**: Top 3–5 conventions new contributors need to know.
- **Output prefs**: Diff style, explanation length, any formatting requests.
- **Boundaries**: Files never to touch, secrets, required pre-finish checks.
- **References**: Where do architecture docs live? Canonical knowledge store (Notion, Confluence, `docs/`)?

Batch these questions — two or three at a time, not one by one. Don't ask about every conceivable section; the template has defaults for missing info.

### Step 2: Write the file

Fill in `references/template.md`. Keep each section tight. If a section has nothing real to put in it, delete the section rather than pad with "TBD" — missing sections are information, padding is noise.

### Step 3: Verify

Run `scripts/audit.py` on the result. It should pass all checks. If it doesn't (e.g., you accidentally included a 40-line JSON example), fix before delivering.

## Output format

Whichever mode, the final output structure is:

```
## Stats
[before/after line and token counts, percent reduction if auditing]

## CLAUDE.md
` ` `md
[the full lean file, ready to save]
` ` `

## Extraction plan  (audit mode only)
- Lines X–Y [topic] → [destination] — [one-line why]
- …

## Next steps
[concrete actions: create docs/foo.md with content X, add Y to ~/.claude/CLAUDE.md, etc.]
```

## Principle of lack of surprise

This skill only rewrites `CLAUDE.md`-family files (CLAUDE.md, AGENTS.md, CLAUDE.local.md). Never modify source code, configs, or secrets while doing this. Never delete the original until the user confirms the rewrite works — write the new file alongside the old one (e.g., `CLAUDE.md.new`) or show the diff and let them apply it.

If the audit would extract content to new files the user hasn't seen yet (a new `docs/hooks.md`, a new Skill), draft those too but clearly mark them as "proposed" — don't auto-create a web of new files without consent.

## Reference files

- `references/template.md` — The lean `CLAUDE.md` skeleton with all essential sections and inline guidance. Read this before writing in author mode.
- `references/anti-patterns.md` — The catalog of common bloat patterns with before/after rewrite examples. Read this before auditing.

## Script

- `scripts/audit.py` — Runs a quantitative audit: line count, token estimate, anti-pattern detection by regex, section classification. Use it at the start of audit mode and again as a final check on any rewrite (author or audit).

登录后下载/点赞/收藏 ❤ 8 | ★ 0

agents-md-optimizer

目录结构

SKILL.md

举报内容

提示