literate-guide_skill

Overview

This skill creates a Knuth-style literate guide: a single narrative essay that interleaves prose and minimal code excerpts to teach a codebase or feature. It organizes material for human understanding, surfaces key design decisions, and numbers sections with the § symbol so readers can follow a conceptual thread rather than a file tree. The output is aimed at developers who need a readable, opinionated walkthrough that explains both what the code does and why it was written that way.

How this skill works

I first ask about scope and audience so the guide targets the right level of detail. Then I read the codebase or selected subsystem, identify the problem, domain model, core flows, and 3–5 defining design decisions. The guide is written as numbered sections (§1, §2, ...) with short prose, trimmed code excerpts (file path and line range noted), explanations of tradeoffs, and cross-references using § notation. Deliverable is a single Markdown essay with optional Mermaid diagrams where useful.

When to use it

• You want a narrative walkthrough that a new developer can read start-to-finish.
• You asked: "Explain this codebase as a story" or "Write a literate guide."
• A feature or PR needs a readable explanation of why choices were made.
• You need documentation that emphasizes design rationale over API reference.
• You prefer prose-first organization rather than file-ordered docs.

Best practices

• Scope tightly for large projects: prefer a subsystem or feature for depth over breadth.
• Identify the audience up front (new hire, reviewer, contributor, personal notes).
• Show only minimal code needed to make a point; annotate each excerpt.
• Make design tradeoffs explicit: alternatives considered, constraints, and consequences.
• Use § cross-references liberally to weave sections into a coherent web.

Example use cases

• A UX agent feature in the repo needs a story explaining its event model and UI hooks.
• Document a parameter-tuning subsystem so maintainers understand expected invariants.
• Explain a design pivot in a recent PR: why earlier approach failed and the chosen fix.
• Create onboarding material for contributors that covers domain model and core flows.
• Produce a readable artifact for release notes that explains internal architecture changes.