{"id":51397212,"url":"https://github.com/x0c/doc-skills","last_synced_at":"2026-07-04T03:11:35.589Z","repository":{"id":366751347,"uuid":"1276497933","full_name":"x0c/doc-skills","owner":"x0c","description":"Claude Code skills to bootstrap, compact, and maintain AI-readable project documentation — doc-init · doc-compact · doc-update","archived":false,"fork":false,"pushed_at":"2026-07-02T08:30:02.000Z","size":213,"stargazers_count":21,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-07-02T10:22:54.593Z","etag":null,"topics":["ai","ai-agent","anthropic","claude","claude-code","claude-code-skills","coding-agent","developer-tools","documentation","knowledge-base","llm","python"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/x0c.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-22T03:16:45.000Z","updated_at":"2026-07-02T08:30:06.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/x0c/doc-skills","commit_stats":null,"previous_names":["x0c/doc-skills"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/x0c/doc-skills","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/x0c%2Fdoc-skills","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/x0c%2Fdoc-skills/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/x0c%2Fdoc-skills/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/x0c%2Fdoc-skills/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/x0c","download_url":"https://codeload.github.com/x0c/doc-skills/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/x0c%2Fdoc-skills/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35108447,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-04T02:00:05.987Z","response_time":113,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-agent","anthropic","claude","claude-code","claude-code-skills","coding-agent","developer-tools","documentation","knowledge-base","llm","python"],"created_at":"2026-07-04T03:11:35.038Z","updated_at":"2026-07-04T03:11:35.582Z","avatar_url":"https://github.com/x0c.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# doc-skills\n\n\u003e **Claude Code Skills** for bootstrapping, compacting, and maintaining AI-readable project documentation — so coding agents stop re-discovering the same project context every session.\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Claude Code](https://img.shields.io/badge/Claude%20Code-Skills-5A67D8?logo=anthropic\u0026logoColor=white)](https://claude.ai/code)\n[![Python 3.8+](https://img.shields.io/badge/Python-3.8+-3776AB?logo=python\u0026logoColor=white)](https://python.org)\n\n**Languages:** [English](#english) | [中文](#中文)\n\n---\n\n\u003ca id=\"english\"\u003e\u003c/a\u003e\n## English\n\n### Why this exists\n\nAI coding agents waste time (and make mistakes) re-discovering the same project context every session: which module owns what, which fields lie, which side effects aren't visible in the code. `doc-skills` turns that tribal knowledge into a small, navigable documentation system that any agent can pick up cold — and keeps it from rotting as the codebase changes.\n\n### Quick Install\n\n```bash\ngit clone https://github.com/x0c/doc-skills.git ~/.claude/skills/doc-skills\n\n# Or copy individual skill folders\ncp -r doc-skills/doc-init doc-skills/doc-compact doc-skills/doc-update ~/.claude/skills/\n```\n\nRestart Claude Code. Each skill's entry point is its `SKILL.md`.\n\n---\n\n### Skills\n\n#### `doc-init` — Documentation System Initialization\n\nBootstraps a full documentation system for a project from scratch. The overall design follows a two-phase approach: **fix the global AI instruction file first, then build the project documentation**.\n\n**Phase 1 — Global governance check**\n\nBefore touching any project files, `doc-init` detects the active global AI instruction files (`~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md`, etc.) and uses a versioned script (`insert_doc_governance.py`) to install or upgrade the doc-management standard. This ensures all future agents operate under consistent rules regardless of which project they're in.\n\n**Phase 2 — Project documentation initialization**\n\nThe core logic runs in a pipeline of steps designed to prevent the two failure modes of most doc-generation tools: *producing skeleton docs that don't capture real behavior*, and *building a doc system that rots the moment the code changes*.\n\nKey design decisions:\n\n- **Product truth before code topology.** The agent first establishes a \"product north star\" (from PRD, roadmap, or user input) before scanning the code. This prevents the common mistake of treating every directory as a \"domain\" and creating docs that describe code structure rather than business behavior.\n\n- **Multi-source evidence gathering.** Rather than only reading code, `doc-init` runs several specialized scripts in parallel: `project_inventory.py` (language stack, entry points, submodules), `depth_scanner.py` (state machines, concurrency patterns, idempotency signals, event flows), `git_history_miner.py` (hotspots, historical naming, fix/revert patterns), and optionally `db_miner.py` (table catalog, field semantics). Scripts collect mechanical facts; the model makes judgment calls about business boundaries.\n\n- **Human-in-the-loop at the domain map stage.** After scanning, the agent proposes a full domain map — \"domains\" in the business sense, not directory names — and asks the user to confirm or adjust before writing anything. This prevents silent misclassification of the entire project.\n\n- **Structured sub-agent prompts, not vague delegation.** When writing multiple domain knowledge bases in parallel, each sub-agent receives a structured prompt containing: domain definition, entry point list, depth scanner signals, canonical terminology, Q\u0026A results, and quality gates. Vague prompts produce skeleton docs; structured prompts produce usable ones.\n\n- **Coverage gate at completion.** `doc_coverage.py` computes a coverage score against a fingerprinted baseline (file count, language breakdown, submodule count, git SHA). A doc system that was 90% complete six months ago and hasn't been touched since the codebase doubled is not \"complete\" — it gets flagged as `STALE` and the gaps are surfaced for targeted updates.\n\n- **Iterative deepening, not one-shot generation.** After the initial pass, the skill proposes at least three directions to deepen (uncovered domains, low-confidence constraints, unverified mechanisms) and lets the user pick. Each direction runs in parallel where possible.\n\nUse when entering a project with no doc structure, or when the global instruction file lacks the documentation-management standard.\n\n---\n\n#### `doc-compact` — Documentation Compaction \u0026 Governance\n\nAudits and compresses project documentation without losing behavioral information. The central design principle: **the only valid reason to keep a sentence is that it changes a reader's action or judgment**.\n\n`doc-compact` runs a five-step pipeline:\n\n1. **Global governance check** — same as `doc-init` Phase 1; ensures the instruction file is current before restructuring anything.\n\n2. **Read-only audit** — `audit.sh` runs a battery of mechanical checks: CLAUDE.md single-line convention, dead links, orphan documents (files in `docs/` not reachable from root `AGENTS.md`), naming convention violations, and — crucially — detection of the `doc-init` domain map segment (which must be preserved untouched through all compaction).\n\n3. **Two-level index decision** — by default, documentation stays flat (everything reachable from root `AGENTS.md` in one hop). A second-level index is only introduced when the navigation section itself has grown large enough to crowd out the behavioral rules. Two independent triggers: scale-driven (navigation takes up ≥ half of `AGENTS.md`) and type-driven (≥ 3 troubleshooting records or review logs).\n\n4. **Structure repair** — fixes mechanical issues: CLAUDE.md back to single line, document naming to `SCREAMING_SNAKE_CASE` (knowledge bases) or `kebab-case` (design/review docs), navigation descriptions rewritten from \"what this file contains\" to \"when you should read this\", dead index entries removed.\n\n5. **Compression (the core step)** — every document in `docs/` is reviewed against a graded set of deletion criteria. Low-risk removals (paraphrase, dead links, historical changelog, duplicate reminders, line-number references that should be method-name anchors) are done directly. High-risk removals (entire files, paragraphs with numbers or boundary conditions, structural changes) are listed for confirmation first. A `\u003c!-- compressed YYYY-MM-DD --\u003e` marker is written to every processed file, which becomes a hard gate in the final audit: any file missing the marker means it was skipped.\n\nUse when docs are bloated, indexes break, `AGENTS.md` balloons past ~200 lines, or `CLAUDE.md` gets polluted with content.\n\n---\n\n#### `doc-update` — End-of-Session Documentation Debrief\n\nDistills reusable findings from a completed session into the right destination. The design centers on a single question: *if a brand-new agent came in right now and only read the existing docs — no session history — could it take over and do the work?*\n\n`doc-update` runs in four steps:\n\n1. **Skip check** — if the session was pure Q\u0026A, all findings already exist in docs, or the information is session-only, the skill exits cleanly. No-op is a valid outcome.\n\n2. **Extract reusable findings** — reviews the session for: new business rules or architectural constraints, bugs hit (root cause + fix), validated patterns, user corrections or preferences, code changes that invalidated existing docs, and (critically) any navigation failures — cases where an agent searched for a document and couldn't find it or found the wrong one. Navigation failures are the most actionable signal: they mean the index description is missing a task-type trigger.\n\n3. **Route to the right destination** — a decision tree maps finding types to target locations:\n   - Cross-project patterns / scripts / checklists → the relevant skill file\n   - Project-level behavioral constraints (mandatory flows, shutdown checklists, verification requirements) → root `AGENTS.md`\n   - Domain knowledge / business rules / architecture → `docs/\u003cDOMAIN\u003e_KNOWLEDGE_BASE.md`\n   - Design decisions → `docs/design/`\n   - Troubleshooting records → `docs/troubleshooting/YYYY-MM-DD-*.md`\n\n   For each touched document, the skill also checks the index entry: does the description cover the task type the agent actually used to find it? If the session surfaced a \"can't find the doc for X\" failure, that task type gets added to the description.\n\n4. **Conflict resolution** — if the session established or corrected a fact that contradicts existing docs, the skill updates all affected documents in the current session scope. It does not do a full-repo consistency sweep (that's `doc-compact`'s job); it only fixes what this session actually touched.\n\nUse at the end of any session where something worth persisting was discovered.\n\n---\n\n### How the three skills fit together\n\n```\nNew project, no docs\n        │\n        ▼\n   doc-init ──────────────────► AGENTS.md + docs/*.md (full domain map)\n        │                              │\n        │                    ongoing code changes\n        │                              │\n        ▼                              ▼\n each session ends              doc-update ──► incremental updates to docs/\n                                       │\n                               docs grow over time\n                                       │\n                                       ▼\n                               doc-compact ──► compress, rebuild index, fix structure\n```\n\n`doc-init` builds the foundation once (or after a major restructure). `doc-update` keeps it current session by session. `doc-compact` restores readability when the system has grown or degraded.\n\n---\n\n### Project structure\n\n```\ndoc-init/\n├── SKILL.md                        # skill entry point\n├── agents/                         # agent definitions (e.g. OpenAI-compatible)\n├── references/                     # design guides read by the model at runtime\n│   ├── human-intake.md             # how to run the user interview\n│   ├── knowledge-network-design.md # KB/Guide boundaries, naming, budget rules\n│   ├── scan-and-boundary-report.md # domain map format, coverage review\n│   ├── document-templates.md       # KB/Guide templates and quality gates\n│   ├── depth-patterns.md           # how to interpret depth_scanner signals\n│   ├── sub-agent-prompt-template.md\n│   ├── multi-source-evidence.md\n│   ├── conflict-resolution.md\n│   ├── git-history-mining.md\n│   ├── operations-validation.md\n│   ├── hidden-semantics/           # language-specific implicit behavior patterns\n│   │   ├── java-kotlin.md\n│   │   ├── python.md\n│   │   ├── go.md\n│   │   ├── javascript-typescript.md\n│   │   └── csharp-dotnet.md\n│   └── database-mining/            # DB catalog workflow and safety rules\n│       ├── workflow.md\n│       ├── critical-table-analysis.md\n│       ├── evidence-pack-format.md\n│       ├── config-discovery.md\n│       └── safety-and-sampling.md\n└── scripts/                        # deterministic fact-collection scripts\n    ├── project_inventory.py        # language stack, entry points, submodules\n    ├── depth_scanner.py            # state machines, concurrency, idempotency\n    ├── doc_coverage.py             # coverage gate (COMPLETE / STALE / NEEDS_INIT)\n    ├── doc_nav_lint.py             # navigation consistency check\n    ├── upsert_agents_nav.py        # idempotent AGENTS.md nav entry writer\n    ├── git_history_miner.py        # hotspots, fix/revert patterns\n    ├── db_miner.py                 # database catalog and field semantics\n    └── insert_doc_governance.py    # versioned global instruction file installer\n\ndoc-compact/\n├── SKILL.md\n├── references/\n│   ├── compression-guide.md        # compression criteria, risk grades, repair scripts\n│   └── standard.md                 # the eleven quality standards with full explanation\n└── scripts/\n    └── audit.sh                    # mechanical audit (dead links, naming, markers)\n\ndoc-update/\n└── SKILL.md\n```\n\n### License\n\nMIT\n\n---\n\n\u003ca id=\"中文\"\u003e\u003c/a\u003e\n## 中文\n\n### 为什么需要它\n\nAI Coding Agent 每次接手项目都要重新摸清同一套上下文——哪个模块归谁管、哪些字段名不能按字面理解、哪些副作用代码里根本看不出来。`doc-skills` 把这些经验沉淀成一套小而精、可导航的文档体系，让任何 Agent 接手都能直接开工，并随代码演进持续保鲜。\n\n### 快速安装\n\n```bash\ngit clone https://github.com/x0c/doc-skills.git ~/.claude/skills/doc-skills\n\n# 或只复制需要的 skill\ncp -r doc-skills/doc-init doc-skills/doc-compact doc-skills/doc-update ~/.claude/skills/\n```\n\n重启 Claude Code 即可，每个 skill 的入口是其 `SKILL.md`。\n\n---\n\n### Skills 说明\n\n#### `doc-init` — 项目文档体系初始化\n\n从零为项目搭建完整文档体系。整体设计遵循两阶段原则：**先修复全局 AI 指令文件，再初始化项目文档**。\n\n**阶段一 — 全局规范校验**\n\n在动项目文件之前，先探测生效中的全局 AI 指令文件（`~/.claude/CLAUDE.md`、`~/.codex/AGENTS.md` 等），用版本化脚本（`insert_doc_governance.py`）安装或升级文档管理规范。确保所有未来会话的 Agent 在一致的规则下运行。\n\n**阶段二 — 项目文档初始化**\n\n核心逻辑是一条防止两类典型失败的流水线：产出不反映真实行为的骨架文档，以及建好就烂、代码一变就失效。\n\n关键设计决策：\n\n- **产品真相先于代码拓扑。** Agent 在扫描代码前，先通过 PRD、路线图或用户输入确立\"产品北极星\"。防止把每个目录当成一个\"领域\"，产出描述代码结构而非业务行为的文档。\n\n- **多源证据采集。** 并行运行多个专项脚本：`project_inventory.py`（语言栈、入口点、子模块）、`depth_scanner.py`（状态机、并发模式、幂等信号、事件流）、`git_history_miner.py`（热点、历史命名、fix/revert 规律），以及可选的 `db_miner.py`（表目录、字段语义）。脚本负责采集机械事实，模型负责判断业务边界。\n\n- **领域地图阶段的人机交互门。** 扫描完成后，Agent 提出完整领域地图——业务概念维度的领域，不是目录名——并要求用户确认或调整，再开始写文档。\n\n- **结构化 sub-agent 提示词，不是模糊委托。** 并行生成多个领域知识库时，每个 sub-agent 收到结构化提示词：域定义 + 入口清单 + depth scanner 信号 + 主称谓 + Q\u0026A 结果 + 质量闸门。模糊提示词产出骨架，结构化提示词产出可用文档。\n\n- **完成时的覆盖度闸门。** `doc_coverage.py` 对带指纹的基线（文件数、语言分布、子模块数、git SHA）计算覆盖率，代码大幅增长而文档未更新时标记为 `STALE`，缺口被明确列出供定向更新。\n\n- **迭代深化，不是一次性生成。** 初始扫描后提议至少三个可深化方向，每个方向在条件允许时并行执行。\n\n适用场景：项目没有文档体系，或全局指令文件缺少文档管理规范时。\n\n---\n\n#### `doc-compact` — 文档整理与压缩\n\n在不丢失行为信息的前提下审计并压缩项目文档。核心原则：**保留一句话的唯一理由，是它会改变读者的判断或行动**。\n\n五步流水线：\n\n1. **全局规范校验** — 重整结构前先确认指令文件是最新版。\n2. **只读审计** — `audit.sh` 检查 CLAUDE.md 单行约定、死链、孤儿文档、命名规范，以及 `doc-init` 领域地图段（必须原样保留）。\n3. **二级索引判定** — 默认平铺，只有导航段膨胀到挤压行为规则时才引入二级索引。\n4. **结构修复** — CLAUDE.md 还原单行、文档命名规范化、导航描述改写为\"带着什么任务该读它\"。\n5. **压缩（核心步骤）** — 逐篇过删除判据，低风险直接删，高风险先列清单确认，每篇写入压缩标记作为硬闸门。\n\n适用场景：文档膨胀、索引失效、`AGENTS.md` 超过约 200 行、`CLAUDE.md` 被混入杂质内容时。\n\n---\n\n#### `doc-update` — 会话收尾文档复盘\n\n把可复用发现提炼到正确位置。核心问题：*如果全新 Agent 现在进来，只读现有文档、不看会话历史，能顺畅接手吗？*\n\n四步流程：\n\n1. **跳过判定** — 纯问答、发现已存在文档、或信息仅对当前会话有用，则干净退出。\n2. **提取可复用发现** — 新业务规则、踩过的坑、代码变动导致的文档失效，以及导航失败（找不到文档或找错文档）。\n3. **路由到正确位置** — 跨项目通用模式 → skill 文件；项目行为约束 → `AGENTS.md`；领域知识 → `docs/`。\n4. **修正冲突旧文档** — 在当次会话范围内更新所有与本次确立事实相矛盾的文档。\n\n适用场景：每次会话结束时，只要发现了值得沉淀的内容就运行。\n\n---\n\n### 三个 skill 的协作关系\n\n```\n新项目，无文档\n        │\n        ▼\n   doc-init ──────────────────► AGENTS.md + docs/*.md（完整领域地图）\n        │                              │\n        │                    日常代码迭代\n        │                              │\n        ▼                              ▼\n  每次会话结束              doc-update ──► 增量更新 docs/\n                                       │\n                               文档随时间增长\n                                       │\n                                       ▼\n                               doc-compact ──► 压缩、重建索引、修复结构\n```\n\n`doc-init` 一次性建立基础。`doc-update` 逐会话保持同步。`doc-compact` 在文档膨胀或失序后恢复可读性。\n\n---\n\n### 项目结构\n\n```\ndoc-init/\n├── SKILL.md                          # skill 入口\n├── agents/\n├── references/                       # 模型运行时读取的设计指南\n│   ├── human-intake.md               # 用户访谈流程\n│   ├── knowledge-network-design.md   # KB/Guide 边界、命名、预算规则\n│   ├── scan-and-boundary-report.md   # 领域地图格式、覆盖度复核\n│   ├── document-templates.md         # KB/Guide 模板和质量闸门\n│   ├── depth-patterns.md             # depth_scanner 信号解读\n│   ├── sub-agent-prompt-template.md\n│   ├── multi-source-evidence.md\n│   ├── conflict-resolution.md\n│   ├── git-history-mining.md\n│   ├── operations-validation.md\n│   ├── hidden-semantics/             # 各语言隐性行为模式\n│   └── database-mining/              # 数据库 catalog 工作流与安全规则\n└── scripts/                          # 确定性事实采集脚本\n    ├── project_inventory.py          # 语言栈、入口点、子模块\n    ├── depth_scanner.py              # 状态机、并发、幂等信号\n    ├── doc_coverage.py               # 覆盖度闸门\n    ├── doc_nav_lint.py               # 导航一致性检查\n    ├── upsert_agents_nav.py          # 幂等写入 AGENTS.md 导航条目\n    ├── git_history_miner.py          # 热点、fix/revert 规律\n    ├── db_miner.py                   # 数据库目录和字段语义\n    └── insert_doc_governance.py      # 版本化全局指令文件安装器\n\ndoc-compact/\n├── SKILL.md\n├── references/\n│   ├── compression-guide.md          # 压缩判据、风险分级、修复脚本\n│   └── standard.md                   # 十一条质量标准完整说明\n└── scripts/\n    └── audit.sh                      # 机械审计脚本\n\ndoc-update/\n└── SKILL.md\n```\n\n### License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fx0c%2Fdoc-skills","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fx0c%2Fdoc-skills","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fx0c%2Fdoc-skills/lists"}