Guide · Agent skill
How to use the Codebase Scanner agent skill (scan)
Updated · written with AI from the project's own documentation and checked against our catalogue data
The Codebase Scanner is an agent skill, a packaged set of instructions that an AI coding agent can load and follow, named scan. It reads your code project and writes a project-doc.md summary of its tech stack, folder layout, conventions and tests, plus an AGENTS.md file at the repo root that tells future AI agents how to work in that project. This guide is for developers and maintainers who have not used agent skills before. By the end you will know what the skill does, how to install it, how to trigger it and what to check before trusting its output.
Codebase Scannerwshobson/agents · MIT Download the skill Quick start
- 1Download the ZIP. Download the scan skill ZIP from this page.
- 2Unzip the skill. Unzip it into ~/.claude/skills/ for personal use or into the project's .claude/skills/ folder for one repo.
- 3Check the git repo. Make sure the project is under git with commit history, since delta scans rely on git diff HEAD~1.
- 4Optionally install plugins. Run /plugin list to check for understand-anything and context-mode, and install them if you want deeper analysis.
- 5Ask for a scan. Request a scan in plain language, such as asking to bootstrap docs for AI agents or to check for drift.
- 6Review the output. Read project-doc.md and AGENTS.md for accuracy before committing them.
- 7Confirm architectural changes. On delta runs, answer y or n when the scanner reports an architectural change.
What the Codebase Scanner skill makes the agent do
The skill is written as a technical analyst brief. On each run the agent checks whether the optional plugins understand-anything and context-mode are available, then decides between two modes. If .claude/pipeline/project-doc.md does not exist, it runs a full scan. If that file exists, it runs a delta scan that only looks at files changed since the last commit.
After writing project-doc.md, the first run also generates AGENTS.md. The skill says this file is not a copy of project-doc.md but agent instructions tailored to the project. On later runs, AGENTS.md is only changed when the scanner detects an architectural change and you confirm it.
- project-doc.md covers tech stack, dependencies, architecture pattern, folder structure, code style, data architecture, cross-cutting concerns, test coverage and entry points.
- AGENTS.md is written to the repo root on the first run.
- Delta runs check changes such as a new framework, a new architectural directory, a major dependency swap or a new auth pattern.
- The skill ends with a summary report and updates state.json.
Install the Codebase Scanner skill
Download the scan skill ZIP from this page. Then choose one of two installation routes. For a personal setup that applies to all your projects, unzip the download into ~/.claude/skills/. For a single project, unzip it into that project's .claude/skills/ folder so it travels with the repo.
If you use the Claude apps instead of the command line, upload the ZIP under Settings → Capabilities → Skills.
- Personal install: unzip into ~/.claude/skills/
- Project install: unzip into the project's .claude/skills/
- Claude apps: Settings → Capabilities → Skills, then upload the ZIP
Optional: install the enhancement plugins
The skill works without these plugins, but it uses them when present. To check whether they are installed, run the commands below inside Claude Code. The plugin manager uses /plugin commands.
The two optional plugins are understand-anything, which provides deeper semantic code analysis, and context-mode, which routes large outputs through a sandbox to protect the context window. If either is missing, the skill falls back to native tools such as find, grep, cat and git.
/plugin list | grep understand-anything
/plugin list | grep context-mode
/plugin marketplace add Lum1104/Understand-Anything && /plugin install understand-anything
/plugin marketplace add mksglu/context-mode && /plugin install context-mode@context-modeTrigger the skill with natural requests
You do not need a special syntax. The skill's description says when to use it: bootstrapping a new agent-driven repo, refreshing project documentation after architectural changes, or running a delta scan to detect drift. Ask for one of those outcomes in plain language and the agent should pick up the skill.
Be specific about the goal. A request to document the project for AI agents suits a first run. A request to check whether docs have drifted from the code suits a delta run.
- "Scan this repo and create project-doc.md and AGENTS.md so AI agents can work here."
- "We just finished a large refactor. Refresh the project documentation."
- "Run a delta scan to check whether the docs have drifted from the code."
What the skill needs and what to check first
The project must be under git. Delta scans run git diff HEAD~1 --name-only to find changed files, so a repo with no git history will fail or report incorrectly. Git is also used for change detection on every run.
The output is inferred by an AI model from your code, so read it before relying on it. The skill's own template says AGENTS.md is auto-generated and should not be edited manually, and architectural updates need human confirmation.
- Git must be installed and the project must have history.
- Claude Code plugin manager is needed only to check or install the optional plugins.
- No scripts are run by this skill, and it does not use the network according to the listing.
Safety notes: file reads and model access
The skill reads project files so that it can describe them. Those reads are part of the agent's work and are visible to the model you are using. If the codebase is sensitive, review what the agent reads and whether the output should go to a model provider before running the scan.
The skill's template includes security rules that the agent must follow before writing AGENTS.md, but this guide does not reproduce them, so read references/agents-template.md in the ZIP if you need the exact rules.
- Do not run this on sensitive code until you have reviewed the file reads.
- Check the generated docs for accuracy before committing them.
Tips for better scans
Run the first full scan on a clean commit so the baseline reflects the code you intend to document. Delta scans compare against the previous commit, so committing between runs keeps the change list meaningful.
When the agent asks about an architectural change, read the listed changes before choosing y or n. Confirming only moves AGENTS.md forward after you have checked it.
- Commit before a full scan to get a clean baseline.
- Make small commits between delta runs so the changed-file list stays useful.
- Install context-mode if the codebase is large, since it keeps raw output out of the main context window.
What people use it for
- Bootstrapping a new repo that AI agents will work in, by generating project-doc.md and AGENTS.md on the first run.
- Refreshing project documentation after a large refactor so it matches the new folder layout.
- Running a periodic delta scan to spot drift between code and documentation.
- Recording a clear summary of tech stack, conventions and test areas for new contributors.
Frequently asked questions
Is the Codebase Scanner skill free to use?
The skill is published under the MIT licence. The listing does not state prices, so check the source repository for any licence details beyond that.
What do I need to run the Codebase Scanner skill?
You need git, and your project needs commit history for delta scans. The Claude Code plugin manager is needed only if you want to check or install the optional understand-anything and context-mode plugins.
How do I install the scan skill?
Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use or into the project's .claude/skills/ folder. In the Claude apps, upload the ZIP under Settings → Capabilities → Skills.
Does the skill work without understand-anything or context-mode?
Yes. The skill is designed to fall back to native tools such as find, grep, cat and git when either optional plugin is missing. Its output may differ in depth, since the plugins add deeper analysis and output routing.
Why does delta scanning fail in my repo?
Delta scans use git diff HEAD~1 to find changed files. A repo with no git history, or with fewer than two commits, can fail or report changes incorrectly, so use a repo with history.
Will the skill change AGENTS.md without asking me?
No. On delta runs, AGENTS.md is only patched when an architectural change is detected and you answer y to the confirmation prompt. The skill is also told to patch affected sections only, never rewrite the full file.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use this skill if you are setting up a repo that AI agents will work in, or if you want a periodic check that documentation still matches the code. Pick something else if you do not want AI-generated docs in your repo, if your project has no git history, or if your code is too sensitive to send to a model provider without review.
Download the skill