Indexion Readme
Scaffold, generate, plan, and assemble monorepo READMEs from doc.json, templates, and per-package doc comments—with drift checks via Indexion.
Overview
Indexion README is an agent skill most often used in Build (also Ship review, Operate iterate) that constructs and verifies monorepo READMEs from doc.json, templates, and Indexion CLI workflows.
Install
npx skills add https://github.com/trkbt10/indexion-skills --skill indexion-readmeWhat is this skill?
- End-to-end README construction: template init, per-package generation, task planning, root assembly, and verification
- Supports doc.json at repo root or under `.indexion/readme/` with `.indexion.toml` auto-load paths
- Per-package README paths under `cmd/<name>/` or `src/<name>/` plus static slices like `docs/intro.md`
- Handles MoonBit-style `README.mbt.md` with optional `README.md` symlink when doctest layout requires it
- Verification step uses `plan drift` to catch documentation edits that diverge from the planned README graph
- Five construction stages: scaffold, generate, plan, assemble, verify via plan drift
Adoption & trust: 515 installs on skills.sh; 1 GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
Your multi-package repo has drifting per-crate READMEs and no reliable way to regenerate the root README from templates and doc comments.
Who is it for?
Maintainers of Indexion- or MoonBit-aware monorepos who want doc.json as source of truth for README assembly.
Skip if: Single-package repos that only need a one-shot narrative README without templates, doc.json, or CLI verification.
When should I use this skill?
README construction—initialize templates, generate per-package READMEs, plan writing tasks, assemble root README from docs/ and package READMEs, verify with plan drift.
What do I get? / Deliverables
You get initialized templates, generated package READMEs, a assembled root README driven by doc.json, and a drift check that flags plan mismatches after edits.
- Per-package README.md files
- Assembled root README (or README.mbt.md + symlink)
- Drift verification report from plan drift
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Primary shelf is Build/docs because the skill’s outputs are README artifacts and doc.json-driven assembly, not runtime code. Docs subphase covers template initialization, per-package README generation, and root README composition from structured config.
Where it fits
Initialize `docs/templates/readme.md` and wire `doc.json` before the first automated package README generation pass.
Plan README writing tasks across `cmd/*` packages so contributors know which prose blocks remain manual.
Run `plan drift` before tagging a release to ensure root README assembly still matches doc.json.
After an API rename in `src/foo`, regenerate that package README and reassemble the root file.
How it compares
Structured README pipeline with CLI drift checks, not a single conversational README draft.
Common Questions / FAQ
Who is indexion-readme for?
Solo and small-team developers using Indexion tooling on monorepos—especially MoonBit or multi-package layouts—who need reproducible README construction.
When should I use indexion-readme?
During Build/docs when scaffolding doc.json and templates, during Ship/review before release when verifying README drift, and during Operate/iterate when package APIs change and per-package READMEs must regenerate.
Is indexion-readme safe to install?
It expects filesystem edits and running Indexion CLI commands such as plan drift; review permissions and the Security Audits panel on this Prism page before use.
Workflow Chain
Then invoke: indexion documentation
SKILL.md
READMESKILL.md - Indexion Readme
# indexion readme — README Construction Build project READMEs from templates, doc comments, hand-written prose, and per-package READMEs. This skill covers the **construction side**: scaffolding, generating, planning, assembling, and verifying. For evaluating existing documentation, see `indexion-documentation`. ## Where things live The conventions vary by project; check what actually exists before editing: | Asset | Location patterns seen | |-------|------------------------| | Config | `doc.json` (repo root) **or** `.indexion/readme/doc.json` | | Per-package template | `docs/templates/readme.md` (no SoT constant; declared via `--template`) | | Static prose | `docs/intro.md`, `docs/installation.md`, `docs/license.md`, … | | Per-package READMEs | `cmd/<name>/README.md`, `src/<name>/README.md` | | Assembled root README | usually `README.md`. Some projects use a `.mbt.md` suffix so the file is also a MoonBit doctest module — when so, `README.md` is a symlink to `README.mbt.md`. | | `.indexion.toml` | `[doc] config_path` / `per_package` auto-load doc.json | **The first thing to check** is `git diff` / `ls -la` for: a symlink on `README.md`, a `doc.json` (at root or under `.indexion/readme/`), and `.indexion.toml`. The presence of these tells you whether the README is hand-maintained, build-assembled, or a hybrid. ## Workflow overview ``` doc init → .indexion/readme/template.md + doc.json (greenfield) edit doc.json + docs/*.md → declare sources of truth doc readme --per-package → cmd/<pkg>/README.md (API skeletons; non-overwriting) hand-write each per-package README's Overview / Usage / Options / Examples doc readme --config → assembled root README plan drift <prev> <new> → verify the assembled output (or hand-edit) is purely additive ``` ## Step 1: Initialize (greenfield only) ```bash indexion doc init <project-dir> ``` Creates `.indexion/readme/template.md` + `.indexion/readme/doc.json`. Skip this step on a project that already has `doc.json` or `.indexion.toml` pointing at one. ## Step 2: Configure doc.json ```json { "$schema": "./schemas/doc-config.schema.json", "version": "1.0", "spec": "moonbit", "output": { "format": "markdown", "filename": "README.md" }, "packages": [ { "path": "cmd/<name>", "title": "<command name>", "include_in_root": true, "sections": ["overview", "usage"] } // …one entry per package that should appear in the assembled root README ], "root": { "output": "README.md", "sections": [ { "type": "static", "file": "docs/intro.md" }, { "type": "toc", "title": "Commands" }, { "type": "packages", "filter": "cmd/**" }, { "type": "static", "file": "docs/installation.md" }, { "type": "static", "file": "docs/license.md" } ] } } ``` **Root section types:** - `static` — include a markdown file verbatim - `toc` — insert a table-of-contents heading - `packages` — pull in entries from the `packages` array, filtered by glob **Package fields:** - `include_in_root` — whether to include in the assembled root README - `sections` — README headings to extract; honored by per-package extraction flows. Note that `{ "type": "packages" }` in the root currently emits a **table** of package links, not the rich Overview/Usage expansion implied by per-package `sections`. See "Known limitation" below. ## Step 3: Generate per-package READMEs ```bash indexion doc readme --per-package src/ cmd/ ``` Generates `README.md` in each package directory that doesn't already have one. **Non-overwriting** — existing per-package READMEs are left alone. The skeleton is API-only (extracted from `///` doc comments v