Skip to content
Get packs

Guide · Agent skill

How to use the Acquire Codebase Knowledge agent skill

Updated · written with AI from the project's own documentation and checked against our catalogue data

Acquire Codebase Knowledge is an agent skill that tells an AI agent to map, document or onboard you into an existing project. It runs a local scan script over the code, reads intent documents such as README or PRD files, and writes seven markdown files into docs/codebase/. This guide explains what an agent skill is, how to install this one, how to trigger it, and what to check in the output.

Acquire Codebase Knowledgegithub/awesome-copilot · MIT

Quick start

  1. 1Download the ZIP. Download the skill ZIP from the directory page and unzip it.
  2. 2Place the skill folder. Put it in ~/.claude/skills/ for personal use or in .claude/skills/ inside your project. Alternatively, upload it under Settings → Capabilities → Skills in the Claude apps.
  3. 3Confirm the requirements. Check that Python 3.8+ and git are installed and that your agent can run shell commands in the project folder.
  4. 4Make a request. Ask something like 'map this codebase' or 'onboard me to this repo' from the project root.
  5. 5Review the seven docs. Read the files in docs/codebase/, follow the evidence paths, and answer the [ASK USER] questions.

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

An agent skill is a folder containing a SKILL.md file and optional scripts and templates. When you make a request that matches the skill's description, the agent loads those instructions and follows them. This skill is meant for requests where you explicitly ask for repository-level discovery.

When triggered, the agent runs scripts/scan.py from your project root, reads any README, PRD, TRD, ROADMAP, SPEC or DESIGN files, and then fills in seven templates. Each claim is meant to cite a file path. Anything it cannot verify is marked [TODO], and questions about team intent are marked [ASK USER].

  • docs/codebase/STACK.md
  • docs/codebase/STRUCTURE.md
  • docs/codebase/ARCHITECTURE.md
  • docs/codebase/CONVENTIONS.md
  • docs/codebase/INTEGRATIONS.md
  • docs/codebase/TESTING.md
  • docs/codebase/CONCERNS.md

Install the Acquire Codebase Knowledge skill

Download the skill as a ZIP from the directory page and unzip it. Then place the skill folder in one of the locations below. Use the personal location to make it available across your projects, or the project location to share it with one repository.

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

  • Personal: unzip into ~/.claude/skills/
  • Project: unzip into .claude/skills/ inside your project folder
  • Claude apps: Settings → Capabilities → Skills, then upload the skill

Check the requirements before you start

The skill needs Python 3.8 or newer and git. It also needs an AI agent that can run shell commands in the project folder, because the scan script has to run from the target project root. The skill runs scripts (yes) and does not use the network (no).

The scan writes its output to docs/codebase/.codebase-scan.txt. The command is the same on Windows, macOS and Linux, apart from the path to the skill folder.

  • Python 3.8+
  • git
  • An agent that can run shell commands in the project folder
python3 "$SKILL_ROOT/scripts/scan.py" --output docs/codebase/.codebase-scan.txt

How do you trigger the skill with a natural request?

Ask for mapping, documenting or onboarding in plain words. The skill's description gives these example prompts. You can also add a focus area, such as architecture only or testing and concerns, to narrow the work.

Do not expect it to run for routine feature work, bug fixes or narrow code edits. The skill says it should not trigger for those unless you ask for repository-level discovery.

  • 'Map this codebase'
  • 'Document this architecture'
  • 'Onboard me to this repo'
  • 'Create codebase docs'
  • 'Map this codebase, architecture only'

What to check in the output and safety notes

Before you rely on the docs, check the [ASK USER] questions and the intent-versus-reality divergences the agent reports, and follow the evidence file paths. The output is only as accurate as the files it reads. The scan has fixed limits, for example 200 tree entries and 3 directory levels, so very large monorepos may be only partly mapped.

The skill runs a local script and does not use the network. Review the script before running it if you have security requirements, since it executes in your project folder.

  • Open each document's evidence list and check a few file paths
  • Resolve every [ASK USER] item with your team
  • Treat [TODO] markers as gaps, not facts

What people use it for

  • Orienting yourself in an unfamiliar repository before your first change
  • Creating a documented baseline of architecture and risks for a tech lead
  • Preparing a project for handover or an audit
  • Writing down integrations, testing setup and conventions for a team wiki

Frequently asked questions

Is the Acquire Codebase Knowledge skill free?

The skill is published under the MIT licence, as stated on its page. The source does not mention any price, so check the directory page for current terms.

What do I need to install the Acquire Codebase Knowledge skill?

You need Python 3.8 or newer and git, plus an AI agent that can run shell commands in your project folder. Install the skill by unzipping it into ~/.claude/skills/ or .claude/skills/, or by uploading it in the Claude apps under Settings → Capabilities → Skills.

Why isn't the skill running when I ask for a bug fix?

The skill is designed not to trigger for routine feature implementation, bug fixes or narrow code edits. It runs when you explicitly ask to map, document or onboard into a codebase.

Does the skill send my code over the network?

The skill's metadata says it does not use the network. It runs scripts/scan.py locally from your project root and writes its output into docs/codebase/.

Why are there [TODO] and [ASK USER] markers in the docs?

[TODO] marks something the agent could not determine from the code. [ASK USER] marks a decision that depends on team intent. Both are intentional, so answer the [ASK USER] questions before relying on the docs.

Will this work on a very large monorepo?

It may not map everything. The scan uses fixed limits, such as 200 tree entries and 3 directory levels, so large monorepos can be only partly covered. The source does not describe a way to change these limits.

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 want a written orientation to an existing repository, a documented architecture baseline, or handover docs, and you are willing to review the output against the cited files. Pick something else for routine feature work, bug fixes, very large monorepos where the scan limits will miss much of the structure, or any case where you need authoritative docs without review.

Download the skill