---
name: doc-management
source: botcore
description: >
  Documentation architecture and maintenance policy for Lushly repositories.
  Use when creating docs, reviewing structure, or preventing documentation rot.
version: "1.0.0"
category: core
triggers:
  - documentation
  - docs
  - readme
  - agents.md
  - claude.md
  - doc site
  - docsify
---

# Documentation Management

Single source of truth policy for Lushly repositories.

## Capabilities

1. **Architecture guidance** — Define where documentation belongs
2. **Rot prevention** — Policies to keep docs maintainable
3. **Doc site setup** — Docsify configuration for browsable skills

## Documentation Architecture

| Layer | File | Purpose | Target Size |
|-------|------|---------|-------------|
| Bootstrap | CLAUDE.md | MCP tools, skill routing | 100-120 lines |
| Knowledge | .claude/skills/ | All detailed docs | Unlimited |
| Human | README.md | Project intro, install | 50-100 lines |
| Browsable | docs/guide/ | Docsify site from skills | Auto-generated |

## Core Principles

### 1. Skills Are Truth

All detailed knowledge lives in `.claude/skills/`. CLAUDE.md and README are routing tables that point to skills.

### 2. No Deep Content in Bootstrap Files

If you're writing more than 5 lines about a topic in CLAUDE.md, it belongs in a skill. Bootstrap files should be scannable in under 30 seconds.

### 3. Link, Don't Duplicate

Reference skills instead of copying content. Duplication leads to rot.

### 4. MCP Tools Get One-Liners

Keep MCP tool descriptions brief in CLAUDE.md. Extended documentation goes in the relevant skill.

## Routing Logic

| Request | Load Reference |
|---------|----------------|
| Creating skills | [skill-manager](../skill-manager/) |
| Linting skills | [skill-manager/references/linter-rules.md](../skill-manager/references/linter-rules.md) |
| Doc site setup | [references/docsify-setup.md](references/docsify-setup.md) |
| Index generation | [references/index-generation.md](references/index-generation.md) |

## When to Create a Skill

Create a new skill when:
- Topic has >20 lines of content
- Topic will be referenced multiple times
- Topic needs examples or code blocks
- Topic is a distinct domain (testing, security, etc.)

## When to Keep in CLAUDE.md

Keep content in CLAUDE.md when:
- MCP tool table (one-liner descriptions only)
- Quick command reference (5-10 most common commands)
- Skill index with brief descriptions
- Environment variables list
- Cross-repo skill links

## Preventing Documentation Rot

### Policy Note

Add this note to the top of CLAUDE.md and README.md:

```markdown
> **Documentation Policy**: Skills are the source of truth. This file is a
> routing table. See [doc-management skill](.claude/skills/doc-management/)
> for full policy.
```

### Automated Checks

1. **Skill linter** — `lush-dev action=skill-lint` validates skill structure
2. **Index generation** — Auto-generate skill index from frontmatter
3. **PR review** — Flag CLAUDE.md changes adding >10 lines of content

### Category Organization

Skills should include a `category` field in frontmatter:

```yaml
category: core        # Fundamental skills (doc-management, skill-manager)
category: development # Development workflows (testing, spec-writer)
category: review      # Code/content review (security, reviewer, duplicates)
category: quality     # Quality attributes (performance, accessibility)
```

## Cross-Repository Pattern

For multi-repo setups like Lushly:

1. **Lushbot** — Shared skills live here (skill-manager, doc-management)
2. **Other repos** — Project-specific skills only (e.g., `afd` skill in AFD repo)
3. **CLAUDE.md linking** — Lushbot CLAUDE.md can reference other repos' skills

```markdown
## Cross-Repo Skills
When working in other Lushly repos, load their skills:
- AFD: `../AFD/.claude/skills/afd/`
```

## Checklist

- [ ] CLAUDE.md has doc policy note at top
- [ ] README.md has doc policy note at top
- [ ] All skills have `category` in frontmatter
- [ ] No content blocks >5 lines in CLAUDE.md
- [ ] Skill index is up to date
- [ ] Doc site reflects current skills

## When to Escalate

- Major restructuring of documentation architecture
- Adding new documentation layers
- Changing the skill specification format
