agents-progressive-disclosure skill

---
name: agents-progressive-disclosure
description: Refactor bloated AGENTS.md/CLAUDE.md-style instruction files into a compact router plus focused on-demand docs. Use when users ask to apply progressive disclosure, split agent rules into docs, reduce instruction bloat, or turn one large rule file into an entrypoint.
---

# Agents Progressive Disclosure

Use this skill to assess a long agent instruction file and choose the smallest useful change: leave it unchanged, reorganize it in place, or split it into a high-signal entrypoint and focused docs. Preserve rules while avoiding unnecessary always-loaded context.

## Core Model

Treat the root instruction file as a router, not a rule warehouse.

- The entry file keeps always-on rules and short, frequently used facts or commands that prevent common mistakes.
- Lengthy task-specific guidance can move into `docs/` files when it has an independent trigger and is needed only for some tasks.
- The entry file includes a clear “read this doc when...” index.
- The agent should load only the docs relevant to the current task.

## Workflow

1. Identify the target instruction file.
   - Prefer the current directory's `AGENTS.md` unless the user names another file.
   - Also support `CLAUDE.md`, `GEMINI.md`, or project-specific equivalents.
   - If multiple candidates exist and the user did not specify one, report the candidates and choose the file most broadly used by the current agent setup; ask only when that choice is unclear or risky.

2. Inspect existing structure.
   - Read the target file fully.
   - List existing `docs/` files, if any.
   - Check for backups before editing.

3. Detect contradictions before classification.
   - Scan for conflicting style rules, package-manager choices, test commands, safety boundaries, precedence statements, or duplicated rules with different wording.
   - Resolve contradictions from explicit user instructions, nearest instruction-file priority, or clear local evidence when possible.
   - Ask the user only when a contradiction affects the refactor and cannot be resolved from available evidence.

4. Choose the smallest useful change.
   - Unless the user explicitly requires a split, assess whether splitting solves a concrete problem. If the file is already compact, its rules are usually needed together, or the benefit of splitting is unclear, keep it unchanged or reorganize it in place.
   - If no change is justified, explain why and stop without creating backups or new docs. For local reorganization, skip the docs-map step and limit edits and validation to what changed.

5. Classify rules by their actual content and use.
   - Keep always-on and safety-critical rules in the entrypoint. Short, frequently used facts and commands that prevent common mistakes can stay there too, such as the package manager and the normal test command.
   - Move lengthy explanations, procedures, or examples into docs when they have an independent trigger and are needed only for some tasks.
   - Consider frequency of use and the consequences of missing a rule. Do not move content solely because its topic is testing, Git, environment setup, or another category.

6. Design the docs map.
   - Prefer the project's existing agent-doc convention; otherwise default to `docs/` for cross-agent portability.
   - Existing conventions may include `.claude/`, `.claude/rules/`, `.cursor/rules/`, or another agent-doc directory.
   - Use existing document names when they already fit; otherwise derive focused names from the source rule clusters.
   - Preserve platform-specific file formats, required frontmatter, imports, path globs, and file extensions.
   - Create `docs/README.md` only when it helps navigate multiple docs.