From codebase-x-ray
A skill that deeply analyzes famous open-source codebases and generates a technical biography-style book. Use when studying the architecture/design philosophy of projects like Doom, Bitcoin, Redis, libuv, PostgreSQL. Trigger on requests such as "analyze ~~", "create a walkthrough for ~~", "write ~~ as an architecture book", "codebase analysis", "project walkthrough", "x-ray", "codebase x-ray". Analysis results are stored in a reusable artifact store for future use without re-analysis.
How this skill is triggered — by the user, by Claude, or both
Slash command
/codebase-x-ray:analyzeThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
A system that produces a **technical biography**-style book about the architecture/design of famous open-source projects.
A system that produces a technical biography-style book about the architecture/design of famous open-source projects.
Goal: "What problem did this system solve, with what philosophy, and what trade-offs did it accept?" Sub-goal: "What software engineering principles and patterns are at work in this code?"
This book does not merely explain code — it teaches software engineering through real code. Even in C code from 1993, GoF design patterns, SOLID principles, and architecture patterns are alive and well. After reading this book, the reader should be able to recognize "ah, so that's that pattern" in other codebases too.
Analysis and writing are completely separated. Analysis extracts facts; writing selects facts. Doing both at once lets narrative logic contaminate analytical completeness.
Hallucination is absolutely forbidden. Every claim carries a provenance tag. Analysis agents self-verify, and the Verifier performs a structural audit.
The Artifact Store is permanent. Once a project is analyzed, it is reused without re-analysis. The Writing Pipeline can be re-run at any time.
Actively seek discrepancies between official narrative and code. The points where design intent diverges from actual implementation make the most interesting chapters.
Output language follows the user's request language. If the user requests in Korean, output in Korean; English for English; Japanese for Japanese. Detected at initialization, recorded as output_language, and passed in the meta block of every sub-agent prompt. Code snippets, file paths, and technical terms (struct names, etc.) always remain in their original language.
The reader is a developer studying the code. They read on their phone during a commute. It must be easy and engaging. Code snippets require output_language comments. Use > **📌 ...**: ... inline callout boxes for terminology, analogies, modern-tech comparisons, and anecdotes. Short paragraphs, many subheadings.
Uncover software engineering patterns and principles from the code. Identify design patterns (GoF, etc.), architecture patterns, OO principles (SOLID, etc.), and system design principles in the code. Connect them using > **📐 Design Pattern**: ... callout boxes. Patterns operate regardless of language. The goal is to enable readers to "recognize this pattern in other codebases too."
Attach an inline tag to every claim. The Verifier rejects any claim without a tag.
[provenance:code_derived file:src/ae.c:L42] ← directly verified from code
[provenance:author_stated source:"URL or source"] ← author/official documentation
[provenance:synthesized] ← our interpretation/inference
code_derived must include a file path and line number.
The skill itself:
codebase-x-ray/skills/analyze/
├── SKILL.md ← this file (orchestrator)
└── references/
├── phase0-research.md ← Web research + Semantic anchor extraction
├── phase1-2-survey.md ← Directory survey + Boundary synthesis
├── phase3-deep-dive.md ← Module deep dive + Self-verify
├── phase4-6-writing.md ← Chapter design + Writing + Assembly
├── verifier.md ← Structural audit
├── chapter-template.md ← Chapter structure guide
└── artifact-format.md ← Artifact prose format + examples
Project directory created at runtime:
{project_root}/
├── manifest.md ← Progress state + project info (key to restarts)
├── source/ ← cloned repository
├── references/ ← downloaded materials from web research (papers, slides, images, etc.)
│ └── sources.md ← URL list + downloaded file mapping
├── checkpoints/
│ ├── phase0a.md
│ ├── phase0b.md
│ ├── phase1/{dirname}.md
│ ├── phase2.md
│ ├── phase4.md
│ ├── verify_phase3_pass1_{batch_num}.md
│ ├── verify_phase3_pass2.md
│ ├── verify_phase6_pass1_{batch_num}.md
│ └── verify_phase6_pass2.md
├── artifacts/
│ └── modules/{module}.md
└── output/
├── 00-prologue.md ← independent file per chapter
├── 01-{chapter}.md
├── 02-{chapter}.md
├── ...
├── build.sh ← chapter assembly + PDF conversion script
└── book.md ← output of build.sh
ANALYSIS PIPELINE
Phase 0a → Web Research
Phase 0b → Semantic Anchor Extraction
Phase 1 → Directory Survey (parallel Agents)
Phase 2 → Boundary Synthesis
Phase 3 → Module Deep Dive (parallel Agents) + Self-Verify
Verifier Pass 1 → Per-artifact audit (parallel batches)
Verifier Pass 2 → Cross-module audit (single Agent)
↓
ARTIFACT STORE (reusable)
↓
WRITING PIPELINE
Phase 4 → Chapter Design
Phase 5 → Per-Chapter Writing (parallel Agents)
Phase 6 → Cross-chapter Review → Final Book
Verifier Pass 1 → Per-chapter audit (parallel batches)
Verifier Pass 2 → Cross-chapter audit (single Agent)
This section provides step-by-step instructions for the main Claude Code session to follow. Execute each step in order.
The user provides a project_name (e.g., redis, doom, sqlite). Extract it from their request.
Ask the user for a project root path — a single directory where everything will live.
Example: ~/research/redis, /tmp/doom-study
Detect output_language: Detect the language of the user's request. "DOOM 분석해줘" → Korean, "analyze DOOM" → English. Record in manifest.md and pass in the meta block of every sub-agent prompt.
Check if {project_root}/manifest.md exists:
Create the project directory structure:
{project_root}/
├── source/ ← repo will be cloned here
├── references/ ← downloaded materials from web research
├── checkpoints/
│ └── phase1/
├── artifacts/
│ └── modules/
└── output/
Clone the repository into {project_root}/source/:
https://github.com/redis/redishttps://github.com/id-Software/DOOMhttps://github.com/sqlite/sqlitehttps://github.com/libuv/libuvhttps://github.com/bitcoin/bitcoinCreate manifest.md:
# Codebase X-Ray: {project_name}
- project: {project_name}
- language: {output_language}
- repo: {project_root}/source
- project_root: {project_root}
- started: {current date/time}
## Progress
Path convention: Throughout the pipeline, paths are relative to {project_root}:
source/ → the cloned repo (used as repo in all sub-agent prompts)checkpoints/ → phase checkpoint filesartifacts/modules/ → module deep dive artifactsoutput/ → chapter files, build.sh, book.mdreferences/phase0-research.md from this skill.{project_root}/checkpoints/phase0a.md.- Phase 0a: completereferences/phase0-research.md.checkpoints/phase0a.md.checkpoints/phase0b.md.ls or Glob).
.git, .github, .vscode, node_modules, vendor, build, dist, and other non-source directoriesreferences/phase1-2-survey.md.checkpoints/phase0b.md.checkpoints/phase1/{dirname}.md.checkpoints/phase1/.references/phase1-2-survey.md.checkpoints/phase0b.md.checkpoints/phase2.md.The main session performs this step directly. No sub-agent needed.
checkpoints/phase2.md.- Modules: [module1], [module2], [module3], ...
references/phase3-deep-dive.md and references/artifact-format.md.checkpoints/phase0a.md (web research — author statements/design decisions).checkpoints/phase0b.md.artifacts/modules/{module_safe_name}.md.Read references/verifier.md.
Pass 1 — Per-Artifact Audit (parallel batches):
ceil(total_artifacts / 4) batches.checkpoints/verify_phase3_pass1_{batch_num}.md.- Verify Phase 3 Pass 1: completePass 2 — Cross-Module Audit (single agent):
checkpoints/verify_phase3_pass2.md.- Verify Phase 3 Pass 2: completereferences/phase4-6-writing.md.checkpoints/phase0b.md.checkpoints/phase4.md.The main session performs this step directly.
checkpoints/phase4.md.- Chapters: [chapter1 title], [chapter2 title], ...
references/phase4-6-writing.md and references/chapter-template.md.checkpoints/phase0b.md.checkpoints/phase4.md (chapter plan + order).output/{NN}-{chapter_safe_name}.md.Phase 6 is editing, not assembly. Physical assembly is handled by build.sh.
references/phase4-6-writing.md.output/ + checkpoints/phase4.md path + worldview + meta blockoutput/book.md.The main session generates output/build.sh during Phase 6:
#!/usr/bin/env bash
set -euo pipefail
cd "$(dirname "${BASH_SOURCE[0]}")"
# Assemble chapter files in numerical order
cat [0-9][0-9]-*.md > book.md
echo "book.md generated: $(wc -w < book.md) words"
# PDF conversion (if pandoc is available)
if command -v pandoc &>/dev/null; then
pandoc book.md \
-o book.pdf \
--pdf-engine=xelatex \
--toc \
--toc-depth=3 \
-V geometry:margin=1in \
-V fontsize=11pt \
-V mainfont="Noto Sans" \
2>/dev/null && echo "book.pdf generated" \
|| echo "WARNING: PDF conversion failed. book.md is fine."
else
echo "pandoc not found. Only book.md was generated."
fi
Read references/verifier.md.
Pass 1 — Per-Chapter Audit (parallel batches):
ceil(total_chapters / 4) batches.checkpoints/verify_phase6_pass1_{batch_num}.md.- Verify Phase 6 Pass 1: completePass 2 — Cross-Chapter Audit (single agent):
checkpoints/verify_phase6_pass2.md.- Verify Phase 6 Pass 2: completeRecord "COMPLETE" in manifest.md.
Notify the user of completion and ask if PDF conversion is needed.
All sub-agent prompts are composed of 3 blocks:
From Phase 0b onward, always include the worldview paragraph first. This is the shared foundational understanding for all agents.
## Context
### Worldview of This System
{worldview paragraph from checkpoints/phase0b.md}
### Prior Results
{previous results needed for this phase}
### Target
{directory/module/chapter this agent will analyze}
### Project Info
- project: {name}
- repo: {path}
Include the relevant section from the references/ file verbatim. Do not summarize.
## Instructions
{full content of references/phase3-deep-dive.md}
## Meta
- Write all output in {output_language}. Keep code snippets and file paths in their original form.
- Include provenance tags in all output.
- Write results to {absolute path of output file}. Return only a completion summary to the main session.
- {If Phase 3} Perform self-verify after analysis is complete.
All sub-agents Write results directly to the designated file and return only a completion summary to the main session.
Rationale: If a Phase 3 artifact is 5,000 words and a chapter is 3,000 words, returning all results to the main session wastes the context window unnecessarily. When sub-agents write files directly, the main session only needs to track "which files are complete."
Similarly, large inputs (full artifact lists, etc.) are not embedded directly in the prompt — instead, provide file paths so the sub-agent can Read them directly.
manifest.md contains all progress state. When restarting after a session interruption:
{project_root}/manifest.md.Phases 1, 3, and 5 run multiple agents in parallel. If only some completed:
checkpoints/phase1/ with the repo's directory list. Re-run only the missing ones.artifacts/modules/ with the module list in manifest.md. Re-run only the missing ones.[0-9][0-9]-*.md file list in output/ with the chapter list in manifest.md. Re-run only the missing ones.verify_phase{N}_pass1_*.md files exist in checkpoints/. Re-run only the missing batches.verify_phase{N}_pass2.md does not exist but all Pass 1 files are present, run Pass 2 only.If the user wants to re-run only the Writing Pipeline (e.g., "I want to restructure chapters and rewrite"):
checkpoints/phase4.md, checkpoints/verify_phase6_pass1_*.md, checkpoints/verify_phase6_pass2.md, and all files under output/.The Artifact Store (artifacts/modules/) is preserved, so no re-analysis is needed.
Each Phase 3 sub-agent performs this directly after completing analysis:
code_derived claimThis is included in the sub-agent prompt's instructions block (references/phase3-deep-dive.md).
Performed by separate Verifier agents in two passes. Runs twice in the pipeline:
Each run consists of:
See references/verifier.md for detailed Verifier instructions.
Phases where the Verifier does not run:
Specific analysis/writing instructions for each phase are in the references/ files.
references/ is located under the same directory as this skill's SKILL.md:
| Phase | File | Content |
|---|---|---|
| 0a, 0b | references/phase0-research.md | Web research, Semantic anchor extraction |
| 1, 2 | references/phase1-2-survey.md | Directory survey, Boundary synthesis |
| 3 | references/phase3-deep-dive.md | Module deep dive + Self-verify |
| 4, 5, 6 | references/phase4-6-writing.md | Chapter design, writing, review |
| Audit | references/verifier.md | Structural audit |
| Phase 5 | references/chapter-template.md | Chapter internal structure |
| Phase 3 | references/artifact-format.md | Artifact prose format |
Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.
npx claudepluginhub workingdanny911/codebase-x-ray --plugin codebase-x-ray