# Orienting To Repo

> 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

- **Type:** Skill
- **Install:** `agentstack add skill-gg-mo-repo-hygiene-orienting-to-repo`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [gg-mo](https://agentstack.voostack.com/s/gg-mo)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [gg-mo](https://github.com/gg-mo)
- **Source:** https://github.com/gg-mo/repo-hygiene/tree/main/skills/orienting-to-repo
- **Website:** https://github.com/gg-mo/repo-hygiene

## Install

```sh
agentstack add skill-gg-mo-repo-hygiene-orienting-to-repo
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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.

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

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [gg-mo](https://github.com/gg-mo)
- **Source:** [gg-mo/repo-hygiene](https://github.com/gg-mo/repo-hygiene)
- **License:** MIT
- **Homepage:** https://github.com/gg-mo/repo-hygiene

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-gg-mo-repo-hygiene-orienting-to-repo
- Seller: https://agentstack.voostack.com/s/gg-mo
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.