orient-in-codebase
/orient-in-codebase
Learn an unfamiliar repository before changing it, including its real build and test commands, conventions and current health. Use this at the start of work in any repository you have not read in this session, or whenever you do not yet know how to run its tests, even if the task looks small.
- Author
- yaohuangguan ↗
- Repository
- agent-playbook ↗
- Licence
- MIT
- Last repository change
- 07.11.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 07.11.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Learn an unfamiliar repository before changing it, including its real build and test commands, conventions and current health. Use this at the start of work in any repository you have not read in this session, or whenever you do not yet know how to run its tests, even if the task looks small.
Original author description
Learn an unfamiliar repository before changing it, including its real build and test commands, conventions and current health. Use this at the start of work in any repository you have not read in this session, or whenever you do not yet know how to run its tests, even if the task looks small.
How it works
- When to use
- Steps
- Stop and ask when
- Common mistakes
- Report
SKILL.md preview
--- name: orient-in-codebase description: Learn an unfamiliar repository before changing it, including its real build and test commands, conventions and current health. Use this at the start of work in any repository you have not read in this session, or whenever you do not yet know how to run its tests, even if the task looks small. --- # Orient in a codebase Most bad changes start with a wrong assumption about the repository. A few minutes here prevents guessed commands, duplicated helpers and confusion over failures that already existed. ## When to use - First task in a repository, or in an area you have not read. - You do not know how tests run, or which branch is current. Skip this if you already did it for this area in the current session. ## Steps 1. **Check where you are.** Run these and read the output: ```bash git status --short --branch git fetch origin git log --oneline -5 ``` If the branch is behind the default branch, note it. A search on a stale branch can miss code that exists. 2. **Read the project's instructions.** Look for `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `CONTRIBUTING.md` and `README.md`. They override your habits. 3. **Identify the stack from its manifest files.** | File | Stack | Look for commands in | | --- | --- | --- | | `package.json` | JavaScript or TypeScript | `scripts` | | `pyproject.toml`, `requirements.txt` | Python | `[tool.*]`, `tox.ini`, `Makefile` | | `go.mod` | Go | `Makefile`, `go test ./...` | | `Cargo.toml` | Rust | `cargo test` | | `pom.xml`, `build.gradle` | Java or Kotlin | `mvn test`, `./gradlew test` | | `*.csproj`, `*.sln` | .NET | `dotnet test` | | `Gemfile` | Ruby | `Rakefile`, `bin/rspec` | | `composer.json` | PHP | `scripts` | 4. **Find the commands CI runs.** Read `.github/workflows/`, `.gitlab-ci.yml` or the equivalent. CI is the real definition of passing, and docs are often out of date. Note the commands for tests, lint, type checks and build. 5. **Record a baseline.** Run the tests for the area you will change, before you change anything. Write down what fails now. Without this, you cannot tell whether you caused a failure. 6. **Find the code path.** Search for a word from the task, such as a route, an error message or a UI label. Follow it from the entry point to storage. Read callers as well as the function itself. 7. **Find the nearest example.** Open the closest similar feature and its test. Copy their naming, structure, helpers and error handling. ## Stop and ask when - The task description does not match what the code does. - The baseline is broken in a way that blocks your work. - You cannot find how to run the tests after checking the manifest and CI. ## Common mistakes | Tempting move | Why it fails | Do this instead | | --- | --- | --- | | Guess `npm test` or `pytest` | The real command may differ or do less | Read the manifest and CI | | Trust the README alone | It may be out of date | Confirm with CI config and by running it | | Skip the baseline | Old failures look like yours | Run the tests first | | Write a new helper | One probably exists | Search before you write | | Say something does not exist after one search | The name may differ or the branch may be stale | Fetch, try other terms, then state what you searched | ## Report ```markdown Branch: <name>, <ahead/behind default branch> Stack: <languages and frameworks> Commands: test `<cmd>`, lint `<cmd>`, types `<cmd>`, build `<cmd>` Baseline: <what passes, what already fails> Code path: <entry point> -> <main files> Pattern to follow: <nearest similar file> ```
Versions
The database has no other skills named orient-in-codebase.
Database snapshot: 13.11.2026 · package version aee069d0440d (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 90codebase-recon
Understand an unfamiliar repository before making changes. Use when the task touches code whose architecture, conventions, or test setup are not already clear. - 100repo-recon
Use this skill when you need to map an unfamiliar codebase before changing anything. Runs a systematic five-step recon pass — read the map, learn the commands, trace one flow end-to-end, note conventions then match them, and write it down — so you understand architecture,… - 100codebase-onboarding
Maps an unfamiliar repository before changing it - stack, build/test/run commands, entry points, data flow, conventions and how changes ship - and writes a short map. Use when starting work in a repo you have not seen, when asked to explain how a codebase works, onboard to a… - 100explore-before-editing
Build a working map of an unfamiliar codebase before changing it: entry points, layers, conventions, build and test commands, where the change belongs, and what could break. Use when starting work in a repository or module you have not touched yet, when a change request names… - 100workflow-onboard
First-contact orientation for an unfamiliar codebase. Use when "I'm new to this repo", "orient me", "explain this codebase", "what does this do?", "onboard me", "first day on this project", or "catch me up on the codebase". - 100orient
Orient a developer to an unfamiliar codebase by systematically exploring its structure, purpose, features, conventions, and workflows. Produces a concise orientation document. Use when the user says "orient me", "what does this project do", "walk me through this codebase", "help…