SkillFoxx

Repo Atlas skill

A skill that builds ten structured documents under docs/atlas, so an agent or engineer finds repository context fast.

  • 58 ★ on the repository
  • Last commit
  • MIT
Skill

Extended access

Why this level

  • The skill runs a script and writes files into the repository, including `CLAUDE.md` and build targets.
All reasons and checks

cathrynlavery/repo-atlasAuthor:Cathryn Lavery

Install

In your terminal, with SkillFoxx CLI

npx skillfoxx add skills/repo-atlas

Detects the agents on your machine, shows the access level and pins the version.

Other ways to install

Access and checks

How we review

Extended accessThe tool runs code or makes network calls and only reads external data.

  • The skill runs a script and writes files into the repository, including `CLAUDE.md` and build targets.

This is third-party code. Review the repository files before installing.

What it does

The `/repo-atlas` command starts a seven-phase workflow. A Python script first builds a repository map: directory tree, entrypoints, file statistics and a changelog. The skill then walks the author through templates for architecture, domain model, critical flows, state sources, gotchas and tests. A short two-role instruction (one agent plans, another verifies) is added to `CLAUDE.md`. For CI the skill creates `make atlas-generate` and `make atlas-check` targets. The result lives in `docs/atlas` and any agent can read it without searching the whole codebase.

Who it is for. Teams and solo developers who bring agents into a large repository and are tired of re-explaining the project in every session.

Good fit when

  • A new developer or agent enters an unfamiliar repository and looks for entrypoints.
  • Architecture lives only in people's heads and needs to be written down next to the code.
  • CI should fail when the repository map goes stale: `make atlas-check` covers that.
  • A second agent reviews the first one's work and takes context from ready documents.

Not a fit when

  • The repository has a couple of files and a map adds nothing.
  • Nobody wants to maintain documents and refresh them with changes.
  • You need user-facing product docs rather than developer context.

Example request

Map this repo and write up the architecture, critical flows and gotchas.

Limitations

The skill targets Claude Code: the `/repo-atlas` command and the `CLAUDE.md` edits depend on it. The generator runs on Python 3.7 or newer with no third-party packages, but the author writes the architecture sections by following the skill's prompts; they are not filled in automatically. Documents go stale along with the code, so enable `make atlas-check` in CI. The skill creates files in `docs/atlas`, extends `CLAUDE.md` and edits build targets, so commit your working state before running it.

How to disable. Delete the skill folder from your skills directory and, if you no longer want the documents, remove `docs/atlas`, the block in `CLAUDE.md` and the make targets.

FAQ

What appears in the project after a run?

A `docs/atlas` folder with ten documents, an agent block in `CLAUDE.md`, and `make atlas-generate` and `make atlas-check` targets.

Which languages and build systems does the script recognise?

Languages include Python, JavaScript, TypeScript, Go, Rust, Swift, Java, Kotlin, C, C++, C#, PHP, Elixir and Dart. Build systems named include npm, Cargo, Go modules, Gradle, Maven, SPM, CMake and Bazel.

How do I install the skill?

Clone the repository and copy the `repo-atlas` folder to `~/.agents/skills/repo-atlas`. Copying the folder by hand also works.

Why are there two agent roles?

One agent writes the plan and the other verifies the result. The instruction goes into `CLAUDE.md`, and both read context from the atlas.

Can the atlas get a second opinion?

Yes, the author recommends pairing it with a separate Codex skill that reviews the documents for accuracy and gaps.

Discussion

No questions or reviews yet.

Skills

A Claude Code working configuration: a planner with per-milestone review, sub-agents and skills for analysis, refactoring and docs sync

SkillExtended access916

A local repository map for agents: the atlas CLI and MCP find the relevant code by file purpose instead of opening everything.

CLIExtended access502

An architecture coach skill: questions lead to ADRs, a diagram and a plan, and a repository is audited from its code

SkillMinimal access89

A skill that maps a repository into meaningful blocks, walks through the code on that map step by step and highlights broken spots

SkillExtended access295

README in short

The repository holds `SKILL.md`, a Python generator, section templates and generator tests. Installation boils down to copying the folder into your skills directory.

README badge

Original SKILL.md

---
name: repo-atlas
description: "Build a persistent context system (atlas) for any repository — generates directory maps with entrypoints, documents architecture and module boundaries, traces critical flows, catalogs external dependencies, and creates agent-ready onboarding guides. Use when asked to create a repo map, generate codebase documentation for LLM agents, set up an atlas, or create onboarding docs. Also use when asked to 'map this repo', 'document this codebase', or 'create context docs'."
---

# Repo Atlas

Build an in-repo persistent context system so engineers and LLM agents can understand any codebase quickly with minimal searching.

## Hard Constraints

- Do NOT change product/runtime behavior
- No paid/hosted tooling — everything lives in the repo
- Zero or minimal dependencies (Python 3 standard library only)
- All generated content must reflect real repo specifics, not generic filler

## Workflow

### Phase 1: Reconnaissance

Before writing anything, understand the repo:

1. Read the top-level directory structure
2. Identify the repo type (app, backend/API, library, monorepo, CLI, infrastructure)
3. Identify the primary language(s) and framework(s)
4. Find entrypoints, build configs, CI files
5. Read 5-10 key files to understand architecture patterns

### Phase 2: Run the Generator Script

Copy `scripts/generate_atlas.py` (bundled with this skill) to the repo at `scripts/atlas/generate_atlas.py`. Then customize and run it:

1. Copy the script to the target repo
2. Review and adjust the configuration section at the top:
   - `IGNORE_NAMES` — add repo-specific directory names to ignore (exact segment match)
   - `TREE_ANNOTATIONS` — add short descriptions for key directories
   - `ENTRYPOINT_NAMES` — add framework-specific entry filenames
   - `ENTRYPOINT_PATH_PATTERNS` — add path-based patterns (fnmatch style, e.g., `cmd/*/main.go`)
   - `ENTRYPOINT_CONTENT_MARKERS` — add code markers that identify entry points
   - `CONVENTIONAL_COMMITS` — adjust if repo uses different commit conventions

Report a problem