Orienting to repo

Skill gg-mo/repo-hygiene/skills/orienting-to-repo

Hygiene skills for Claude Code, Codex, Cursor, OpenCode, Gemini, and Copilot — orient, docstring, test, gate commits

Install

npx -y skills add gg-mo/repo-hygiene --skill orienting-to-repo

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

2 stars2 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Use when starting substantive work in an unfamiliar repo, before diving into task-specific grep or edits — especially when the task touches business logic, public API, build, or infra, or you don't yet know the repo's purpose, stack, conventions, or layout

SKILL.md

3.6 KB, as published. Nobody here has run it

Orienting to a Repo

Overview

Before substantive work in a repo you don't already understand, build a brief mental model. Jumping to task-specific grep is a trap: you find symbol X without learning that symbol X is one of three competing implementations and the project is mid-migration. Five minutes of orientation prevents an hour of wrong-direction work.

Core principle: Understand what the repo IS before you change it.

When to Use

First substantive change in a repo you haven't worked in this session
After a /clear or /compact in a repo
Task touches business logic, public API, build config, or CI

When NOT to Use

One-line typo fix
Renaming a single local variable
Already oriented in this session (rely on conversation context)
User explicitly says "skip orientation"

The Orientation Pass

Run these in parallel where possible. Time-box to ~5 minutes, not 30.

Purpose — Read README.md (intro + setup section). What does this repo DO?
Stack — Read package.json / pyproject.toml / go.mod / Gemfile / Cargo.toml. Language, framework, key deps.
Layout — ls the root and 1-2 levels into the main source dir. Note convention: src/, lib/, app/, pkg/, etc.
Conventions — Look for CLAUDE.md, AGENTS.md, CONTRIBUTING.md, .editorconfig, linter configs. These are the rules.
Tests — Where do they live? What runner? Read one test file to see the style.
CI / build — Skim .github/workflows/ or equivalent. What's enforced before merge?
Entry point — Find and read the main entry file (top of main.py, index.ts, cmd/<name>/main.go).

Capture the Model — Briefly

After the pass, write a short scratch summary (3-5 bullets) in your reply to the user. Cover:

Purpose (one sentence)
Stack
Where the relevant code for the current task lives
Conventions to follow (linter, test framework, doc style)
Any "watch out for X" you noticed (active migration, deprecated dir, etc.)

Do NOT create a REPO_MAP.md file or any persistent artifact. The map goes stale instantly and lies to future sessions. Keep the model in conversation context only.

Quick Reference

Look for	To learn
README.md	Purpose, install, basic usage
CONTRIBUTING.md / CLAUDE.md / AGENTS.md	Project-specific rules
package metadata file	Language + dependencies
.github/workflows or .gitlab-ci.yml	What CI enforces
Existing test file	Test framework + style
`git log -20 --oneline`	What's active right now

Common Mistakes

Mistake	Fix
Jumping straight to `grep "<task-symbol>"`	Run the orientation pass first
Reading every file under `src/`	Read the entry point, then trace from there
Skipping CI config	Skipped CI = surprised by failed build on PR
Producing a REPO_MAP.md artifact	Don't. Keep the model in chat context.
Spending 30+ minutes orienting	You're over-investing. Time-box ~5 min.

Red Flags — STOP and Orient

About to grep for a task-specific symbol in a repo you haven't read the README of
About to edit a file in a stack you haven't confirmed (TS vs JS, Python 2 vs 3, etc.)
"I'll figure out the conventions as I go" — no, find them now
"The user wants this fast" — fast and wrong is slower than oriented and right