Skip to content
Michi v2026.11.16
Save the Tokens

michi-library

Michi’s working docs are written for an agent: dense, additive, shaped like a decision log, exhaustive because leaving something out costs the agent context. That is the right shape while you are in the loop. It fails at handoff — when the work has to be understood by someone who wasn’t in the sessions. This skill derives the reader-facing layer. The working docs stay as they are: epics, plans, debriefs and journals are the record, not the deliverable.

  • A colleague needs to understand a project, use it, or work on it, and the working docs don’t say where to start
  • A teammate is receiving a module, or a reviewer is picking up a branch
  • Someone is coming to an epic cold — a collaborator, or you after a long pause
  • The root docs (README, PROJECT.md, STATUS.md) have drifted or contradict each other

The target decides the shape of the output. The skill asks if you don’t say.

CommandProducesTouches root docs?
/michi-library project <roles>a library of reader docs for those roles in docs/library/ (or a library-root: you set), markdown plus an HTML siteone link in README.md, if it exists; library-root: in CLAUDE.md, if you pick another location; STATUS.md
/michi-library project configurechanges to the library’s settings: its roles, its editions, its location; then builds what changedlibrary-root: in CLAUDE.md, if you move the library
/michi-library scope <thing>a new standalone artifact for a feature, module or branchSTATUS.md only
/michi-library epic <epic>an overview.md in the epic folder, for a reader new to the epicSTATUS.md only

At the scope target the skill asks who the reader is, because the rules flip. For a teammate with repo access, file paths are the most useful thing in the document. For someone outside the team, they are dead weight — the fact gets inlined or dropped. Before drafting, the skill presents the proposed layer structure and what goes where, and you agree it.

At the epic target the skill proposes one of two shapes and you confirm; if neither fits, it says so and proposes a lighter answer. Epic full — for new features, strategic or conceptual work, spikes and rebuilds — covers the problem, where it stands, the process and work, what surprised or changed along the way, the results and the takeaways. Epic condensed — for maintenance, cleanup and tweaks — is a few bullets of what was done and what’s still open. Both leave out the bulk of an epic (step lists, test counts, raw transcripts) and take the current state from the latest evidence rather than any status header. If the epic has a hand-written README.md, the skill reads it as a source; the overview sits beside it and never replaces it. The overview is a dated snapshot: run the target again to refresh it.

/michi-library project all — or one role, or a list (project observer, project practitioner, contributor). If you don’t name them, the skill uses the roles recorded in docs/library/library.conf, or asks.

Readers are roles, not people. A role is a reason for reading, and anyone can take any role. The reader is a colleague who knows the domain, but not this project. Observers and practitioners may not have the repo, so their documents link only within the library and to the web. Contributors work in the repo, and their documents link into it.

RoleAsksDocuments
ObserverWhat is it, why does it exist, where is it going?overview, reading guide, roadmap
PractitionerHow do I install it and use it?getting started (with hello world), usage guide, limitations, reference, upgrading, changelog, FAQ (optional)
ContributorHow do I set up to work on it, and what’s next?contributor guide, backlog; ARCHITECTURE.md and STATUS.md linked as they are

Every library also gets a tl;dr (what it is, its status, the key ideas, where to go next) and a glossary of the project’s own terms. Upgrading is written when a change has required users to act; a changelog when the project has versioned releases (an existing CHANGELOG.md is linked instead).

Parts. When a reader would pick some parts of a project and skip others — the packages of a monorepo, say — the skill proposes parts and you confirm. Shared material stays at the top; each part gets its own documents in docs/library/<part>/.

Documents beyond the templates. The templates are what every project gets, not everything a project may need. Some readers bring a question only some projects raise, such as what happens to their data or how the system is operated. Some topics are big enough for a document of their own: an API or a catalog of rules, the alternatives considered and their shortcomings, or how the project evolved. Before drafting, and again before closing, the skill asks whether anything else is needed, and it may propose a document it finds a case for while drafting. Nothing beyond the templates is written without your yes. Each extra document is listed in docs/library/library.conf (doc|<file>|<label>|<role>), and the HTML puts it in that role’s sidebar after the templated documents.

Existing docs are material. The skill draws on what’s there instead of linking a reader into it: PROJECT.md is the overview’s source, re-drawn on every run. STATUS.md, an existing CHANGELOG.md, and for now ARCHITECTURE.md are linked as they are. Where an existing doc conflicts with a template, you decide what happens to it. If there’s no README.md, the skill doesn’t create one.

The HTML site. The skill builds docs/library/html/ from the markdown: open index.html (the tl;dr) in a browser.

  • A tab per role across the top, and a sidebar with only that role’s pages, one section per part. A part is headed by its folder name, or by a label you give it in docs/library/library.conf (part|<folder>|<label>) when folder names would confuse a reader. A document listed for several roles gets a page in each, so clicking it in the sidebar never moves you to another role.
  • Previous and Next stay within a role (and a part), and the last page says so, so an observer isn’t walked into the API reference.
  • Each role’s first page points back to the project intro, for readers who came in through a tab.
  • Mermaid diagrams are rendered to SVG, readable in light and dark mode.
  • A search box in the header lists matching sections as you type, from the pages in that build only. It works when the pages are opened from disk or unzipped, with no server.
  • Links to repo markdown (STATUS.md, a package README) stay links to the live files; a markdown viewer extension in the browser shows them formatted. An edition without the repo carries them as pages instead (below).
  • To put a repo file in a sidebar as it is (a part’s README as its reference, say), list it in docs/library/sidebar-links, one role|part|label|repo-relative path per line (part empty for the project-wide section).

The HTML is regenerated on every run, so never edit it. The build needs pandoc 3.1.1 or later, and Node 22.13 or later (for the diagrams) unless mmdc is installed. If the project runs a formatter, the skill formats the library’s markdown and adds html/ to the formatter’s ignore file.

An edition is part of the library built for some readers: an observer-only version, say, or one for observers and practitioners to send to someone outside the team. Run /michi-library project configure, and the skill asks two things: which roles, and who reads it.

VisibilityThe readerWhat the build does
privatehas the repolinks into the repo work as usual
colleaguea colleague without the repopackage READMEs and other sidebar files become pages; a link that would leave the bundle, or any mention of a document only the repo has, stops the build; the result is zipped
externalsomeone outside the organizationas colleague, plus a check for first person, internal IDs (M19), and repo paths

The edition is named from those choices (observer-practitioner-external), and it lives in docs/library/editions/ as a small file you keep: the roles, the visibility, and, only if you ask, the parts to keep, documents to leave out, terms to let through, redacted stand-ins for files (a package README without its internal references, say), and files to carry as they are (a downloadable schema, or a self-contained player a page embeds). The build writes the HTML next to it and, unless it is private, a dated zip; both are generated and git-ignored. Open the zip anywhere: every link stays inside it.

Leaving a role out leaves no trace of it. In every edition, the build drops a section whose heading names the role (“For contributors”), a passage the source marks for it (<!-- role: contributor --> … <!-- /role -->), and a list line or table row whose every link points at the role’s documents. A heading left empty goes too, and the build reports each drop. Then it reads each page as the reader will and stops on anything left: the role’s name, the titles of its documents, a link to one of them, and, unless the edition is private, any document only the repo has (STATUS.md, a path under docs/). For each stop the skill proposes a fix (reword, move under a role heading, mark it, or let that term through for this edition) and changes nothing without your yes.

When the external check finds first person, an internal ID, or a repo path in a library document, it stops the zip too. It reads each page as the edition ships it, so a passage dropped for a left-out role doesn’t count, and each finding names the page and the passage it is in. A product name or a quoted phrase that only looks like first person can be let through on its page, by the word or by the whole phrase. Its findings in a package README are reported, not fixed, since that file isn’t the library’s; a redacted stand-in is the way to share one without them.

Refresh by running the target again with the same roles. The previous library is material like any other doc: what’s still true is kept, and anything that conflicts with a source is raised with you.

Diagnoses before writing. It inventories the whole doc set first — including any index that already exists — then checks for five failure modes, most of which can be found with a search rather than a judgment call:

  1. Addressed to the operator — “the criteria you set,” “I measured.” The reader is eavesdropping on a conversation between one person and one agent.
  2. The self-correction record — the agent’s revision history left in the artifact: “this count was wrong four times,” warning markers on every other claim. Useful to the operator, noise to a newcomer.
  3. Status where structure is needed — “where it stands” before anyone has said what “it” is.
  4. Unresolvable references — internal section numbers, milestone IDs, links a reader can’t follow.
  5. No landing — no start-here, one altitude throughout, no reading order.

Writes in layers. A short start-here that stands alone and names what to read next; working detail; deep reference as needed. Within a document, the phases run what it is → what it can and can’t do → how it’s built → where it stands, so a reader can stop at the phase that answered them.

Draws diagrams with the michi-diagrams skill, where a figure shows a relationship the prose can only describe.

Aggregates across epics. When material is spread over many efforts it names the through-line, tabulates where the same thing appears under different names, says which numbers are not comparable, and states the honest conclusion — including the unflattering part.

Runs reader tests before claiming done. A stranger read; a sweep for first- and second-person subjects; every structural claim checked against the repo in the same session; the docs read against each other for contradictions; every document named in a reading path actually opened. At the project target, also: every link resolves, and every command the docs name exists. It runs hello world if that is safe and cheap; otherwise it says the commands were checked, not run.

  • Project target: the library — markdown in docs/library/ and the HTML site in docs/library/html/; with configure, editions in docs/library/editions/
  • Scope target: a standalone artifact carrying an audience line, an as-of date, and a provenance block marked internal
  • Epic target: the epic’s overview.md, full or condensed, with an as-of date and its sources
  • A capture of the gaps — what was stale, what contradicted what, what the sources couldn’t answer
  • It avoids second copies. Fast-changing content — status, near-term work, conventions in CLAUDE.md — is linked where it lives, not copied, because copies drift.
  • It won’t invent to fill a template. A section with nothing true to say is left out; if the sources never answered something, that is the finding, surfaced for you to follow up.
  • It won’t launder uncertainty. If a number took three attempts, the reader is told its confidence once, plainly — not as a running correction log.
  • If the work reveals that requirements were never decided, that is /michi-explore or /michi-planning work. If the drift is structural, /michi-sustainability has the repo-wide audit.

For the full agent instructions, see the SKILL.md source.