codebase-orient

codebase-orient is a reusable skill for Claude Code and Codex that gives the agent a repeatable way to inspect an unfamiliar repository before broad work.

Instead of asking the model to vaguely "understand the project", this skill tells it what to read first, what uncertainty to label, what hidden risks to surface, and what orientation artifacts to create or refresh. It is for developers who want better repo context before refactors, multi-file changes, handoffs, or work in an unfamiliar area.

Note

Installing a skill copies skill files into your tool's skill directory only. Running codebase-orient instructs the agent not to edit application code, refactor, or commit. In normal mode it may create or refresh docs/ai/CODEBASE_MAP.md, docs/ai/CHANGE_SURFACES.md, and docs/ai/OPEN_QUESTIONS.md. In dry-run mode it reports those proposed changes without writing them. On Claude Code project-local installs, an orientation pass may also add verified project-specific discovery paths to .claude/skills/codebase-orient/SKILL.md.

Quickstart

Most users want the reusable codebase-orient skill at the user level for the tool they already use.

Before running the install scripts, clone or download this repository locally and run the commands below from the repository root so scripts/ is present.

Have your coding agent install it

If you already work in Codex or Claude Code, a practical onboarding path is to give that coding agent this repository and ask it to install the reusable skill for the tool you are currently using.

Exact-install integrity rule for agent-delegated setup:

• The agent must first obtain an exact local copy of the requested repo revision by cloning/checking out the requested tag or by downloading and extracting that tagged archive.
• It must then run the checked-in installer script for the selected tool and install scope.
• It must not manually recreate, paste, summarize, paraphrase, or rewrite SKILL.md from web-fetched, rendered, transformed, or partial content.
• If it cannot obtain an exact local copy or cannot run the documented installer, it must stop and ask rather than approximate the installation.

Use this prompt:

Install the reusable codebase-orient skill for the coding tool we are using now. Follow this repository's README. Obtain an exact local copy of the requested repo revision first by cloning/checking out the requested tag or by downloading and extracting that tagged archive, then run the checked-in installer script. Do not manually recreate or rewrite SKILL.md from fetched or rendered content. Use the recommended user-level install path by default unless I request project-local scope; if I ask to install it "in this project," use the supported project-local route. If an installation already exists, do not overwrite or delete it automatically; explain the choices and ask me whether to do an overlay refresh, a clean reinstall, or a project-local install instead. If you cannot obtain an exact local copy or cannot run the documented installer, stop and ask. After installation, report how to invoke the installed skill explicitly. Do not run orientation in any target repository until I choose the target or ask you to do that next.

The manual commands below remain the inspectable install contract that the agent should follow.

If you use	Recommended install	What it changes
Claude Code	User-level codebase-orient	Copies the skill to ~/.claude/skills/codebase-orient/
Codex	User-level codebase-orient	Copies the skill to ~/.agents/skills/codebase-orient/
Claude Code, but you want a project-local skill generated inside each repo	User-level install-codebase-orient bootstrap skill	Installs a separate bootstrap skill at ~/.claude/skills/install-codebase-orient/

Install the reusable skill

If you want a project-local install instead, or the Claude Code bootstrap route, skip to Alternate install paths before running the default commands below.

If the install target already exists, stop and choose intentionally:

• Overlay refresh: rerun with -Force in PowerShell or --force in bash.
• Clean reinstall: delete the installed target first, then rerun without -Force or --force.
• Project-local install: use this when you intentionally want repo-scoped installation or testing.
• Agents acting on your behalf should ask before overwriting an existing installation.

Claude Code

.\scripts\install-user.ps1

macOS/Linux

bash ./scripts/install-user.sh

Codex

.\scripts\install-codex-user.ps1

macOS/Linux

bash ./scripts/install-codex-user.sh

First use

Keep these three steps separate:

• Installing the skill copies files into the tool's skill location.
• Invoking the installed skill is the next step.
• Running orientation in a target repo happens only after you explicitly invoke it there.

Reading an installed SKILL.md directly can confirm what was copied, but that is not the same as confirming the tool discovered or invoked the installed skill.

After installing, Codex should detect a newly installed or updated skill automatically. If codebase-orient does not appear, restart Codex.

Then invoke the skill explicitly:

Claude Code

/codebase-orient

Codex

In Codex CLI or the IDE extension, run `/skills` or type `$` to mention/select `codebase-orient`, then ask it to orient the repo. In the Codex app, the skill is also available, but this README does not assume the same picker interaction there unless Codex documentation says so.

What to expect after the first run

• The agent reads high-signal files first, then maps routes, entry points, services, schema, tests, deployment/config, and instruction files.
• The target repo may gain or refresh docs/ai/CODEBASE_MAP.md, docs/ai/CHANGE_SURFACES.md, and docs/ai/OPEN_QUESTIONS.md.
• Those docs/ai/ files are orientation aids, not the source of truth. Source code and project config stay authoritative.
• The skill should not edit source code, refactor, or commit during orientation.

Which install path applies to you?

Path	Use it when	Target
User-level codebase-orient	You want one reusable skill available across projects in the same tool	~/.claude/skills/codebase-orient/ or ~/.agents/skills/codebase-orient/
Project-local codebase-orient	You want the skill available only inside one repo	.claude/skills/codebase-orient/ or .agents/skills/codebase-orient/
User-level install-codebase-orient bootstrap skill	You use Claude Code and want a first-pass setup that generates a project-local Claude skill plus orientation docs in the target repo	~/.claude/skills/install-codebase-orient/

Alternate install paths

Project-local install for Claude Code or Codex

Run these from the target repo root. The scripts install relative to the current working directory and do not verify that it is a repository root.

For delegated installation from a GitHub URL or tag, first acquire the exact skill source separately, then run the checked-in project-local installer from the target repo root. Do not manually write .claude/skills/codebase-orient/SKILL.md or .agents/skills/codebase-orient/SKILL.md.

Claude Code project-local

& "PATH\TO\codebase-orient-skill\scripts\install-project.ps1"

bash /path/to/codebase-orient-skill/scripts/install-project.sh

This copies the skill into .claude/skills/codebase-orient/ in the current repo.

Codex project-local

& "PATH\TO\codebase-orient-skill\scripts\install-codex-project.ps1"

bash /path/to/codebase-orient-skill/scripts/install-codex-project.sh

This copies the skill into .agents/skills/codebase-orient/ in the current repo.

Claude Code bootstrap install: install-codebase-orient

This is a different skill from codebase-orient. Install it only if you specifically want Claude Code to generate a project-local .claude/skills/codebase-orient/SKILL.md inside each target repo.

.\scripts\install-bootstrap-user.ps1

bash ./scripts/install-bootstrap-user.sh

First use:

/install-codebase-orient

Expected result in the target repo:

• .claude/skills/codebase-orient/SKILL.md
• docs/ai/CODEBASE_MAP.md
• docs/ai/CHANGE_SURFACES.md
• docs/ai/OPEN_QUESTIONS.md

Repository evidence for the bootstrap skill also says it may append a minimal orientation pointer to an existing CLAUDE.md.

Codex does not have a bootstrap installer in this repo.

What the skill actually does

The canonical skill source is skills/codebase-orient/SKILL.md. Its job is to make repository orientation more deliberate and less guessy.

It tells the agent to:

• read project instructions and docs first;
• verify important claims against source instead of inheriting them blindly from README or instruction files;
• map important change surfaces such as routes, services, auth, schema, UI, tests, and deployment;
• create or refresh docs/ai/ orientation artifacts;
• label claims as Fact, Strong inference, Weak inference, or Unknown;
• report hidden risks such as stale docs, source-of-truth drift, generated-vs-source mismatches, and lifecycle traps.

It is meant for broad or unfamiliar work. It is explicitly meant to be skipped for tiny, known, single-file edits. The reusable canonical skill currently includes an explicit tuned framework-probe section for SvelteKit. Other frameworks currently use the generic discovery order unless later live-fire or eval evidence justifies a dedicated tuned probe section. The separate Claude Code bootstrap skill has its own bootstrap-specific discovery helpers and should not be treated as identical framework coverage.

Local behavioral evals

This repo now includes a small local/manual Codex eval scaffold for behavioral checks on codebase-orient.

• Prompt corpus: evals/codebase-orient-behavioral-cases.json
• Runner: scripts/run-behavioral-evals.ps1
• Default artifact location: ../codebase-orient-behavioral-eval-artifacts/

The PowerShell entrypoint is a thin wrapper over a dependency-free Node core, so maintainer use requires node to be available on PATH.

Run the validated one-case vertical slice:

powershell -ExecutionPolicy Bypass -File .\scripts\run-behavioral-evals.ps1 --case-id explicit-dry-run-unfamiliar

The current vertical slice executes one selected single case per invocation. explicit-dry-run-unfamiliar is the one fresh end-to-end case validated so far. The corpus also contains additional designed cases, including two-pass scenarios, that are not yet all executed or supported by the current vertical slice. No representative multi-case subset command is currently implemented.

The runner keeps disposable fixtures and raw traces outside the repository by default. It isolates the skill under test into a temporary USERPROFILE\.agents\skills\codebase-orient home so the eval uses the repo's current canonical skill content instead of a stale user-level install. The current vertical slice emits a structured evidence summary for maintainer review; it is not yet a representative multi-case or automatic pass/fail gate.

Observable limits are intentional and documented:

• codex exec --json provides deterministic filesystem and command-event evidence.
• The proven dry-run case ran under a read-only sandbox, so its no-write result deterministically proves no files were written during that constrained run only. It does not by itself prove voluntary no-write compliance under a writable sandbox.
• The local traces from this scaffold did not expose a dedicated skill-selected event type.
• Invocation and skip behavior are therefore reported as proxy evidence, not direct proof, based on the JSONL agent-message stream plus outcome traces.

Running it again later

Use the same invocation whenever docs/ai/ is missing, stale, or likely cheaper than rediscovering the repo from scratch.

Claude Code

/codebase-orient

Codex

In Codex CLI or the IDE extension, run `/skills` or type `$` to mention/select `codebase-orient`, then ask it to orient this repo before planning this change.

You can also ask for dry-run behavior:

Run codebase-orient in dry-run mode. Report proposed docs/ai changes before writing anything.

Outputs and authority boundaries

codebase-orient works with four distinct layers that should not be confused:

• skills/codebase-orient/SKILL.md in this repo is the canonical reusable skill source.
• skills/install-codebase-orient/SKILL.md is the separate Claude Code bootstrap skill source.
• A repo-local installed skill such as .claude/skills/codebase-orient/SKILL.md or .agents/skills/codebase-orient/SKILL.md is the local runtime copy.
• docs/ai/* files are refreshable orientation artifacts, not permanent source of truth.

That distinction matters because the generated docs/ai/ files can go stale, while source code and project config remain authoritative.

Important notes

Explicit invocation is the reliable path

The skill may be auto-invoked when the model recognizes an orientation request, but repository evidence is clear that auto-invocation is model-driven and not guaranteed. If you want the orientation pass, invoke it explicitly. Current Codex documentation says skills are available in the Codex CLI, IDE extension, and Codex app; Codex detects newly installed or updated skills automatically; if a skill does not appear, restart Codex; and in CLI/IDE the explicit invocation path is /skills or $.

Reinstall behavior

All install scripts refuse to overwrite an existing target unless you rerun them with -Force in PowerShell or --force in bash.

That overwrite is an overlay install:

• current source files are copied over the existing target;
• files that existed in an older install but were removed from the source package are not pruned automatically.

For a clean exact-sync reinstall, delete the target directory first and then run the install script without -Force or --force.

Codex lifecycle limits

This repo supports Codex user-level and project-local installs of the reusable codebase-orient skill.

Repository evidence does not support these two Claude Code bootstrap behaviors for Codex:

• the install-codebase-orient bootstrap skill;
• post-orientation project-local specialization of .claude/skills/codebase-orient/SKILL.md.

Claude Code project-local specialization

When a Claude Code project-local skill exists at .claude/skills/codebase-orient/SKILL.md, an orientation pass may extend it with verified project-specific discovery paths found during that pass. Only paths confirmed to exist and relevant to the project are added; canonical skill rules are not overwritten. Project-specific additions are kept visually separated at the end of the file. This is the only additional write that orientation may perform beyond the docs/ai/ files described above. In dry-run mode, proposed additions are reported but not written. Codex project-local installs do not use this behavior.

Project-local .gitignore snippets

If you install a project-local skill and want to track only the shared skill file, these are the patterns printed or documented by the repo.

Claude Code

.claude/*
!.claude/skills/
!.claude/skills/codebase-orient/
!.claude/skills/codebase-orient/SKILL.md

Codex

.agents/*
!.agents/skills/
!.agents/skills/codebase-orient/
!.agents/skills/codebase-orient/SKILL.md

Limitations and trust

• Explicit invocation is the reliable path. Auto-invocation is model-driven and not guaranteed in either Claude Code or Codex. If you need the orientation pass, invoke it explicitly.
• Orientation improves process, not correctness. The skill instructs the agent to label uncertainty and verify claims against source, but verify any claim that matters before acting on it.
• Large monorepos may need scoped orientation. Running against an entire monorepo can produce shallow results. Scope the invocation to the relevant package or area when needed.
• Skills are agent instructions. Review SKILL.md before installing third-party skills. This skill is designed to be conservative: no source edits, no refactors, no commits during orientation.

Reference and contributor notes

• skills/codebase-orient/SKILL.md: canonical reusable skill behavior
• skills/install-codebase-orient/SKILL.md: Claude Code bootstrap skill behavior and versioned embedded template
• CHANGELOG.md: release history
• docs/releases/v1.0-validation-record.md: frozen historical validation record for v1.0.0
• scripts/: install and validation helpers

Tracked repo-maintenance text in this repo follows an ASCII punctuation convention. The check scripts are:

.\scripts\check-ascii-punctuation.ps1

./scripts/check-ascii-punctuation.sh

Shared canonical/bootstrap rule blocks can also be validated directly with:

.\scripts\check-shared-rule-drift.ps1

Uninstall reference

Remove the installed skill directory that matches how you installed it:

Claude Code user-level: ~/.claude/skills/codebase-orient/
Claude Code project-local: .claude/skills/codebase-orient/
Codex user-level: ~/.agents/skills/codebase-orient/
Codex project-local: .agents/skills/codebase-orient/
Claude Code bootstrap user-level: ~/.claude/skills/install-codebase-orient/

License

MIT. See LICENSE.