Agent Doc Lint

**English** | [中文](README.zh-CN.md)

agent-doc-lint

Your CLAUDE.md / AGENTS.md is too long? This skill helps your AI agent analyze it, split it into skills, and keep it drift-free.

Supports both **Claude Code** (`CLAUDE.md` + `.claude/skills/`) and **Codex CLI** (`AGENTS.md` + `.codex/skills/`).

What It Does

Your instruction file is loaded into **every single request** — a 500-line file costs tokens on every interaction, even simple questions. Skills load **only when relevant**, cutting token waste without losing context quality.

Install this as a skill, run `/doc-lint`, and the agent will:

**Quick mode** (`/doc-lint`) — analyze existing docs only:

1. Scan — read your instruction file and existing skills
2. Analyze placement — classify each section: protected (must stay) vs. should move to skill
3. Propose — output a structured splitting plan, wait for your approval
4. Execute — create/update skills, slim down the instruction file, run lint to verify

**Full mode** (`/doc-lint --full`) — also scan project code:

1. Scan — read docs + scan project source structure
2. Accuracy check — verify docs match current code (stale types, outdated counts, missing modules)
3. Analyze placement — same as quick mode
4. Propose — splitting plan + accuracy fixes, wait for your approval
5. Execute — fix stale content + split, run lint to verify

No changes are made without your explicit approval.

The Splitting Guide

**[best-practices.md](best-practices.md)** provides the methodology the agent follows:

• Context Cost Model — Why splitting matters
• What Goes Where — Always-on rules vs. on-demand reference
• 6 Splitting Triggers — file too long, reference tables (10+ rows), hardcoded counts, static file trees, content duplication, scope-specific sections
• How to Split — 5-step procedure with before/after examples
• Skill Design — Frontmatter, size limits, description quality, scope boundaries
• Anti-Drift —