docs-organization

# docs-organization

Practical documentation structure templates for AI-assisted projects. Helps AI coding agents (and humans) organize project docs by size, audience, and freshness.

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

## What it does

Answers the question every project eventually asks: *where should this doc go?*

Given a project, this skill:
1. **Assesses project size** (small / medium / large) using a simple rubric
2. **Recommends a directory structure** with templates for each size
3. **Classifies existing docs** by audience (agent, operator, user) and freshness (canonical, snapshot, archived)
4. **Slims bloated CLAUDE.md/AGENTS.md** by extracting reference material into dedicated files
5. **Prevents drift** with single-source-of-truth principles and doc metadata conventions

Works with any AI coding agent: Claude Code, OpenClaw, Codex CLI, Cursor CLI, Cursor, Cursor.

## Quick Start

```bash
# Universal (npx skills)
npx skills add zning1994/docs-organization

# OpenClaw ClawHub
openclaw skills install docs-organization

# Standalone
git clone https://github.com/zning1994/docs-organization
```

## When to use

- Setting up docs for a new project
- Reorganizing a messy `docs/` folder
- CLAUDE.md or AGENTS.md is over 250 lines
- Same information duplicated across multiple markdown files
- Not sure where a new doc should live
- Need to archive old design specs or research notes

## Core Principles

### 1. Single Source of Truth

Every fact lives in exactly one place. Other docs *link* to it, never *copy* it.

### 2. CLAUDE.md Is a Routing Table

Keep CLAUDE.md under 250 lines. It tells AI agents where to find things, not what things are. Extract API tables, deploy procedures, and changelogs into `docs/`.

### 3. Organize by Audience + Freshness

| Directory | Status | Contains |
|-----------|--------|----------|
| `reference/` | canonical | API, DB schema, config |
| `runbooks/` | canonical | Deploy, ops, incidents |
|