Skip to content
Skills Library
Programming · Research

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.

Licence
MIT
Last repository change
07.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 07.11.2026, without references to retired models or APIs.

Licence

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

  1. When to use
  2. Steps
  3. Stop and ask when
  4. Common mistakes
  5. Report
Original SKILL.md headings · 85 lines, 580 words
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…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.