Litprog Skill

Literate Programming Skill for Claude Code

A Claude Code skill that transforms codebases into literate programs. These are documents written for human comprehension that also generate the original source code.

What is Literate Programming?

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.

A literate program produces two outputs:

• Weave: Produce a readable document (PDF, HTML) with prose, diagrams, and syntax-highlighted code.
• Tangle: Extract runnable source files from the document.

The key insight: present code in *psychological order*. That is, the order that makes it easiest to understand, not the order the compiler needs.

What This Skill Does

• Installs as a Claude Code skill (via SKILL.md)
• Gives Claude the ability to analyze a codebase and produce a .lit.md file
• The .lit.md file weaves prose, Mermaid diagrams, LaTeX math, and syntax-highlighted code into a narrative
• Includes a tangler (scripts/tangle.ts) that extracts source files back from the .lit.md
• Includes a reverse-sync engine (scripts/untangle.ts) that updates the .lit.md when source files are edited directly
• Includes a PostToolUse hook (scripts/hook-reverse-sync.ts) for automatic reverse-sync in Claude Code
• Running /literate-programming on an existing .lit.md just weaves + tangles (idempotent)
• Supports PDF generation via Pandoc

Installation

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 co