# Refactor Docs

> Split oversized or multi-topic docs into focused files with progressive disclosure

- **Type:** Skill
- **Install:** `agentstack add skill-paulo-yamagishi-claude-code-setup-refactor-docs`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [paulo-yamagishi](https://agentstack.voostack.com/s/paulo-yamagishi)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [paulo-yamagishi](https://github.com/paulo-yamagishi)
- **Source:** https://github.com/paulo-yamagishi/claude-code-setup/tree/main/.claude/skills/refactor-docs

## Install

```sh
agentstack add skill-paulo-yamagishi-claude-code-setup-refactor-docs
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Refactor Docs

Split oversized or multi-topic documentation files into focused, smaller files following progressive disclosure principles.

## Steps

1. **Determine scope:**
   - If `$ARGUMENTS` is a file path, analyze only that file
   - If `$ARGUMENTS` is a directory, analyze all `.md` files in it
   - If `$ARGUMENTS` is empty, scan all `.md` files in: `core/`, `projects/`, `templates/`, `skill/`, `.claude/skills/`, `.claude/rules/`

2. **Identify candidates:** For each file, flag if:
   - Over 300 lines
   - Covers multiple distinct topics (detected by counting `##` sections on unrelated subjects)
   - Has large reference sections that could be extracted

3. **Propose split strategy** for each flagged file:

   **Core guides:** Split into `{topic}-guide.md` (essentials, <150 lines) + `{topic}-reference.md` (deep-dive details, examples, edge cases)

   **CLAUDE.md files:** Move detailed sections to separate files importable via `@import`, keep CLAUDE.md as a concise overview (<100 lines)

   **Rule files:** Break multi-topic rule files into single-topic files, each with appropriate `paths` frontmatter for scoped loading

   **Skill files:** Extract large reference sections into companion files only if the skill exceeds 250 lines (skills should be self-contained where possible)

4. **Present the plan** with before/after line counts for each file. Wait for user approval before proceeding.

5. **Execute the refactor:**
   - Create new files with extracted content
   - Update the original file to reference the new files
   - Update `@import` directives in CLAUDE.md if applicable
   - Update cross-references in other files that linked to the original

6. **Verify:** After refactor, confirm:
   - No broken cross-references (Grep for old paths, check they've been updated)
   - All new files are under 300 lines
   - No content was lost in the split

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [paulo-yamagishi](https://github.com/paulo-yamagishi)
- **Source:** [paulo-yamagishi/claude-code-setup](https://github.com/paulo-yamagishi/claude-code-setup)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-paulo-yamagishi-claude-code-setup-refactor-docs
- Seller: https://agentstack.voostack.com/s/paulo-yamagishi
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.