optimize-claude-md

The saved excerpt is a snapshot from review. The external source remains the complete and most current version.

---
name: optimize-claude-md
description: "Optimize existing CLAUDE.md, SKILL.md, agent definitions, and other AI-facing files for Claude comprehension and economy. Scope: optimization of existing content only — not upstream sync, not read-only auditing. Measures baseline metrics, delegates to @ai-doc-optimizer agent with file-type-specific context, runs independent verification via second agent, measures post-optimization metrics, and presents comprehensive before/after report. Supports iterative mode for large targets. Use when improving prompt effectiveness, reducing token waste, or rewriting instructions for LLM consumption. Invoke with /optimize-claude-md <file-or-directory>."
argument-hint: <file-or-directory-path>
user-invocable: true
disable-model-invocation: true
---
If the user's intent does not match the purpose of this skill, load `plugin-lifecycle` to route to the right skill and process: `Skill(skill="plugin-creator:plugin-lifecycle")`.

# Optimize AI-Facing Files

Orchestrate multi-phase optimization of AI-facing documentation with measurement, delegation, verification, and comprehensive reporting.

## Invocation

```text
/optimize-claude-md <path>
```

Where `<path>` is one of:

- A single file (e.g., `./CLAUDE.md`, `.claude/skills/my-skill/SKILL.md`, `.claude/agents/my-agent.md`)
- A skill directory (e.g., `.claude/skills/my-skill/`) — optimizes SKILL.md and all reference files
- A plugin directory (e.g., `plugins/my-plugin/`) — optimizes CLAUDE.md, all skills, and all agents

## Process

<user_provided_target>$ARGUMENTS</user_provided_target>
<PWD> !`pwd` </PWD>

### Phase 1: Validate Target

If `<user_provided_target>` is empty, ask the user for a target path before proceeding.

If `<user_provided_target>` is not an absolute path, prepend the value of `<PWD>` to produce the absolute path. Use that absolute path for all subsequent operations.

Verify the resolved absolute path exists. Determine scope (single file, skill directory, or plugin directory).

Recognize these file types: `CLAUDE.md`, `AGENTS.md`, `SKILL.md`, agent definition (`.md` in `agents/`), reference file (`.md` in `references/`). Both `CLAUDE.md` and `AGENTS.md` are index files — apply index discipline checks in Phase 2.

### Phase 2: Measure Baseline

**For all files**:

- Determine file type (`CLAUDE.md`, `AGENTS.md`, `SKILL.md`, agent definition, reference file)
- Measure token count: `uvx skilllint@latest check --tokens-only <file>`
- Record baseline token count

**For SKILL.md files only**:

- Run completeness score evaluation (8-category assessment from /plugin-creator:audit-skill-completeness)
- Record baseline completeness score (format: X/24)

**For CLAUDE.md and AGENTS.md files** — run index discipline audit (6 binary checks):

Score = number passing (0–6). Record as `Index: N/6`.

| Check | Pass condition |
|-------|---------------|
| Entry length | All entries ≤ ~150 chars |
| No procedure steps | No entry contains numbered steps or multi-sentence procedures |
| Operative-fact hooks | All hooks state the rule/constraint/value directly; no entry contains "Load when" |
| No inline processes | No substantial process/protocol body appears directly inline |
| No stale routes | All linked `docs/` files exist at the referenced paths |
| No missing routes | All `docs/` files have a corresponding router entry |

**Record all metrics** for reporting.

### Phase 3: Delegate to @ai-doc-optimizer

Spawn the optimization agent via Agent tool with enhanced delegation template (see below). Pass file-type-specific context, baseline metrics, and constraints.

<delegation_template>

```text
TARGET: {resolved path(s)}
FILE TYPE: {CLAUDE.md | SKILL.md | agent definition | reference file}
BASELINE TOKEN COUNT: {N tokens}
BASELINE COMPLETENESS SCORE: {X/24} (SKILL.md only)

TASK:
1. Run RT-ICA pre-check — verify file type, intent, audience, constraints
2. Enable the prompt-optimization skill
3. Read the complete target file(s)
4. Analyze against the 8 o