codebase-knowledge-builder

Category: Development & Coding | Uploader: OthmanAdi | Downloads: 0 | Version: v1.0（Latest）

Deep-dive into any codebase and produce structured knowledge artifacts that turn a coding agent into a codebase specialist. This skill should be used when the user asks to "study this repo", "understand this codebase", "document this project", "onboard me onto this code", "create codebase knowledge", "map this architecture", or when asked to produce knowledge artifacts for any agent working on an unfamiliar repository.

Changelog: Source: GitHub https://github.com/OthmanAdi/codebase-knowledge-builder

Directory Structure

Current level: skills/codebase-knowledge-builder/

📁 references/
- 📄 deep-dive-methodology.md 2.8 KB
- 📄 recon-checklist.md 1.6 KB
📁 templates/
- 📄 knowledge_artifact.md 1.5 KB
📄 SKILL.md 4.5 KB

SKILL.md

---
name: codebase-knowledge-builder
description: Deep-dive into any codebase and produce structured knowledge artifacts that turn a coding agent into a codebase specialist. This skill should be used when the user asks to "study this repo", "understand this codebase", "document this project", "onboard me onto this code", "create codebase knowledge", "map this architecture", or when asked to produce knowledge artifacts for any agent working on an unfamiliar repository.
version: 1.0.0
---

# Codebase Knowledge Builder

Transform from a generalist into a codebase specialist by systematically studying a repository and producing high-quality knowledge artifacts. The process follows a strict "read first, write later" principle across four sequential phases.

## Prerequisites

- File read access to the target repository (cloned locally or accessible via tools)
- Bash access for file counting and structure discovery
- Write access to produce scratch files and final artifacts

## Workflow

1. **Reconnaissance** -- Build a broad mental model of the entire repo
2. **Deep-Dive Study** -- Investigate each requested topic in isolation
3. **Artifact Authoring** -- Synthesize findings into polished knowledge artifacts
4. **Delivery** -- Package and deliver artifacts to the user

---

### Phase 1: Reconnaissance

Clone the repo and build a high-level map before touching any specific topic.

1. Run `find . -type f -name '*.js' -o -name '*.ts' -o -name '*.py' | head -50` and `wc -l` to gauge scale.
2. Read the main entry point file end-to-end.
3. Follow the checklist in `references/recon-checklist.md` to systematically discover architecture, entry points, config systems, and key abstractions.
4. Save a structured summary to a scratch file (`recon_findings.md`) with: tech stack, directory map, module responsibilities, design patterns, and open questions.

**Do not proceed to Phase 2 until the repo's architecture can be described in one paragraph.**

### Phase 2: Deep-Dive Study

For each topic the user requests, perform a focused investigation. Study each topic **separately** -- do not mix concerns.

1. Read `references/deep-dive-methodology.md` for file reading strategies, tracing patterns, and note-taking protocol.
2. Start from the subsystem's entry point and follow imports outward (dependency order, not alphabetical).
3. Trace three paths per subsystem: **happy path**, **error path**, **edge cases**.
4. After every 2-3 files, save key findings to a scratch file. Do not rely on context memory alone.
5. For each file, capture: purpose (one sentence), key functions, what it calls, what calls it, and gotchas.

### Phase 3: Artifact Authoring

Synthesize each topic's findings into a standalone knowledge artifact.

1. Copy the template from `templates/knowledge_artifact.md` for each topic.
2. Fill **every section** -- Overview, Architecture, Key Components table, Data & Control Flow, Key Functions table, Configuration table, Gotchas, Extension Points, and Visual Flow diagram.
3. Include Mermaid diagrams: use `sequenceDiagram` for flows, `graph TD` for architecture.
4. Each artifact must be self-contained -- a developer reading only that artifact should understand the subsystem completely.

### Phase 4: Delivery

Attach all completed Markdown artifacts to a message to the user. Include a brief summary of what each artifact covers.

---

## Limitations

- Large monorepos (>10,000 files) may require scoping to specific directories or packages before starting reconnaissance.
- Binary files, compiled assets, and vendored dependencies should be excluded from study.
- Knowledge artifacts reflect the codebase at a point in time. Major refactors may invalidate sections.

## Quality Checklist

Before delivering any artifact, verify:

| Check | Criteria |
| :--- | :--- |
| **Completeness** | Every template section is filled with codebase-specific detail, not placeholders. |
| **Accuracy** | File paths, function names, and parameter descriptions match the actual code. |
| **Gotchas** | At least 2-3 non-obvious behaviors, historical fixes, or race conditions documented. |
| **Visuals** | At least one Mermaid diagram per artifact. |
| **Self-contained** | A reader with no prior context can understand the subsystem from the artifact alone. |

## Bundled Resources

| Resource | Path | When to Read |
| :--- | :--- | :--- |
| Recon Checklist | `references/recon-checklist.md` | At the start of Phase 1 |
| Deep-Dive Methodology | `references/deep-dive-methodology.md` | At the start of each Phase 2 topic |
| Artifact Template | `templates/knowledge_artifact.md` | At the start of Phase 3 for each topic |

Comments 0

Latest | Hot

Please login before commenting.

No comments yet. Be the first one!

codebase-knowledge-builder

Directory Structure

SKILL.md

Report

Notice