Codebase Context

codebase-context is an Agent Skill for building a reliable repository model before feature work, debugging, refactoring, or review begins.

It gives downstream work better footing by turning an unfamiliar codebase into a compact context bundle: what the repository contains, where the likely entry points are, how the main parts connect, what the test surface looks like, and where the biggest unknowns or risks live.

What This Skill Is Responsible For

• Producing a Phase 0 repository understanding pass.
• Summarizing structure, entry points, dependencies, tests, and conventions.
• Separating observed facts from inference.
• Flagging uncertainty, blind spots, and likely risk areas.
• Providing a reusable handoff artifact for later engineering work.

What This Skill Is Not Responsible For

• Implementing features or fixes.
• Replacing deep debugging on a narrow bug.
• Acting as a full security-audit framework.
• Providing cross-agent shared memory infrastructure.

This boundary is intentional. The skill is designed to improve execution quality by improving context quality first.

Why Use It

Most engineering mistakes in unfamiliar repositories come from one of four failures:

• starting implementation before understanding ownership boundaries
• editing the wrong entry point or module
• assuming tests or CI cover more than they actually do
• introducing patterns that conflict with the repository's existing conventions

codebase-context addresses those failures with a structured read-first analysis pass.

Highlights

• Clear activation criteria for repo overviews and Phase 0 analysis work
• Stronger output contract with confidence and evidence expectations
• Progressive-disclosure support files for large or unusual repositories
• Example context bundle for maintainers and evaluators
• Eval scaffold for regression testing
• Lightweight validator for saved markdown bundles
• Pull-request CI validation for structure and benchmark regressions
• Packaged end-to-end fixtures for realistic repository analysis tests
• Deterministic benchmark harness for scoring generated bundles
• Contributor documentation and release notes for GitHub readiness

Standards Alignment

This repository follows the Agent Skills pattern of:

• a single SKILL.md runtime contract
• progressive disclosure through optional references/, assets/, examples/, evals/, and scripts/
• installability through the .agents/skills/<skill-name> directory convention

The skill is designed to remain portable across agent environments rather than depending on one private dispatcher or internal platform.

It is also explicitly aligned with dispatcher-style ecosystems that route by intent, artifact type, risk, and layer rather than by hardcoded skill names.

Dispatcher Alignment

codebase-context is now shaped to fit skill-dispatcher-style routing contracts directly.

Dispatcher-facing metadata in SKILL.md now declares:

• category: analysis
• layer: information
• accepted intents such as index_codebase and prepare_engineering_context
• input artifacts such as repo_path, workspace_context, and routing_request
• output artifacts such as repo_context and codebase_context_bundle
• low write risk and active lifecycle status

In a dispatcher-led pipeline, this skill is the Phase 0 step that should usually run before high-risk implementation or refactoring work.

Dispatcher Handoff Shape

When used from a router, the most useful handoff packet looks like:

intent: prepare_engineering_context
current_artifact_type: repo_path
target_artifact_type: repo_context
repo_context: none
constraints: read-only, concise, focus on entry points and tests
preferred_stack: repository-native
allowed_write_risk: low

The expected deliverable is a markdown context bundle that a downstream execution or review skill can consume without redoing the initial repository scan.

Installation

Install the folder into a skills directory that your agent scans:

• ~/.agents/skills/codebase-context
• <project>/.agents/skills/codebase-context

The skill name is codebase-context, so explicit invocations can use $codebase-context when the host agent supports named skill activation.

Repository Layout

codebase-context/
|-- assets/
|   `-- context-bundle-template.md
|-- evals/
|   `-- evals.json
|-- examples/
|   |-- fixture-bundles/
|   `-- sample-context-bundle.md
|-- fixtures/
|   |-- express-api/
|   |-- python-cli/
|   `-- ts-monorepo/
|-- references/
|   |-- analysis-playbook.md
|   `-- output-contract.md
|-- scripts/
|   |-- run_fixture_benchmark.py
|   |-- score_context_bundle.py
|   `-- validate_context_bundle.py
|-- .github/workflows/
|   `-- validate.yml
|-- benchmarks/
|   `-- README.md
|-- CHANGELOG.md
|-- CONTRIBUTING.md
|-- LICENSE
|-- README.md
`-- SKILL.md

How It Works

The runtime flow is intentionally simple:

1. Confirm the repository scope and whether the bundle should stay in-chat or be saved.
2. Scan the repo efficiently, skipping generated directories and irrelevant noise.
3. Detect the tech stack from manifests, lockfiles, configs, and representative source files.
4. Identify likely entry points, module boundaries, and public interfaces.
5. Estimate test shape and coverage confidence without inventing precision.
6. Capture conventions and likely risks.
7. Deliver the result as a markdown context bundle.

The default output shape lives in assets/context-bundle-template.md.

Output Contract

Every high-quality bundle should include:

• Executive Summary
• Tech Stack
• Structure
• Entry Points
• Dependencies
• Test Coverage
• Conventions
• Risks and Unknowns
• Recommended Next Steps

Good output is concise, evidence-aware, and honest about uncertainty. The deeper rules for this live in references/output-contract.md.

Memory Model

This skill intentionally uses a scoped memory model:

• Runtime memory holds the temporary repo understanding for the current task.
• Project-local persistent memory is optional and only applies when the user asks to save the context bundle.
• Shared memory is out of scope and should be handled by a separate capability if needed.

This prevents silent memory promotion and keeps repository analysis auditable.

Example Usage

Prompt:

Use $codebase-context on this repo before we refactor the auth flow. I want a concise context bundle covering structure, entry points, dependencies, tests, conventions, and the main risk areas.

Reference output:

• examples/sample-context-bundle.md

Evaluation Strategy

The repository now includes evals/evals.json with realistic prompts for:

• onboarding to an unfamiliar product repo
• analyzing a monorepo before migration work
• understanding a library before extension
• scoping risk before release stabilization

These evals are intentionally qualitative-first. For deterministic validation of a saved bundle's section structure, use:

python scripts/validate_context_bundle.py examples/sample-context-bundle.md

For fixture-based regression scoring, run:

python scripts/run_fixture_benchmark.py \
  --fixtures-dir fixtures \
  --bundles-dir examples/fixture-bundles

The benchmark harness is documented in benchmarks/README.md.

Optional Integrations

This skill can pair well with:

• a dispatcher that routes high-risk engineering tasks through a Phase 0 analysis step
• downstream implementation or review skills that consume the context bundle as handoff context
• project-local documentation workflows that persist the bundle to docs/ or a task workspace

These integrations are optional. They are not required for the skill to function.

CI and Regression Testing

This repository now includes GitHub Actions validation in .github/workflows/validate.yml.

On pull requests and pushes to main, CI:

• validates the example bundles against the required section schema
• runs the fixture benchmark harness
• fails if the benchmark average falls below the configured threshold

This keeps structural regressions and benchmark drift visible in routine maintenance work.

Fixture Repositories

The fixtures/ directory packages three compact repository shapes for end-to-end regression testing:

• express-api
• python-cli
• ts-monorepo

Each fixture includes source attribution in fixture.json, describing the public repository patterns it was modeled after. The fixtures are hand-authored and intentionally compact rather than full third-party mirrors.

Out of Scope

The following are conceptually related, but intentionally not implemented here:

• code graph indexing services
• persistent cross-project memory stores
• automated dependency visualization pipelines
• full LLM-run benchmarking infrastructure with human review loops

Keeping those concerns out of this repository keeps the skill focused, portable, and maintainable.

Contributing

See CONTRIBUTING.md for authoring guidance, validation steps, and release expectations.

License

MIT. See LICENSE.