Skip to content
Back to search

litprog-skill

Literate programming skill for agent harnesses like Claude Code, OpenCode and Hermes Agent

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/tlehman--litprog-skill/badge.svg)](/listings/tlehman--litprog-skill)

HTML

<a href="/listings/tlehman--litprog-skill"><img src="/api/listings/tlehman--litprog-skill/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Copy `SKILL.md` into your project's `.claude/skills/` directory:

git clone https://github.com/tlehman/litprog-skill.git
mkdir -p your-project/.claude/skills/
cp litprog-skill/SKILL.md your-project/.claude/skills/literate-programming.md

Claude Code automatically discovers skills from `.claude/skills/` in your project root. After copying, the `/literate-programming` slash command will be available in any Claude Code session within that project.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 331 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Literate Programming
  2. Transform a codebase into a literate program: a document written for human comprehension that also generates the original source code.
  3. ## Overview
  4. A literate program is a single `.lit.md` markdown file that serves as both documentation and source code. It produces two outputs:
  5. - **WEAVE** → A PDF (via Pandoc) with prose, diagrams, math, and syntax-highlighted code.
  6. - **TANGLE** → The original source files, extracted from named code chunks.
  7. The prose explains *why* the code exists and how it works. The code is embedded in named chunks that can reference each other. The reader follows a narrative, not a file listing.
  8. ## Chunk Syntax
  9. Code blocks become named chunks by adding attributes:
  10. ````
  11. ```ts {chunk="handle-request" file="src/server.ts"}
  12. <<parse-headers>>
  13. <<route-request>>
  14. <<send-response>>
  15. ```
  16. ````
  17. - `chunk="name"`: names the block (required for inclusion in the tangled output)
  18. - `file="path"`: marks it as a root chunk that produces an output file
  19. - `<<chunk-name>>`: references another chunk. Expanded recursively during tangling
  20. Same-named chunks are concatenated in document order (additive chunks), enabling progressive elaboration.
  21. For full syntax details, see `references/chunk-syntax.md`.
  22. ## Workflow
  23. When the user asks you to create a literate program from a codebase, follow these steps:
  24. ### Step 0: Check for Existing .lit.md
  25. Before analyzing the codebase, check if a `.lit.md` file already exists in the project. If one exists:
  26. 1. Skip creation entirely. Do not recreate from scratch.
  27. 2. Tangle the existing `.lit.md` to regenerate source files:
  28. ```bash
  29. bun run scripts/tangle.ts <file.lit.md> --output-dir <dir>
  30. ```
  31. 3. Weave the existing `.lit.md` to regenerate the PDF:
  32. ```bash
  33. pandoc <file.lit.md> -o <file.pdf> --pdf-engine=xelatex --filter mermaid-filter --toc --number-sections
  34. ```
  35. 4. Report what was done and exit.
  36. If no `.lit.md` exists, proceed with the steps below to create one.
  37. ### Step 1: Find Entry Points
  38. Locate where execution begins. Check `package.json`, `main()` functions, `__main__.py`, or the public API surface for libraries. This is where the narrative starts.
  39. ### Step 2: Trace Data Flow
  40. Follow data from input to output through the codebase:
  41. - What does the program consume? (CLI args, files, network, env vars)
  42. - What transformations does it apply?
  43. - What does it produce?
  44. Each stage of this pipeline becomes a candidate section.
  45. ### Step 3: Identify Background Processes
  46. Look for event loops, worker threads, scheduled tasks, signal handlers, and message queues. These are parallel flows that interact with the main pipeline and deserve their own sections.
  47. ### Step 4: Plan Diagrams
  48. Choose diagrams to illustrate the architecture before showing code:
  49. - Module dependencies → `graph TD`
  50. - Request lifecycle → `sequenceDiagram`
  51. - Data pipeline → `graph LR`
  52. - State machines → `stateDiagram-v2`
  53. Check `which mermaid-filter` first. If available, write these as ` ```mermaid ` blocks. If not, write them as TikZ `{=latex}` raw blocks (see TikZ section in Writing the .lit.md).
  54. Place each diagram *before* the code it describes.
  55. ### Step 5: Determine Psychological Order
  56. Present code in the order easiest to understand, not the order files appear on disk. Common strategies:
  57. - **Top-down**: Architecture first, then drill into components
  58. - **Data-centric**: Core types first, then operations
  59. - **Narrative**: Follow a request/event from start to finish
  60. Each section should build on the previous one. Defer edge cases and error handling until after the happy path is clear.
  61. ### Step 6: Plan the Outline
  62. Write a section outline before writing any prose or code. Each section should:
  63. 1. Motivate the problem it solves
  64. 2. Show a diagram (if helpful)
  65. 3. Present the code in named chunks
  66. 4. Explain non-obvious decisions
  67. For detailed guidance, see `references/analysis-workflow.md`.
  68. ### Step 7: Verify Before Overwriting
  69. Before tangling for the first time (which overwrites source files), run the tangler in verify mode to confirm the `.lit.md` captures every file completely:
  70. ```bash
  71. bun run scripts/tangle.ts project.lit.md --output-dir ./src/ --verify
  72. ```
  73. This compares tangled output against existing files without writing anything. If any file differs, it reports the first mismatched line and exits with code 1. Fix all mismatches in the `.lit.md`, then tangle for real.
  74. ## Writing the .lit.md
  75. ### Document Structure
  76. ```markdown
  77. ---
  78. title: "Project Name — A Literate Program"
  79. author: "Author"
  80. toc: true
  81. # (see assets/pandoc-header.yaml for full template)
  82. ---
  83. # Introduction
  84. Motivate the project. What problem does it solve? What is the key insight?
  85. # Section Title
  86. Prose explaining this part of the system...
  87. \```lang {chunk="chunk-name" file="path/to/file.ext"}
  88. code here
  89. <<reference-to-other-chunk>>
  90. \```
  91. More prose connecting ideas...
  92. ```
  93. ### Writing Principles
  94. 1. **Byte-for-byte completeness**: Every file with a root chunk (`file="path"`) must have 100% of its content captured in chunks. Tangle will overwrite that file, so any missing content will be deleted. If you don't want to manage a file, don't give it a root chunk.
  95. 2. **Prose first**: Every code block should be preceded by prose that explains *why* this code exists and what it accomplishes.
  96. 3. **Meaningful chunk names**: Names like `parse-config` or `validate-input` tell the reader what the chunk does. Avoid generic names like `code-1` or `part-a`.
  97. 4. **Progressive disclosure**: Introduce concepts gradually. Use additive chunks to build up a definition across multiple sections when that aids understanding.
  98. 5. **Cross-references via chunks**: When one section's code references another's via `<<chunk-name>>`, the reader can follow the logical thread by chunk name rather than hunting through files.
  99. 6. **Diagrams before code**: A Mermaid diagram gives the reader a mental model. The code that follows is easier to understand when the reader already sees the big picture.
  100. 7. **Math where it helps**: Use LaTeX math (`$...$` inline, `$$...$$` display) for algorithms, protocols, or any logic with a mathematical foundation.
  101. ### Mermaid Diagrams
  102. Embed diagrams directly in the markdown (not inside named chunks):
  103. ````markdown
  104. ```mermaid
  105. graph LR
  106. A[Input] --> B[Parse]
  107. B --> C[Transform]
  108. C --> D[Output]
  109. ```
  110. ````
  111. ### TikZ (when mermaid-filter is unavailable)
  112. If `which mermaid-filter` returns nothing, use TikZ instead. TikZ diagrams are raw LaTeX embedded via pandoc raw blocks:
  113. ````markdown
  114. ```{=latex}
  115. \begin{tikzpicture}[...]
  116. ...
  117. \end{tikzpicture}
  118. ```
  119. ````
  120. These are invisible in Markdown preview but render correctly in the PDF.
  121. **Translation patterns:**
  122. `graph LR` / `graph TD` → `tikzpicture` with `shapes,arrows` library:
  123. ````markdown
  124. ```{=latex}
  125. \begin{tikzpicture}[node distance=2cm, auto,
  126. block/.style={rectangle, draw, text width=4em, text centered, minimum height=2em},
  127. line/.style={draw, -latex}]
  128. \node [block] (A) {Input};
  129. \node [block, right of=A] (B) {Parse};
  130. \node [block, right of=B] (C) {Transform};
  131. \node [block, right of=C] (D) {Output};
  132. \path [line] (A) -- (B);
  133. \path [line] (B) -- (C);
  134. \path [line] (C) -- (D);
  135. \end{tikzpicture}
  136. ```
  137. ````
  138. `sequenceDiagram` → manual x/y placement (or use `pgf-umlsd` if available):
  139. ````markdown
  140. ```{=latex}
  141. \begin{tikzpicture}
  142. \node at (0,0) {Client};
  143. \node at (4,0) {Server};
  144. \draw[->] (0.3,-0.5) -- node[above]{\small Request} (3.7,-0.5);
  145. \draw[->] (3.7,-1.2) -- node[above]{\small Response} (0.3,-1.2);
  146. \end{tikzpicture}
  147. ```
  148. ````
  149. `stateDiagram-v2` → `automata` library:
  150. ````markdown
  151. ```{=latex}
  152. \begin{tikzpicture}[shorten >=1pt, node distance=3cm, on grid, auto,
  153. state/.style={circle, draw, minimum size=1.5cm}]
  154. \node [state, initial] (idle) {Idle};
  155. \node [state, right of=idle] (running) {Running};
  156. \node [state, accepting, right of=running] (done) {Done};
  157. \path[->] (idle) edge node {start} (running)
  158. (running) edge node {finish} (done);
  159. \end{tikzpicture}
  160. ```
  161. ````
  162. ### LaTeX Math
  163. For algorithms or formal descriptions:
  164. ```markdown
  165. The time complexity is $O(n \log n)$ due to the sorting step.
  166. $$
  167. f(x) = \sum_{i=0}^{n} a_i x^i
  168. $$
  169. ```
  170. ## Producing Output
  171. ### TANGLE (extract source code)
  172. ```bash
  173. bun run scripts/tangle.ts project.lit.md --output-dir ./src/
  174. ```
  175. This expands all root chunks and writes the source files. Verify by diffing against the original source.
  176. ### WEAVE (generate PDF)
  177. Before weaving, check whether `mermaid-filter` is available:
  178. ```bash
  179. which mermaid-filter
  180. ```
  181. **If present**, use the full command:
  182. ```bash
  183. pandoc project.lit.md \
  184. -o project.pdf \
  185. --pdf-engine=xelatex \
  186. --filter mermaid-filter \
  187. --toc \
  188. --number-sections \
  189. -V geometry:margin=1.5cm
  190. ```
  191. **If absent**, omit `--filter mermaid-filter` and convert any ` ```mermaid ` blocks to ` ```{=latex} ` TikZ blocks first (see TikZ section above):
  192. ```bash
  193. pandoc project.lit.md \
  194. -o project.pdf \
  195. --pdf-engine=xelatex \
  196. --toc \
  197. --number-sections \
  198. -V geometry:margin=1.5cm
  199. ```
  200. For setup instructions, see `references/pandoc-setup.md`.
  201. ## Quality Checklist
  202. After writing the `.lit.md`, verify:
  203. - [ ] **Tangle roundtrip**: `bun run scripts/tangle.ts --verify` reports all files as byte-for-byte matches
  204. - [ ] **No dangling references**: Every `<<chunk-name>>` resolves to a defined chunk
  205. - [ ] **No unused chunks**: Every defined chunk is referenced by a root chunk (directly or transitively)
  206. - [ ] **Every source file covered**: Each important source file has a corresponding root chunk with `file=`
  207. - [ ] **Prose precedes code**: No code block appears without motivating prose
  208. - [ ] **Diagrams render**: Mermaid diagrams produce correct output in the PDF
  209. - [ ] **Math renders**: LaTeX expressions compile without errors
  210. - [ ] **Narrative flows**: A reader unfamiliar with the codebase can follow the document start to finish
  211. ## Post-Creation Setup
  212. After creating the `.lit.md` and verifying the quality checklist, set up the reverse-sync hook so that edits to source files are automatically synced back into the `.lit.md`.
  213. ### 1. Configure the PostToolUse hook
  214. Create or update the target project's `.claude/settings.local.json` to include:
  215. ```json
  216. {
  217. "hooks": {
  218. "PostToolUse": [
  219. {
  220. "matcher": "Edit|Write",
  221. "command": "bun run <literate-programming-skill-path>/scripts/hook-reverse-sync.ts"
  222. }
  223. ]
  224. }
  225. }
  226. ```
  227. Replace `<literate-programming-skill-path>` with the absolute path to this skill's installation directory.
  228. ### 2. Inform the user
  229. After setup, tell the user:
  230. > The `.lit.md` is now the **single source of truth** for your codebase.
  231. >
  232. > - **Preferred workflow**: Make all changes in the `.lit.md` file, then tangle to regenerate source files.
  233. > - **If you edit a source file directly**: The reverse-sync hook will automatically update the `.lit.md` and re-tangle. This keeps everything consistent.
  234. > - **To regenerate the PDF**: Run `/literate-programming` again. Since the `.lit.md` already exists, it will just weave and tangle without recreating the document.
  235. >
  236. > The hook does NOT regenerate the PDF on every edit (too slow). PDF generation only happens when you explicitly run `/literate-programming`.
README.md · README · 86 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Literate Programming Skill for Claude Code
  2. A Claude Code skill that transforms codebases into literate programs. These are documents written for human comprehension that also generate the original source code.
  3. ## What is Literate Programming?
  4. Literate programming was invented by **Donald Knuth** in 1984. Knuth is the author of *The Art of Computer Programming*, creator of TeX, and winner of the 1974 Turing Award. He introduced literate programming as a paradigm where programs are written as essays for human readers, with code embedded in a narrative.
  5. A literate program produces two outputs:
  6. - **Weave**: Produce a readable document (PDF, HTML) with prose, diagrams, and syntax-highlighted code.
  7. - **Tangle**: Extract runnable source files from the document.
  8. The key insight: present code in *psychological order*. That is, the order that makes it easiest to understand, not the order the compiler needs.
  9. ## What This Skill Does
  10. - Installs as a Claude Code skill (via `SKILL.md`)
  11. - Gives Claude the ability to analyze a codebase and produce a `.lit.md` file
  12. - The `.lit.md` file weaves prose, Mermaid diagrams, LaTeX math, and syntax-highlighted code into a narrative
  13. - Includes a tangler (`scripts/tangle.ts`) that extracts source files back from the `.lit.md`
  14. - Includes a reverse-sync engine (`scripts/untangle.ts`) that updates the `.lit.md` when source files are edited directly
  15. - Includes a PostToolUse hook (`scripts/hook-reverse-sync.ts`) for automatic reverse-sync in Claude Code
  16. - Running `/literate-programming` on an existing `.lit.md` just weaves + tangles (idempotent)
  17. - Supports PDF generation via Pandoc
  18. ## Installation
  19. Copy `SKILL.md` into your project's `.claude/skills/` directory:
  20. ```bash
  21. git clone https://github.com/tlehman/litprog-skill.git
  22. mkdir -p your-project/.claude/skills/
  23. cp litprog-skill/SKILL.md your-project/.claude/skills/literate-programming.md
  24. ```
  25. Claude Code automatically discovers skills from `.claude/skills/` in your project root. After copying, the `/literate-programming` slash command will be available in any Claude Code session within that project.
  26. ## Usage
  27. ### Create a literate program
  28. Ask Claude to create a literate program from your codebase:
  29. > /literate-programming
  30. Claude will analyze your code, determine the best narrative order, and produce a `.lit.md` file with prose, diagrams, and named code chunks.
  31. If a `.lit.md` already exists, running `/literate-programming` will just tangle and weave the existing file without recreating it.
  32. ### Reverse-sync (automatic)
  33. After creation, a PostToolUse hook is configured so that when you edit a source file directly, the changes are automatically synced back into the `.lit.md` and re-tangled. This keeps the `.lit.md` as the single source of truth.
  34. The hook does NOT regenerate the PDF on every edit. To regenerate the PDF, run `/literate-programming` again.
  35. ### Tangle (extract source code)
  36. ```bash
  37. bun run scripts/tangle.ts project.lit.md --output-dir ./src/
  38. ```
  39. This expands all root chunks and writes the source files. Verify by diffing against the original source.
  40. ### Weave (generate PDF)
  41. ```bash
  42. pandoc project.lit.md \
  43. -o project.pdf \
  44. --pdf-engine=xelatex \
  45. --filter mermaid-filter \
  46. --toc \
  47. --number-sections
  48. ```
  49. **Prerequisites for weave:** pandoc, xelatex, mermaid-filter
  50. For setup instructions, see `references/pandoc-setup.md`.
  51. ## Why Use This?
  52. - **Optimized for reading**: Code is read far more often than it is written. Literate programs optimize for reading.
  53. - **Explains the why**: Forces the author to explain *why*, not just *what*. Every code block is preceded by prose that motivates its existence.
  54. - **Beautiful PDFs**: Produces documents with diagrams and math alongside code.
  55. - **Architectural clarity**: Reveals architectural decisions that comments and READMEs miss. The narrative structure shows how pieces fit together.
  56. - **Knowledge transfer**: Useful for onboarding, code reviews, and preserving institutional knowledge. A new team member can read the literate program start to finish and understand the system.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.