---
title: "skill by agenticluke · skilld"
canonical_url: "https://skilld.dev/gh/agenticluke/codebase-map-plus"
meta:
  description: "Study a new codebase and make a clear guide with its structure, key entry points, code rules, and a starter CLAUDE.md. Use when joining a project, explaining a… From agenticluke/codebase-map-plus."
  "og:description": "Study a new codebase and make a clear guide with its structure, key entry points, code rules, and a starter CLAUDE.md. Use when joining a project, explaining a… From agenticluke/codebase-map-plus."
  "og:title": "skill by agenticluke"
  "twitter:description": "Study a new codebase and make a clear guide with its structure, key entry points, code rules, and a starter CLAUDE.md. Use when joining a project, explaining a… From agenticluke/codebase-map-plus."
  "twitter:title": "skill by agenticluke"
---

`

[All skills](https://skilld.dev/skills)

[![agenticluke avatar](https://skilld.dev/_img/avatar?url=https%3A%2F%2Fgithub.com%2Fagenticluke.png%3Fsize%3D96)](https://skilld.dev/gh/agenticluke)

# **/skill**

[@d202ecb](https://github.com/agenticluke/codebase-map-plus/commit/d202ecba01c711faf15e877e07048f07ea3707a7 "Your agent reads SKILL.md at commit d202ecb")

by [agenticluke](https://skilld.dev/gh/agenticluke)· [agenticluke](https://skilld.dev/gh/agenticluke)/ [codebase-map-plus](https://skilld.dev/gh/agenticluke/codebase-map-plus)

Study a new codebase and make a clear guide with its structure, key entry points, code rules, and a starter CLAUDE.md. Use when joining a project, explaining a repo, or setting up Claude Code for the first time.

- 1 file
- 7.2 KB
- Updated 4 weeks ago
- [GitHub](https://github.com/agenticluke/codebase-map-plus/blob/main/skill/SKILL.md "View SKILL.md on GitHub")

## SKILL.md

7.2 KB

**≈55** tokens always: the name and description. **≈1.8k** when used: this file.

## Codebase Onboarding

### Credit

This skill was created by **ECC**. It is shared under a permissive open-source license. Keep this credit when you copy or change the skill.

### When to Use

Use this skill when:

- Claude Code opens a project for the first time.
- A user joins a new team or repo.
- A user asks, "Help me understand this codebase."
- A user asks for a project `CLAUDE.md`.
- A user says, "Onboard me" or "Explain this repo."

### Goal

Learn the project without reading every file. Find the main parts, show how they work together, and write a short guide that helps a new person begin.

Do not change project files unless the user asks. Do not run code that can post, deploy, delete data, or change live systems.

### Step 1: Check Existing Rules

Before reading the code:

1. Find `CLAUDE.md`, `AGENTS.md`, `CONTRIBUTING.md`, and `README` files.
2. Read the rules that apply to the current folder.
3. Check for nested rule files in key folders.
4. Follow project rules even if they differ from this skill.

If a good `CLAUDE.md` already exists, review it. Do not replace it without need. Suggest small fixes instead.

### Step 2: Scan the Project

Gather useful facts without opening every file. Run safe checks at the same time when possible.

#### Find package files

Look for files such as:

- `package.json`
- `go.mod`
- `Cargo.toml`
- `pyproject.toml`
- `requirements.txt`
- `Gemfile`
- `pom.xml`
- `build.gradle`
- `composer.json`

Read lock files only when you need an exact tool or package version.

#### Find tools and frameworks

Look for files such as:

- `next.config.*`
- `nuxt.config.*`
- `angular.json`
- `vite.config.*`
- `tsconfig.json`
- `Dockerfile`
- `docker-compose.*`
- `.eslintrc*`
- `eslint.config.*`
- `.prettierrc*`
- `Makefile`
- CI files under `.github/workflows/`

Do not name a framework from a file name alone. Check the package file or source code too.

#### Find entry points

Look for common entry files:

- `main.*`
- `index.*`
- `app.*`
- `server.*`
- CLI command files
- Web route files
- Worker or job files
- Mobile app start files

A repo may have more than one entry point. List each one and say what starts it.

#### View the folder shape

Show the top two folder levels first. Skip large or made files such as:

- `.git/`
- `node_modules/`
- `vendor/`
- build output
- cache folders
- coverage reports
- large data files

Open deeper folders only when they hold key code.

#### Find tests

Look for:

- `tests/`
- `test/`
- `__tests__/`
- `*.test.*`
- `*.spec.*`
- test tool config files

Find how tests are run. Do not run slow tests unless the user asks or the cost is clear.

### Step 3: Map the Code

Find the main parts and how data moves between them.

For each main part, state:

- Its job
- Its folder
- What calls it
- What it calls
- What data it reads or writes

Trace at least one common path from start to end. For example:

```
HTTP request -> route -> service -> database -> response
```

If the repo has more than one app, make a small map for each app. Then show any shared code.

Do not guess. Mark facts that are not clear as `Needs review`.

### Step 4: Find Project Rules

Read a few normal source files from each main area. Find rules for:

- File and folder names
- Function and class names
- Import paths
- Error handling
- Logs
- Settings and environment values
- Tests
- Comments and docs
- Code format

Separate written rules from patterns you only saw in code:

- `Stated rule`: Found in a rule or config file.
- `Seen pattern`: Found in several source files.
- `Needs review`: Seen once or not fully clear.

Do not copy secrets. List environment variable names only. Never show their values.

### Step 5: Handle Special Cases

- **Empty repo:** Say what is present and give a short setup list.
- **Very large repo:** Start with root files and active apps. Ask which app matters most if the scope is still too wide.
- **Many apps:** List each app, its start file, and shared parts.
- **Old code:** Note old and new patterns. Do not call one the main rule without proof.
- **Made code:** Mark generated files and do not use them to infer style.
- **Missing docs:** Say which facts came from code.
- **Broken setup:** Report the exact missing file, tool, or step. Do not hide the error.
- **Unknown language:** Use package files, start scripts, and folder names to guide the scan.
- **No tests:** State that no tests were found. Do not claim the project has no test plan.
- **Dirty worktree:** Do not remove or replace the user's changes.

### Output

Give the user these sections:

#### Project Summary

Explain what the project does in three to six short lines.

#### Project Map

Show the main folders and their jobs.

#### Entry Points

List each app, server, CLI, worker, or job entry point. Include the command that starts it when known.

#### Main Flow

Show one or more common paths through the code.

#### Tools and Commands

List confirmed commands for setup, start, test, lint, format, and build. Say `Not found` when a command is unknown.

#### Code Rules

List stated rules, seen patterns, and points that need review.

#### Risks and Open Questions

List missing docs, unclear code paths, old parts, unsafe scripts, or setup gaps.

#### Starter CLAUDE.md

Draft a short `CLAUDE.md` with:

- Project purpose
- Main folders
- Safe setup commands
- Test and check commands
- Code rules
- Files that should not be changed
- Known risks
- Any project-specific safety rules

Show the draft first. Write it to the repo only if the user asked for a file change.

### Example

User request:

```
Onboard me to this repo and draft a CLAUDE.md.
```

Example result:

```
## Project Summary

This is a small web app for tracking tasks. The browser app sends requests to a Node.js API. The API stores tasks in PostgreSQL.

## Project Map

- `src/web/`: Browser pages and UI parts
- `src/api/`: HTTP routes and request checks
- `src/services/`: Main task rules
- `src/db/`: Database access
- `tests/`: Unit and API tests

## Entry Points

- `src/server.ts`: Starts the API with `npm run dev`
- `src/web/main.tsx`: Starts the browser app
- `src/jobs/cleanup.ts`: Removes old task logs

## Main Flow

Create task request -> API route -> task service -> database -> JSON response

## Tools and Commands

- Install: `npm install`
- Start: `npm run dev`
- Test: `npm test`
- Lint: `npm run lint`
- Build: `npm run build`

## Code Rules

- Stated rule: Use TypeScript strict mode.
- Seen pattern: Service files end with `.service.ts`.
- Needs review: Some old routes return errors in a different shape.

## Risks and Open Questions

- The cleanup job has no test.
- The needed Node.js version is not written in the repo.
```

### Quality Check

Before you finish, confirm that:

- Each claim points to a file or clear code path.
- All key entry points are listed.
- Commands come from project files, not guesses.
- Generated and third-party files were skipped.
- No secret values were shown.
- Unknown facts are marked clearly.
- No project file was changed without the user's request.

Source: [SKILL.md on GitHub](https://github.com/agenticluke/codebase-map-plus/blob/main/skill/SKILL.md)

## Third-party checks

No third-party reports yet.

## Provenance

[Signed by skilld at d202ecb.](https://github.com/agenticluke/codebase-map-plus/commit/d202ecba01c711faf15e877e07048f07ea3707a7 "d202ecba01c711faf15e877e07048f07ea3707a7") This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 4 weeks ago.

Activeupdated 4 weeks ago

## Capability

<dl>

<dt>origin</dt>
<dd>ECC</dd>

</dl>

## README badge

![README badge for agenticluke/codebase-map-plus](https://skilld.dev/b/agenticluke/codebase-map-plus?theme=light&label=0)

## Related skills

-
-
-
-
-
-