How to use the Codebase Onboarding Guide agent skill

What is an agent skill and what does this one do?

An agent skill is a folder containing a SKILL.md file that gives an AI agent specific instructions for a task. This skill is written in Japanese and, when triggered, tells the agent to analyse a codebase it does not know yet.

The agent first gathers raw signals without reading every file. It checks package manifests (such as package.json, go.mod, Cargo.toml, pyproject.toml and pom.xml), framework config files (such as next.config, nuxt.config, angular.json and vite.config), entry points (main.*, index.*, app.*, server.*), the top two levels of the directory tree, lint and build config (such as .eslintrc, .prettierrc, tsconfig.json and Dockerfile), and test structure (such as tests/, __tests__/, *.spec.ts and jest.config.*).

It then identifies the main modules and how they relate, and notes coding conventions and naming patterns.

The output is an architecture map, the main entry points and flow, a conventions and style guide, and a starter CLAUDE.md file that tells future Claude Code sessions how the project works.

How do you install the codebase-onboarding skill?

The skill ships as a single file, SKILL.md. Download the ZIP from the skill's page on this site and unzip it into one of the following locations, depending on whether you want the skill for yourself or for one project.

You can also upload the skill in the Claude apps under Settings → Capabilities → Skills.

• Personal use across projects: unzip into ~/.claude/skills/
• Single project: unzip into the project's .claude/skills/ folder, so teammates who clone the repo get it too
• Claude apps: Settings → Capabilities → Skills, then upload the skill

How do you trigger the skill with a natural request?

You do not need a special command. The skill is meant to run when you ask for something that matches its purpose. The source lists these situations: opening a project in Claude Code for the first time, joining a new team or repository, asking the agent to help you understand a codebase, asking it to generate a project's CLAUDE.md, and saying 'onboard' or 'describe this repo'.

Be specific about the outcome you want. Asking for a CLAUDE.md or an onboarding guide makes the output format clear.

• Help me understand this codebase.
• Generate a CLAUDE.md for this project.
• Onboard me to this repo.
• Describe this repo so I can start contributing.

What should you expect from the output?

The result is a structured document with four parts. The architecture map shows the main modules and their relationships. The entry points and flow section shows where execution starts and how it moves through the code. The conventions and style section lists coding rules and project-specific patterns. The starter CLAUDE.md is a file you can review, edit and keep in the repository so future Claude Code sessions start with context.

Treat the output as a first draft. The skill infers everything from the code, so it can be wrong or incomplete. Check the claims against the actual files before relying on them.

• Architecture map
• Main entry points and flow
• Conventions and style guide
• Starter CLAUDE.md

What does the skill need, and what are the safety notes?

The skill requires Claude Code or another SKILL.md-compatible agent with read access to the repository. It does not run scripts and does not use the network, according to its listing. It only reads project files.

Because it only reads, it is low risk in that sense. Still, review any CLAUDE.md it writes before committing it, since that file will steer future agent sessions.

• Requires: Claude Code or another SKILL.md-compatible agent with read access to the repository
• Runs scripts: no
• Uses network: no

Which projects is this skill not suited for?

The skill reads only the top-level structure and key files. In very large monorepos, a shallow scan can miss important modules. The output is inferred from code, not verified documentation, so projects that need accurate, up-to-date docs should not rely on it alone.

• Very large monorepos where important modules sit below the top two directory levels
• Projects that need verified, up-to-date documentation

Tips for better results

Run the skill from the root of the repository so the top-level structure is visible. Ask for the starter CLAUDE.md explicitly if you only want that file. Compare the entry points it reports with the real ones before trusting the flow description.

• Start from the repository root.
• Ask for specific outputs such as the CLAUDE.md.
• Verify the entry points and conventions against the code.
• Edit the generated CLAUDE.md to add rules the code does not show.