How to use the Learn Codebase agent skill (learn-codebase)

What an agent skill is and what this one makes the agent do

An agent skill is a folder containing a SKILL.md file. The file has a short description at the top that tells the agent when the skill applies, and instructions below that tell the agent what to do. When the skill is installed and matches a request, the agent follows those instructions.

The learn-codebase skill tells the agent to systematically read every source file in the project in full, no matter how many there are. For large files, it tells the agent to page through the file in chunks using the Read tool's offset and limit parameters. The stated goal is a deep understanding of the codebase that the agent can work from later.

• It is only instructions for the agent; the skill contains no scripts.
• Its single file is SKILL.md.
• Its description says to use it when starting work on a new or unfamiliar project, or when you ask to "learn the codebase", "read the codebase", "prime", or "get up to speed".

Install the learn-codebase skill from the ZIP

Download the ZIP for the skill from this page and unzip it. You can install it for yourself across all projects, or for a single project.

For a personal install, unzip it into ~/.claude/skills/. For a single project, unzip it into the .claude/skills/ folder inside that project. Either way, the skill's SKILL.md file should end up inside a learn-codebase folder.

If you use the Claude apps instead, you can upload the skill under Settings → Capabilities → Skills.

• Personal: ~/.claude/skills/
• Project only: .claude/skills/ inside the project folder
• Claude apps: Settings → Capabilities → Skills

How to trigger the skill with natural requests

You do not need a special command. The skill is matched by its description, so ask the agent in plain language. The description lists these phrases: "learn the codebase", "read the codebase", "prime", and "get up to speed". You can also describe the situation, such as saying you have just started on a new or unfamiliar project.

Be explicit about scope if it matters. The skill is written to cover every source file, so if you only want part of a repository understood, say so in your request and the agent can decide how to proceed.

• "Learn the codebase before we change anything."
• "Read the codebase so you understand how this project is structured."
• "Prime yourself on this repo, I just inherited it."
• "I'm new to this project. Get up to speed before we start."

Examples of when to use it and when to skip it

The skill fits best when you are new to a project and want the agent to understand the code before it edits anything. A typical case is an inherited codebase where nobody on the current team wrote the original code.

It is a poor fit for a narrow task. If you only need one bug fixed in a known file, a full read adds overhead without much benefit. Very large repositories are also a poor fit, because reading every source file can use a large amount of tokens and cost money.

• Good fit: an inherited project you need to understand before a larger change.
• Good fit: a team that wants the agent to build a working model of a repository before it is asked to change things.
• Poor fit: fixing one bug in one file.
• Poor fit: very large repositories where token use becomes costly.

What the skill needs and what to watch for

The skill lists no requirements. It runs no scripts and does not use the network. Its only dependency is the agent's Read tool, which the instructions refer to directly.

The main safety concern is content, not code execution. The instruction covers every source file, so the agent may read secrets or credentials that are stored alongside code. Before you use it on a repository that holds sensitive files, review what is in the project and consider keeping those files out of the folder the agent can reach.

• Requires: nothing listed.
• Runs scripts: no.
• Uses network: no.
• Reads every source file, including any secrets or credentials stored in the project.

Tips for getting the most from it

Run the skill at the start of a session, before asking for changes, so the understanding is in place when the real work begins. The skill's own note says it front-loads a cognitive cache to make later development less costly over the life of the project.

Expect the run to take time and tokens on a large project. Keep your request focused on the goal you have in mind after the read.

• Start a fresh session on the project, then ask for the read first.
• Check the project for sensitive files before you run it.
• For small tasks, skip the skill and ask for the change directly.