# Litprog Skill

> 仓库地址：https://github.com/tlehman/litprog-skill
> 作者/组织：tlehman
> 成熟度：beta
> 分析日期：2026-04-15

## 一句话总结
将代码库转化为 literate programming 文档——用人类理解的叙事顺序组织代码，同时保持可执行性。

## 项目定位与架构
Litprog Skill 复兴了 Knuth 的 literate programming 理念，但用现代 agent skill 的形式落地。核心哲学是"code is read far more often than it is written"——文档优先于编译器需求。

技术上基于 `.lit.md` 文件格式，支持两个核心操作：**Weave**（生成 PDF/HTML 可读文档，含 prose、diagrams、highlighted code）和 **Tangle**（从文档中提取可运行的源文件）。reverse-sync engine 确保编辑源文件后文档自动更新，保持双向同步。

## 关键技术特性
- **Weave/Tangle 双操作**：一个 `.lit.md` 文件同时产出文档和源码
- **Reverse-sync Engine**：源文件变更自动反映到 literate 文档
- **Idempotent**：对已有 literate 文件运行 skill 只执行 weave/tangle，不重复创建
- **Rich Content**：支持 Mermaid diagrams、LaTeX 数学公式嵌入
- **Pandoc PDF Generation**：基于 Pandoc 生成高质量 PDF

## 设计亮点与创新
reverse-sync 是关键创新——传统 literate programming 的最大痛点是文档和代码脱节，双向同步机制解决了这个问题。与 AI agent 结合后，agent 可以按"心理顺序"重组代码呈现，降低知识传递成本。

## 局限性与风险
- 对 Pandoc 和 LaTeX 的依赖增加了环境配置复杂度
- Literate programming 本身是小众实践，团队采纳需要文化转变
- 适合文档密集型项目，对快速原型开发可能过重

## 与生态系统的关联
跨平台设计（Claude Code/OpenCode/Hermes 三端兼容）体现了 agentskills.io 标准的互操作性。为 Hermes 生态增加了**知识管理**维度。