Codebase Knowledge Builder

From unfamiliar repository to working knowledge.

Codebase Knowledge Builder is an open Agent Skill 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:

npx --yes [email protected] add OthmanAdi/codebase-knowledge-builder --skill codebase-knowledge-builder -g

Then ask your agent a normal question:

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, 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:

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 makes those expectations explicit without forcing empty sections or invented “gotchas.”

How the four-phase process works

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 and deep-dive methodology 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:

npx --yes [email protected] 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:

/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:

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:

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:

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:

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:

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

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

.
├── 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 before opening a pull request. Report vulnerabilities through the private process in SECURITY.md, never through a public issue or an unredacted artifact.

License

The GitHub repository and npm package are licensed under MIT. ClawHub applies MIT-0 to registry publications, which is a separate and more permissive distribution grant.