How to use the Repomix Codebase Explorer agent skill

What is an agent skill and what does repomix-explorer do?

An agent skill is a folder containing a SKILL.md file that gives an AI agent instructions for a specific kind of task. The agent reads these instructions when a request matches the skill's description.

When you ask an agent for an overview of an unfamiliar or large codebase, this skill tells it to run the Repomix tool. Repomix bundles all the project's files into a single text file, XML by default. The agent then searches that file for patterns such as authentication code, API endpoints, or largest files, and reports back a structure summary and metrics such as file counts and token estimates.

• Works on local folders and on public GitHub repositories you name
• Reports structure, file counts, token estimates and language breakdowns
• Intended for read-only exploration, not editing

Install the repomix-explorer skill

Download the skill ZIP from this page and unzip it. You can install it in one of two ways.

Option A: for your user account, unzip the folder into ~/.claude/skills/. Option B: for one project only, unzip it into the project's .claude/skills/ folder.

Option C: in the Claude apps, open Settings, go to Capabilities, then Skills, and upload the ZIP.

• Personal install: ~/.claude/skills/
• Project install: .claude/skills/ inside your project
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP

Make sure your machine can run it

The skill runs the Repomix CLI through npx, so Node.js with npx must be available. The Repomix CLI is fetched on demand with npx repomix@latest, so you do not install it separately. Remote repositories need network access to GitHub.

• Node.js with npx available on the command line
• Network access for remote repositories on GitHub
• The skill runs scripts and uses the network

How to trigger the skill with natural requests

You do not need special syntax. Describe what you want in plain language and the agent will decide whether the skill applies. The skill is triggered by requests for structure or overviews, pattern discovery across many files, metrics, and any GitHub URL or owner/repo name you want explored.

• Structure: "Analyze this repo", "What's the structure of facebook/react?"
• Patterns: "Find all authentication code", "Where are the API endpoints defined?"
• Metrics: "How many files are in this project?", "Show me the largest files"
• Remote: "Explore https://github.com/microsoft/vscode"

Examples of what you can ask for

For a remote repository, the agent runs Repomix with the --remote flag and writes the output to /tmp so your current project stays clean. For a local folder, it packs that directory. For large repositories it can use --compress, which the skill describes as Tree-sitter compression with about 70% token reduction.

• Overview: "Explain the structure of this project"
• Remote: "Analyze the yamadashy/repomix repository"
• Language mix: "How much TypeScript vs JavaScript?"
• Pattern search: "Show me all React components"

Know what the skill will not do

The skill is for understanding, not changing code. Its description says not to trigger for editing, refactoring or writing code in your current project, for git operations, running tests, builds or installs, or for reading a single known file. For a single known file, a direct read or grep is faster.

• Not for editing or refactoring your current project
• Not for a known file path or a single-symbol grep
• Not for sensitive or private repositories, since the code is packed and processed and remote fetches go over the network

Safety notes: scripts and network

This skill runs scripts and uses the network. The agent executes Repomix commands in a shell, and remote repositories are fetched from GitHub. The packed output contains the repository's code, so treat the generated file as containing whatever the repo contains.

Avoid using it on private or sensitive repositories. Remove large output files after analysis if you do not need them, as the skill itself recommends.

• Runs shell commands through npx
• Fetches remote repositories over the network
• Output may be large; clean it up with rm repomix-output.xml when done

Tips for better results

Name the repository explicitly in the form owner/repo or as a full GitHub URL. If you care about a branch, tag or commit, say so, since the skill supports a specific remote branch. Ask targeted questions such as where authentication lives, which files are largest, or where routes are defined, because those map to the grep searches the skill runs.

• Use owner/repo or a full GitHub URL for remote projects
• Name a branch, tag or commit when it matters
• Ask specific pattern questions for better search results
• Keep the default XML format unless you have a reason to change it