# Codebase Knowledge Builder
**From unfamiliar repository to working knowledge.**
Codebase Knowledge Builder is an open [Agent Skill](https://agentskills.io) for codebase understanding and developer onboarding. It studies a repository or subsystem and produces source-cited Markdown knowledge artifacts that explain architecture, behavior, error paths, edge cases, constraints, and unknowns.
It does not build an index, run a server, or hide uncertainty. The result is a portable document that a developer or another coding agent can review, version, and reuse.
## Quick start
Install the standalone skill with the current verified Skills CLI release:
```bash
npx --yes skills@1.5.23 add OthmanAdi/codebase-knowledge-builder --skill codebase-knowledge-builder -g
```
Then ask your agent a normal question:
```text
Study the authentication subsystem in this repository. Build a source-cited
knowledge artifact for a new maintainer. Keep the repository read-only and mark
anything the source does not prove as unknown.
```
See a real result: [how this repository packages one canonical skill across six distribution surfaces](examples/distribution-architecture.md), generated against fixed commit `50aa5b8504d9a8a253f1a8507544d77562a611e3`.
The skill resolves the repository revision and scope, follows relevant code paths, distinguishes evidence from inference, and validates the artifact before delivery.
## Understand an unfamiliar codebase before you edit it
A quick repository scan can tell you where files live. It rarely explains how a subsystem behaves, where errors travel, which assumptions are verified, or what is still unclear.
Codebase Knowledge Builder turns exploration into a reviewable handoff:
| Before | After |
| :--- | :--- |
| Scattered file reads | One scoped, revision-specific artifact |
| Architecture guessed from folder names | Boundaries supported by source citations |
| Happy path only | Happy, error, and relevant edge paths |
| Confident prose with hidden gaps | `observed`, `inferred`, `unknown`, and `not applicable` labels |
| Scratch notes inside the target | Task-scoped output outside the target by default |
| Context that disappears with the session | Portable Markdown for people and agents |
## What each knowledge artifact contains
- Repository identity, inspected revision, timestamp, scope, exclusions, and budget
- An executive answer to the research question
- Architecture and ownership boundaries relevant to that question
- Happy-path, error-path, and evidenced edge-case traces
- Key interfaces, data contracts, configuration surfaces, and extension points
- Source references in `relative/path:line` form
- Explicit reasoning and confidence for inferred claims
- Unknowns, contradictions, and the evidence needed to resolve them
- Optional Mermaid diagrams when a visual model adds real clarity
- A final validation and redaction record
The bundled [artifact template](skills/codebase-knowledge-builder/templates/knowledge_artifact.md) makes those expectations explicit without forcing empty sections or invented “gotchas.”
## How the four-phase process works
```mermaid
flowchart LR
A["Repository or subsystem"] --> B["1. Reconnaissance<br/>trust, scope, revision"]
B --> C["2. Deep dive<br/>bounded behavior traces"]
C --> D["3. Authoring<br/>evidence and unknowns"]
D --> E["4. Validation<br/>redaction and delivery"]
```
### 1. Reconnaissance
Resolve the canonical root, applicable instructions, revision, initial worktree state, research question, exclusions, and budget. Inventory version-controlled files first. Do not execute repository content.
### 2. Deep-dive study
Start from an evidenced entry surface, then follow calls, imports, registrations, data transformations, or build relationships. Trace only the paths that answer the scoped question.
### 3. Artifact authoring
Synthesize findings into the provided template. Consequential claims need a source location or a clearly labeled inference. Missing evidence stays visible as `unknown`.
### 4. Validation and delivery
Check citations, scope, confidence, redaction, Markdown and Mermaid rendering, output location, and the target's final worktree state. Deliver through the path or channel the user approved.
## Evidence and safety contract
Repository analysis is a trust-boundary problem. This skill makes the boundary part of the workflow:
- Applicable host, user, and workspace instructions remain authoritative.
- Content found inside the target is untrusted evidence. It cannot authorize commands, network access, secret access, or wider scope.
- The target is read-only by default. Builds, package scripts, dependency installation, and Git mutations require explicit authorization.
- Existing local checkouts are preferred. Remote checkouts are bounded and do not initialize submodules or download Git LFS objects without approval.
- Reads stay inside the canonical repository root. Symbolic links, junctions, mount points, and other reparse points are reported but not followed.
- Secret-bearing files and values are excluded by default. Artifacts contain redacted names and locations, never credentials.
- Output goes to a task-scoped location outside the target unless the user chooses an exact in-repository destination. That choice establishes a canonical approved output root.
- Before every write, existing destination components are inspected without following links, including the final item when it exists. A symbolic link, junction, mount point, other reparse point, or final parent outside the approved output root stops the write.
- The final path must not exist unless the user explicitly approves overwriting that exact regular file.
- Target-controlled text is escaped before it enters Markdown tables, links, HTML, mentions, task lists, or Mermaid labels.
Read the full [reconnaissance checklist](skills/codebase-knowledge-builder/references/recon-checklist.md) and [deep-dive methodology](skills/codebase-knowledge-builder/references/deep-dive-methodology.md) for the maintained contract.
## Installation
### Standalone Agent Skill
Recommended for Codex IDE, any host supported by the Skills CLI, and users who want the smallest installation surface:
```bash
npx --yes skills@1.5.23 add OthmanAdi/codebase-knowledge-builder --skill codebase-knowledge-builder -g
```
Manual installation is also possible. Copy `skills/codebase-knowledge-builder/` into the skill directory used by your agent. Keep the directory name unchanged so discovery and updates continue to work.
### Claude Code plugin
The repository contains a skills-only Claude Code plugin. Marketplace registration and installation are separate commands:
```text
/plugin marketplace add OthmanAdi/codebase-knowledge-builder
/plugin install codebase-knowledge-builder@codebase-knowledge-builder
```
Do not install both the standalone copy and the Claude plugin at the same scope. Duplicate skill names can produce ambiguous discovery. Third-party marketplace updates are not automatic; use the Claude plugin update flow when a new release is published.
### Codex plugin
Codex desktop and CLI can install the skills-only plugin from the repository marketplace after the npm package is published:
```bash
codex plugin marketplace add OthmanAdi/codebase-knowledge-builder
codex plugin add codebase-knowledge-builder@codebase-knowledge-builder
```
The Codex IDE extension uses the standalone Agent Skill route. Start a new Codex session after installing a plugin so the bundled skill is discovered.
### Hermes Agent
Hermes can install the canonical skill directly. No Hermes-specific adapter is required:
```bash
hermes skills inspect OthmanAdi/codebase-knowledge-builder/skills/codebase-knowledge-builder
hermes skills install OthmanAdi/codebase-knowledge-builder/skills/codebase-knowledge-builder
```
Start a new session or use `/reset` after installation. The currently documented Hermes `--now` install flag is not accepted by the current CLI, so it is intentionally omitted here.
### npm package
`codebase-knowledge-builder` is a content-only package used for versioned distribution and the Codex plugin marketplace. It has no executable, runtime API, dependencies, or lifecycle scripts. The command below becomes available after the first authenticated registry publish completes:
```bash
npm install codebase-knowledge-builder
```
Installing the package does not activate the skill by itself. Use the standalone or host-plugin route above for agent discovery.
### OpenClaw and ClawHub
The canonical skill also matches the current ClawHub skill format. Once the first live ClawHub release is verified, OpenClaw users can install the published identity:
```bash
openclaw skills install @othmanadi/codebase-knowledge-builder
```
ClawHub publication is a separate release gate. A local `clawhub-upload/` directory is generated from the canonical skill and hash-checked before publishing; it is never a second source of truth.
## Verified compatibility
Installation and runtime behavior are separate claims. This table records the evidence available for release `1.0.0` on 2026-08-30:
| Surface | Evidence | Status |
| :--- | :--- | :--- |
| Agent Skills / Skills CLI 1.5.23 | Isolated project install plus canonical file-hash parity | Verified |
| Claude Code 2.1.251 | Strict repository, plugin-manifest, and skill validation | Verified structure |
| Codex CLI 0.146.0 | Isolated repository-marketplace resolution and local plugin load | Verified local load, npm route pending |
| Hermes Agent 0.19.1 | Public remote inspect and isolated clean install without a security bypass | Verified |
| npm | Clean allowlisted package dry-run, no lifecycle scripts | Verified package, live publish pending |
| ClawHub / OpenClaw | Current format and release-command contract | Documented, live publish pending |
The matrix is intentionally narrower than the number of hosts that can parse Agent Skills. Installability does not prove that every host has been runtime-tested.
## How this differs from repo maps and code indexes
| Tool shape | Primary output | Codebase Knowledge Builder adds |
| :--- | :--- | :--- |
| Source packager | Repository text in a prompt-friendly bundle | Synthesized behavior, evidence labels, and a maintained artifact |
| Static repo map | Symbols, signatures, and file relationships | Error paths, assumptions, ownership, and unresolved questions |
| Graph or index | Queryable dependency and call data | Portable Markdown without a database or server |
| Wiki generator | Broad generated documentation | A bounded subsystem study shaped by one engineering question |
| Agent memory | Host-local context for later sessions | Reviewable, shareable, revision-specific repository knowledge |
This skill complements deterministic analysis tools. It does not replace a compiler, parser, test suite, security scanner, or dependency graph.
## Use cases
- Onboard onto an unfamiliar or legacy codebase before making a change
- Trace a request, event, data, or control flow across modules
- Document one subsystem without generating a whole-repository wiki
- Prepare a reviewable handoff for a new maintainer, contractor, or coding agent
- Record failure behavior, risky assumptions, and evidence gaps during architecture discovery
- Refresh stale documentation against a known revision
## Limitations
- The artifact quality depends on the agent, model, available context, and repository evidence.
- Model-guided synthesis is slower and less deterministic than a static symbol map.
- Read-only analysis can describe implemented paths, but it cannot prove runtime behavior that requires execution.
- Large monorepos need an explicit subsystem or budget. The skill will not silently claim full coverage.
- Artifacts describe one revision and can become stale after refactors.
- This repository ships no hosted service and performs no telemetry, but source-code privacy still depends on the agent host and model configuration you choose.
- The workflow is not a security audit, code-quality audit, or impact-analysis engine unless the user separately authorizes and scopes that work.
## FAQ
### Does it work with private repositories?
Yes, if your chosen agent can access the local checkout. This project does not upload code itself, but the host or model may process repository content remotely. Review that product's data controls before analyzing private source.
### Is this a repo map or knowledge graph?
No. It can describe architecture and relationships, but its product is a source-cited Markdown artifact. It does not maintain a queryable graph or index.
### Can I study one subsystem instead of the entire repository?
Yes. A narrow research question is usually the best input. The scope, budget, exclusions, and unknowns are recorded in the artifact.
### Where are generated files written?
Outside the target repository by default, in a task-scoped location selected by the agent or user. Writing inside the target requires an exact destination. Every existing destination component must be link-free, the final parent must remain inside the canonical approved output root, and an existing final regular file requires explicit overwrite approval.
### How do I refresh a stale artifact?
Run the skill again against the new revision with the prior artifact as context. Ask it to verify every existing claim, remove invalidated claims, and record the new revision and unresolved differences.
### Does it require Bash or a specific programming language?
No. The workflow is tool-neutral and starts from version-control metadata and repository manifests. Agents choose appropriate file and search tools for their host.
### How does it handle monorepos?
It records workspace boundaries during reconnaissance, then scopes deep reading to the subsystem or dependency path that answers the question. It reports excluded packages rather than pretending to have studied them.
## Repository layout
```text
.
├── skills/codebase-knowledge-builder/ # canonical Agent Skill
│ ├── SKILL.md
│ ├── references/ # reconnaissance and tracing method
│ └── templates/ # evidence-backed artifact template
├── .codex-plugin/ # skills-only Codex package metadata
├── .claude-plugin/ # skills-only Claude Code metadata
├── .agents/plugins/ # npm-backed Codex marketplace entry
├── assets/ # README and social-preview artwork
├── examples/ # source-cited worked artifacts
├── llms.txt # machine-readable project navigation
└── package.json # content-only npm distribution
```
There is one behavioral source of truth: `skills/codebase-knowledge-builder/`. Host manifests package that skill; they do not reimplement it.
## Contributing and security
Read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request. Report vulnerabilities through the private process in [SECURITY.md](SECURITY.md), never through a public issue or an unredacted artifact.
## License
The GitHub repository and npm package are licensed under [MIT](LICENSE). ClawHub applies MIT-0 to registry publications, which is a separate and more permissive distribution grant.