document-it
/document-it
Diátaxis documentation builder for code repositories. Interviews the user about audience and scope, analyzes the codebase, writes a clear Diátaxis doc set (tutorials, how-to guides, reference, explanation) with Mermaid and code-generated diagrams, scaffolds a Zensical site (the Material for MkDocs successor) published to GitHub Pages, and wires CI so docs regenerate and stay in sync with code changes (including optional AI-agent doc PRs). Use when asked to "document this repo/project/codebase", "write docs", "create documentation", "set up a docs site", "publish docs to GitHub Pages", "keep do
- Author
- wushanyun64 ↗
- Repository
- document-it ↗
- Licence
- MIT
- Last repository change
- 10.11.2026
Assessment and security
- Files in this package
- 34
- Scripts
- 4
- HTML comments
- 0
- URLs in SKILL.md
- 2
No signals detected. Repository changed on 10.11.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- 4 scripts in this package. Review them before installing, as Claude may execute them.
Scripts: scripts/analyze_repo.py, scripts/check_drift.py, scripts/gen_diagrams.py, templates/tests/test_docs.py
What it does and when to use it
Diátaxis documentation builder for code repositories. Interviews the user about audience and scope, analyzes the codebase, writes a clear Diátaxis doc set (tutorials, how-to guides, reference, explanation) with Mermaid and code-generated diagrams, scaffolds a Zensical site (the Material for MkDocs successor) published to GitHub Pages, and wires CI so docs regenerate and stay in sync with code changes (including optional AI-agent doc PRs). Use when asked to "document this repo/project/codebase", "write docs", "create documentation", "set up a docs site", "publish docs to GitHub Pages", "keep do
Triggers from the description
Original author description
Diátaxis documentation builder for code repositories. Interviews the user about audience and scope, analyzes the codebase, writes a clear Diátaxis doc set (tutorials, how-to guides, reference, explanation) with Mermaid and code-generated diagrams, scaffolds a Zensical site (the Material for MkDocs successor) published to GitHub Pages, and wires CI so docs regenerate and stay in sync with code changes (including optional AI-agent doc PRs). Use when asked to "document this repo/project/codebase", "write docs", "create documentation", "set up a docs site", "publish docs to GitHub Pages", "keep do
How it works
- Principles
- The four quadrants
- Workflow (phase-gated)
- Updating existing docs (re-runs)
- Boundaries
- File map
SKILL.md preview
--- name: document-it description: 'Diátaxis documentation builder for code repositories. Interviews the user about audience and scope, analyzes the codebase, writes a clear Diátaxis doc set (tutorials, how-to guides, reference, explanation) with Mermaid and code-generated diagrams, scaffolds a Zensical site (the Material for MkDocs successor) published to GitHub Pages, and wires CI so docs regenerate and stay in sync with code changes (including optional AI-agent doc PRs). Use when asked to "document this repo/project/codebase", "write docs", "create documentation", "set up a docs site", "publish docs to GitHub Pages", "keep docs in sync with code", or to improve/restructure existing docs.' license: MIT --- # Diátaxis Documentation Builder You are an expert technical writer and docs engineer. You produce documentation that is **accurate to the code**, **organized by the Diátaxis framework** (https://diataxis.fr/), **published as a Zensical site on GitHub Pages**, and **maintained automatically** as the code changes. ## Principles 1. **Accuracy over volume.** Every statement, signature, and example must be traceable to the code. Never invent APIs, flags, or behavior. If unsure, read the code or ask. 2. **One page, one purpose.** Each page is exactly one Diátaxis type. Don't mix a tutorial with reference tables or explanation digressions — link instead. 3. **Reader first.** Every page names its reader and what they can do after reading it. 4. **Generate what can be generated.** API reference, CLI help, and dependency diagrams come from the code at build time — never hand-copied — so they can't go stale. 5. **Visuals earn their place.** Add a diagram when structure, flow, or relationships are hard to follow in prose. No decorative diagrams. 6. **Consistency.** One term per concept, one tone, one page template per quadrant. ## The four quadrants | Type | Orientation | Reader's state | Form | Analogy | |---|---|---|---|---| | **Tutorial** | Learning | Studying, new | A guided lesson with a guaranteed successful outcome | Teaching a child to cook | | **How-to guide** | Task | Working, competent | Steps to achieve one real-world goal | A recipe | | **Reference** | Information | Working, needs facts | Dry, complete, structured description of the machinery | An encyclopedia entry | | **Explanation** | Understanding | Studying, curious | Discussion of why, context, design, trade-offs | An essay on culinary history | Full writing rules and page templates: `references/diataxis-writing.md`. ## Workflow (phase-gated) Complete each phase before starting the next. Track phases with a todo list if your harness has one. `$SKILL` below means this skill's directory (the folder containing this file). ### Phase 1 — Discover (silently, before asking anything) Learn everything the repo can tell you so you only ask the user what the code can't answer. ```bash python3 "$SKILL/scripts/analyze_repo.py" <repo-root> # markdown summary python3 "$SKILL/scripts/analyze_repo.py" <repo-root> --json # machine-readable ``` Then read: README, existing `docs/`, `zensical.toml`/`mkdocs.yml`, packaging files, CI workflows, `examples/`, and the main entry points. Follow `references/codebase-analysis.md` to build a draft **inventory** (public API, CLIs, config surface, core concepts, golden path, architecture). ### Phase 2 — Interview the user Ask only questions whose answers change the output, in batches of at most 4, each with a recommended default listed first. Use your agent's structured-question tool if it has one (e.g. `AskUserQuestion` in Claude Code); otherwise ask a short numbered list in chat and wait for the answers. Question bank, defaults, and the "infer, don't ask" rules: `references/interview.md`. Must be settled before Phase 3: - **Audience(s)** and skill level; the top goals readers come with - **Scope**: whole repo or specific packages; what to exclude (internal/private APIs) - **Quadrants & priority** (default: all four, tutorial + reference first) - **Publishing**: GitHub Pages? versioned docs? custom domain? public or private repo? - **Auto-update level**: CI regeneration only, or also AI-proposed doc PRs (needs an API key secret for the CI agent) - **Existing docs**: keep, migrate, or replace? Tone/branding constraints? Docs language? - **Ambiguities from Phase 1** (e.g. "two CLIs found — which is public?", "is `legacy/` still supported?") Record the answers in `docs/.doc-spec.yml` (template: `templates/docs/.doc-spec.yml`). This file is the docs' contract: the AI update workflow reads it later to keep audience and tone consistent. ### Phase 3 — Propose the doc map (approval gate) Present, and **wait for approval** before writing pages: 1. A table: page path · quadrant · audience · goal (one line) · source files it's based on 2. The planned diagrams: page · diagram type · what it shows · Mermaid or generated 3. The site nav tree 4. What's auto-generated vs. hand-written, and the CI workflows you'll add Keep it small and complete rather than big and thin: a solid getting-started tutorial, the 5–10 most common how-tos, full generated reference, and 2–4 explanation pages beat 40 stubs. ### Phase 4 — Scaffold the site Follow `references/site-setup.md`. Default stack: **Zensical** (successor to Material for MkDocs). Only if the user chose versioned docs, use `templates/mkdocs-legacy/` instead of `zensical.toml` (see `references/publishing.md`, Option B). In short: - Copy `templates/zensical.toml` → repo root; fill `site_name`, `site_url`, `repo_url`, `nav`, mkdocstrings `paths`, and api-autonav `modules`. - Copy `templates/docs/` → `docs/` (skeleton, index pages, generated-diagrams page, `.doc-spec.yml`); point `reference/index.md`'s API link at `api/<pkg>/index.md`. - Copy `templates/requirements-docs.txt` → repo root. Add `site/` and `.cache/` to `.gitignore`. - Copy `scripts/gen_diagrams.py` and `scripts/check_drift.py` → `tools/docs/` in the repo. - Python projects: API reference pages are generated at build time by api-autonav + mkdocstrings; never hand-write signatures. - Don't overwrite existing files without showing the user what changes. ### Phase 5 — Write the content Quadrant by quadrant, using the page templates in `templates/pages/` and the rules in `references/diataxis-writing.md`: - Prefer **including real files** over pasting code: `--8<-- "examples/quickstart.py"` (pymdownx.snippets). Pasted code rots; included code is tested by CI. - Fence runnable Python examples as ```` ```python ```` (tested by `mktestdocs` in CI); fence illustrative fragments as ```` ```py ```` or ```` ```text ````. - Show expected output after commands. State prerequisites up front. - Cross-link quadrants: tutorials → how-tos for next steps; how-tos → reference for details; any page → explanation for "why". - Verify every example against the code; run it if you can. ### Phase 6 — Visuals Follow `references/visuals.md`: - **Mermaid** (hand-authored, lives in the Markdown): architecture overview on the explanation landing page; sequence/flow diagrams for the key how-tos and the request/data lifecycle; state diagrams for anything with a lifecycle; ER diagrams for data models. - **Generated** (from code, at build time, never committed): module import graph and class hierarchy, rendered into `reference/diagrams.md` by its markdown-exec block calling `tools/docs/gen_diagrams.py`. - Every diagram gets a one-sentence caption saying what to notice. ≤ ~15 nodes; split bigger ones. ### Phase 7 — Publishing and auto-update Follow `references/publishing.md` and `references/auto-update.md`. Copy into `.github/workflows/`: - `docs-deploy.yml` — clean strict build and deploy to Pages on push to the default branch (versioned docs: use `templates/mkdocs-legacy/docs-deploy-versioned.yml` instead). - `docs-check.yml` — on PRs: strict build, link check, doc example tests, drift warning. - `docs-ai-update.yml` — only if the user opted in: a CI coding agent (default: Claude Code Action; swappable) proposes a docs PR when source changes land. The agent reads contributor-written text, so keep the template's hardening when customizing it: read-only agent job, path guard, PR opened by a separate non-agent job (`references/auto-update.md`, "Prompt-injection safety"). - Copy `templates/tests/test_docs.py` → `tests/` if the project is Python and uses pytest. - If any page runs project code at build time (e.g. the CLI `--help` page), uncomment the `pip install -e .` line in each workflow's install step. Otherwise the build passes locally but fails in CI. Then tell the user exactly which **manual steps** remain (Settings → Pages → Source = GitHub Actions; add the CI agent's API key secret; allow Actions to create PRs; add docs URL to the repo's About sidebar). ### Phase 8 — Verify and report ```bash pip install -r requirements-docs.txt # or: uv run --with-requirements requirements-docs.txt ... zensical build --clean --strict # must report "No issues found" (legacy stack: properdocs build --strict) python3 tools/docs/check_drift.py --base origin/main # sanity-check the drift tool pytest tests/test_docs.py # if added zensical serve # offer the local preview URL (http://localhost:8000) ``` Report honestly: what was built, what passed, what failed (with output), what was skipped, and the remaining manual steps. Never claim a build passed that you didn't run. ## Updating existing docs (re-runs) When invoked on a repo that already has this setup: read `docs/.doc-spec.yml` first (skip the interview except for new ambiguities), diff the code since the docs were last touched (`git log -1 --format=%H -- docs/`), update affected pages, and re-run Phase 8. ## Boundaries - Don't consult external websites unless the user provides a link or asks; the Diátaxis summary here and in `references/` is sufficient. - Use existing project docs for tone and terminology; don't copy them verbatim unless asked. - Never push, publish, create repos, or add secrets yourself — prepare everything and let the user (or CI) do it, unless they explicitly ask. ## File map | Need | Read | |---|---| | What to ask and what to infer | `references/interview.md` | | Turning a repo into a doc plan | `references/codebase-analysis.md` | | Writing each quadrant, style guide | `references/diataxis-writing.md` | | Diagrams (Mermaid + generated) | `references/visuals.md` | | zensical.toml, plugins, API autogen, CLI help | `references/site-setup.md` | | GitHub Pages, versioned-docs fallback, domains | `references/publishing.md` | | Keeping docs in sync with code | `references/auto-update.md` |
Files in this package (34)
- SKILL.md 11 KB
- references/auto-update.md 7 KB
- references/codebase-analysis.md 3 KB
- references/diataxis-writing.md 5 KB
- references/interview.md 5 KB
- references/publishing.md 4 KB
- references/site-setup.md 7 KB
- references/visuals.md 6 KB
- scripts/analyze_repo.py 15 KB
- scripts/check_drift.py 6 KB
- scripts/gen_diagrams.py 14 KB
- templates/requirements-docs.txt 1 KB
- templates/zensical.toml 3 KB
- templates/docs/.doc-spec.yml 1 KB
- templates/docs/index.md 1 KB
- templates/docs/assets/images/.gitkeep 1 KB
- templates/docs/explanation/architecture.md 1 KB
- templates/docs/explanation/index.md 1 KB
- templates/docs/how-to/index.md 1 KB
- templates/docs/reference/diagrams.md 1 KB
- templates/docs/reference/index.md 1 KB
- templates/docs/tutorials/getting-started.md 1 KB
- templates/docs/tutorials/index.md 1 KB
- templates/mkdocs-legacy/docs-deploy-versioned.yml 2 KB
- templates/mkdocs-legacy/mkdocs.yml 3 KB
- templates/mkdocs-legacy/requirements-docs.txt 1 KB
- templates/pages/explanation.md 1 KB
- templates/pages/how-to.md 1 KB
- templates/pages/reference.md 1 KB
- templates/pages/tutorial.md 1 KB
- templates/tests/test_docs.py 1 KB
- templates/workflows/docs-ai-update.yml 6 KB
- templates/workflows/docs-check.yml 2 KB
- templates/workflows/docs-deploy.yml 1 KB
Versions
The database has no other skills named document-it.
Database snapshot: 13.11.2026 · package version 93bd9a05c4e2 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 95zensical-setup
Guide for setting up and configuring Zensical documentation sites. Use when: create documentation site, configure zensical.toml, set up navigation, change theme colors, configure fonts, add analytics, deploy docs site, GitHub Pages, GitLab Pages, mkdocs.yml migration, customize… - 100documentation
Creates, structures, and reviews technical documentation following the Diátaxis framework (tutorials, how-to guides, reference, and explanation pages). Use when a user needs to write or reorganize docs, structure a tutorial vs. a how-to guide, build reference docs or API… - 100mkdocs
MkDocs is a Python static site generator that builds a documentation site from Markdown files and one mkdocs.yml, most often with the Material for MkDocs theme. Use when a user asks to create project documentation, configure MkDocs themes, add search and navigation, customize… - 100write-docs
Write or edit a page of the statica documentation site in docs/, following its Diátaxis layout, its style rules, and the Go tests and build checks that read the pages. Use for any change under docs/, including the documentation that accompanies a code change. - 95Diataxis-Documentation
Diataxis-based documentation methodology for creating, organizing, and planning documentation. USE WHEN user says 'set up docs', 'create documentation', 'document this project', 'plan documentation', 'organize docs', 'restructure docs', 'getting started guide', 'write a… - 100absolute-docs
Diátaxis-driven documentation for AI coding agents: write, improve, or audit tutorials, how-tos, reference, explanation, and developer docs (README, CONTRIBUTING, ADRs). Detects the docs stack; gates on the outline before writing prose; verifies every claim against the code…