New: 97,000+ skills indexed from GitHub repos with 100+ stars · every skill safety-checkedBrowse top skillsTop skills
Esc to closeBrowse all skills
Submit a skillBrowse skills
Submit a skillBrowse skills

Official agent skill

Acquire Codebase Knowledge

by github in github/awesome-copilot

Maps an unfamiliar codebase into seven evidence-backed documents in docs/codebase/, using a scan script and templates, for onboarding or architecture write-ups.

OfficialMITAuto-check passedDevelopment

Install Acquire Codebase Knowledge

skills CLI
$ npx skills add github/awesome-copilot --skill acquire-codebase-knowledge -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install github/awesome-copilot acquire-codebase-knowledge --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/github/awesome-copilot.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/acquire-codebase-knowledge .claude/skills/acquire-codebase-knowledge && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
acquire-codebase-knowledge
GitHub stars
40k
Used in
1 other repo
Token cost
~2.3k tokens
SKILL.md length
884 words
Files
11 (incl. scripts, references, assets)
Skills in repo
417
Repo updated
First seen
Licence
MIT

At a glance

Maps an unfamiliar codebase into seven evidence-backed documents in docs/codebase/, using a scan script and templates, for onboarding or architecture write-ups.

  • Works in 4 steps: Scan and Read Intent → Investigate → Populate Templates → …
  • Onboarding to an existing repository you have not worked in before
  • SKILL.md covers Output Contract (Required), Workflow, Focus Area Mode and Gotchas, plus 3 more sections
  • Runs Python scripts from its folder; calls python3

What it does

When you ask it to map, document or onboard you to an existing repository, this skill produces seven Markdown documents in docs/codebase/: STACK, STRUCTURE, ARCHITECTURE, CONVENTIONS, INTEGRATIONS, TESTING and CONCERNS. It works in phases: run a scan script, read intent documents such as a README, PRD or roadmap, investigate each area, fill in the templates, then validate all seven.

Only what files or terminal output can verify is written down. Every document carries a short evidence list of file paths, unknowns are flagged instead of guessed, and the final reply lists numbered questions for you along with places where the stated intent and the code disagree. You can name a focus area, such as architecture only, which is finished first while the rest are still validated. It needs Python 3.8+ and git, with scan.py run from the project root.

When your agent uses it

  • Onboarding to an existing repository you have not worked in before
  • Documenting the architecture and conventions of a codebase
  • Creating a set of codebase docs grounded in the actual files
  • Finding where a project's stated intent and its code have drifted apart

Example prompts

  • “Map this codebase and write the docs.”
  • “Onboard me to this repo, and start with architecture only.”
  • “Create codebase docs for the payments service in ./services/payments.”
  • “Document this architecture and list what you could not verify.”

Requirements

  • Python 3.8+
  • git
  • Compatibility (from SKILL.md): Cross-platform. Requires Python 3.8+ and git. Run scripts/scan.py from the target project root.

Workflow steps

4 steps, taken from the step headings in SKILL.md.

  1. Scan and Read Intent
  2. Investigate
  3. Populate Templates
  4. Validate, Repair, Verify

What it can do on your machine

Read from SKILL.md and the folder at commit 727ff2e. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Ships 1 file in scripts/ (Python), which the agent can run.

    Shell commands in SKILL.md call:

    • python3

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

  • Compatibility

    Cross-platform. Requires Python 3.8+ and git. Run scripts/scan.py from the target project root.

    From compatibility in the SKILL.md frontmatter.

Context cost

Acquire Codebase Knowledge loads about 2.3k tokens when it runs, and up to ~4.7k if it reads all its reference files. Until then it costs about 98 tokens; SKILL.md has 884 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~98
When it runs · the whole SKILL.md, loaded when a task matches
~2.3k
With references · SKILL.md plus every file in references/, read only if the agent opens them
~4.7k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); the scripts in this folder are not scanned.

SKILL.md

The full file from github/awesome-copilot at commit 727ff2e, republished under its MIT licence (© github). 884 words, ~2,270 tokens.

Download SKILL.mdSave it as .claude/skills/acquire-codebase-knowledge/SKILL.md (or your agent's skills folder). This skill also uses 10 other files; get the full folder from GitHub.
name
acquire-codebase-knowledge
description
Use this skill when the user explicitly asks to map, document, or onboard into an existing codebase. Trigger for prompts like "map this codebase", "document this architecture", "onboard me to this repo", or "create codebase docs". Do not trigger for routine feature implementation, bug fixes, or narrow code edits unless the user asks for repository-level discovery.
compatibility
Cross-platform. Requires Python 3.8+ and git. Run scripts/scan.py from the target project root.
license
MIT
metadata.version
1.3
metadata.enhancements
Multi-language manifest detection (25+ languages supported), CI/CD pipeline detection (10+ platforms), Container & orchestration detection, Code metrics by…
argument-hint
Optional: specific area to focus on, e.g. "architecture only", "testing and concerns"

Acquire Codebase Knowledge

Produces seven populated documents in docs/codebase/ covering everything needed to work effectively on the project. Only document what is verifiable from files or terminal output — never infer or assume.

Output Contract (Required)

Before finishing, all of the following must be true:

  1. Exactly these files exist in docs/codebase/: STACK.md, STRUCTURE.md, ARCHITECTURE.md, CONVENTIONS.md, INTEGRATIONS.md, TESTING.md, CONCERNS.md.
  2. Every claim is traceable to source files, config, or terminal output.
  3. Unknowns are marked as [TODO]; intent-dependent decisions are marked [ASK USER].
  4. Every document includes a short "evidence" list with concrete file paths.
  5. Final response includes numbered [ASK USER] questions and intent-vs-reality divergences.

Workflow

Copy and track this checklist:

- [ ] Phase 1: Run scan, read intent documents
- [ ] Phase 2: Investigate each documentation area
- [ ] Phase 3: Populate all seven docs in docs/codebase/
- [ ] Phase 4: Validate docs, present findings, resolve all [ASK USER] items

Focus Area Mode

If the user supplies a focus area (for example: "architecture only" or "testing and concerns"):

  1. Always run Phase 1 in full.
  2. Fully complete focus-area documents first.
  3. For non-focus documents not yet analyzed, keep required sections present and mark unknowns as [TODO].
  4. Still run the Phase 4 validation loop on all seven documents before final output.
Phase 1: Scan and Read Intent

  1. Run the scan script from the target project root:

    bash
    python3 "$SKILL_ROOT/scripts/scan.py" --output docs/codebase/.codebase-scan.txt

    Where $SKILL_ROOT is the absolute path to the skill folder. Works on Windows, macOS, and Linux.

    Quick start: If you have the path inline:

    bash
    python3 /absolute/path/to/skills/acquire-codebase-knowledge/scripts/scan.py --output docs/codebase/.codebase-scan.txt

  2. Search for PRD, TRD, README, ROADMAP, SPEC, DESIGN files and read them.

  3. Summarise the stated project intent before reading any source code.

Phase 2: Investigate

Use the scan output to answer questions for each of the seven templates. Load references/inquiry-checkpoints.md for the full per-template question list.

If the stack is ambiguous (multiple manifest files, unfamiliar file types, no package.json), load references/stack-detection.md.

Phase 3: Populate Templates

Copy each template from assets/templates/ into docs/codebase/. Fill in this order:

  1. STACK.md — language, runtime, frameworks, all dependencies
  2. STRUCTURE.md — directory layout, entry points, key files
  3. ARCHITECTURE.md — layers, patterns, data flow
  4. CONVENTIONS.md — naming, formatting, error handling, imports
  5. INTEGRATIONS.md — external APIs, databases, auth, monitoring
  6. TESTING.md — frameworks, file organization, mocking strategy
  7. CONCERNS.md — tech debt, bugs, security risks, perf bottlenecks

Use [TODO] for anything that cannot be determined from code. Use [ASK USER] where the right answer requires team intent.

Phase 4: Validate, Repair, Verify

Run this mandatory validation loop before finalizing:

  1. Validate each doc against references/inquiry-checkpoints.md.
  2. For each non-trivial claim, confirm at least one evidence reference exists.
  3. If any required section is missing or unsupported:
  • Fix the document.
  • Re-run validation.
  1. Repeat until all seven docs pass.

Then present a summary of all seven documents, list every [ASK USER] item as a numbered question, and highlight any Intent vs. Reality divergences from Phase 1.

Validation pass criteria:

  • No unsupported claims.
  • No empty required sections.
  • Unknowns use [TODO] rather than assumptions.
  • Team-intent gaps are explicitly marked [ASK USER].
Show full SKILL.md (421 more words)Show less

Gotchas

Monorepos: Root package.json may have no source — check for workspaces, packages/, or apps/ directories. Each workspace may have independent dependencies and conventions. Map each sub-package separately.

Outdated README: README often describes intended architecture, not the current one. Cross-reference with actual file structure before treating any README claim as fact.

TypeScript path aliases: tsconfig.json paths config means imports like @/foo don't map directly to the filesystem. Map aliases to real paths before documenting structure.

Generated/compiled output: Never document patterns from dist/, build/, generated/, .next/, out/, or __pycache__/. These are artefacts — document source conventions only.

.env.example reveals required config: Secrets are never committed. Read .env.example, .env.template, or .env.sample to discover required environment variables.

devDependencies ≠ production stack: Only dependencies (or equivalent, e.g. [tool.poetry.dependencies]) runs in production. Document linters, formatters, and test frameworks separately as dev tooling.

Test TODOs ≠ production debt: TODOs inside test/, tests/, __tests__/, or spec/ are coverage gaps, not production technical debt. Separate them in CONCERNS.md.

High-churn files = fragile areas: Files appearing most in recent git history have the highest modification rate and likely hidden complexity. Always note them in CONCERNS.md.

Anti-Patterns

❌ Don't✅ Do instead
"Uses Clean Architecture with Domain/Data layers." (when no such directories exist)State only what directory structure actually shows.
"This is a Next.js project." (without checking package.json)Check dependencies first. State what's actually there.
Guess the database from a variable name like dbUrlCheck manifest for pg, mysql2, mongoose, prisma, etc.
Document dist/ or build/ naming patterns as conventionsSource files only.

Enhanced Scan Output Sections

The scan.py script now produce the following sections in addition to the original output:

  • CODE METRICS — Total files, lines of code by language, largest files (complexity signals)
  • CI/CD PIPELINES — Detected GitHub Actions, GitLab CI, Jenkins, CircleCI, etc.
  • CONTAINERS & ORCHESTRATION — Docker, Docker Compose, Kubernetes, Vagrant configs
  • SECURITY & COMPLIANCE — Snyk, Dependabot, SECURITY.md, SBOM, security policies
  • PERFORMANCE & TESTING — Benchmark configs, profiling markers, load testing tools

Use these sections during Phase 2 to inform investigation questions and identify tool-specific patterns.

Bundled Assets

AssetWhen to load
scripts/scan.pyPhase 1 — run first, before reading any code (Python 3.8+ required)
references/inquiry-checkpoints.mdPhase 2 — load for per-template investigation questions
references/stack-detection.mdPhase 2 — only if stack is ambiguous
assets/templates/STACK.mdPhase 3 step 1
assets/templates/STRUCTURE.mdPhase 3 step 2
assets/templates/ARCHITECTURE.mdPhase 3 step 3
assets/templates/CONVENTIONS.mdPhase 3 step 4
assets/templates/INTEGRATIONS.mdPhase 3 step 5
assets/templates/TESTING.mdPhase 3 step 6
assets/templates/CONCERNS.mdPhase 3 step 7

Template usage mode:

  • Default mode: complete only the "Core Sections (Required)" in each template.
  • Extended mode: add optional sections only when the repo complexity justifies them.

© github, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 10 other files (scripts, references, assets) in skills/acquire-codebase-knowledge of github/awesome-copilot.

  • SKILL.md
  • assets/templates/ARCHITECTURE.md
  • assets/templates/CONCERNS.md
  • assets/templates/CONVENTIONS.md
  • assets/templates/INTEGRATIONS.md
  • assets/templates/STACK.md
  • assets/templates/STRUCTURE.md
  • assets/templates/TESTING.md
  • references/inquiry-checkpoints.md
  • references/stack-detection.md
  • scripts/scan.py

Open the folder on GitHubat commit 727ff2e

Used in 1 other repository

We found 1 copy of this SKILL.md (exact, near-identical or edited) in other folders, from 1 other GitHub owner. This page covers the copy in github/awesome-copilot, which our catalogue first saw on October 7, 2026.

Compare with similar skills

Acquire Codebase Knowledge next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Acquire Codebase Knowledge compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Acquire Codebase Knowledge this skillgithub/awesome-copilot40k1 repos~2.3kAutomated safety check: PassMIT
BiSheng Approval Module Referencedataelement/bisheng12k—~4kAutomated safety check: PassApache-2.0
BTCA Local Repo Searchstickerdaniel/linkedin-mcp-server3.8k—~660Automated safety check: PassApache-2.0
Jgrepkeltokhy/jgrep136—~1.1kAutomated safety check: PassMIT
Local File and Code Searchtaxueseek/argo184—~1.1kAutomated safety check: PassMIT
Basemind Code ContextGoldziher/basemind106—~2.6kAutomated safety check: PassMIT

Similar skills

  • BiSheng Approval Module Reference

    dataelement/bisheng

    Maps BiSheng's approval-center architecture to exact service files and methods, so a change to approval logic can be located without searching the whole repo.

    12k GitHub stars~4k tokensUpdated 6 days ago
    DevelopmentAuto-check passed

  • BTCA Local Repo Search

    stickerdaniel/linkedin-mcp-server

    Searches git repositories cloned locally under a sandbox folder to answer questions with cited links and complete code snippets.

    3.8k GitHub stars~660 tokensUpdated today
    DevelopmentAuto-check passed

  • Jgrep

    keltokhy/jgrep

    Filter text, records, code functions, or complete diff hunks by a plain-English description using Jev.

    136 GitHub stars~1.1k tokensUpdated 8 days ago
    DevelopmentAuto-check passed

  • Local File and Code Search

    taxueseek/argo

    Searches local files and code through one script, seek.py, that picks between rg, fd and macOS Spotlight and works in three layers: locate, context, close reading.

    184 GitHub stars~1.1k tokensUpdated yesterday
    DevelopmentAuto-check passed

  • Basemind Code Context

    Goldziher/basemind

    Answers structural questions about a repository, such as where a symbol is defined, what calls it and what changed recently, through the basemind MCP server.

    106 GitHub stars~2.6k tokensUpdated yesterday
    DevelopmentAuto-check passed

  • Sync Docs

    ayutaz/piper-plus

    コミット前にエージェントチームで全ドキュメント (CLAUDE.md / README / CHANGELOG / docs/) を監査し、コード変更に応じて自動更新します。大規模変更時の documentation drift を予防。

    218 GitHub stars~1.4k tokensUpdated today
    DevelopmentAuto-check passed

More from github/awesome-copilot

All 417 skills in this repo

  • Azure Architecture Autopilot

    github/awesome-copilot

    Official

    Designs Azure infrastructure from a natural-language description, or diagrams an existing resource group, then refines the design through conversation and deploys it with Bicep.

    40k GitHub starsUsed in 1 repo~1.9k tokens
    Auto-check passed

  • Draw.io Diagram Generator

    github/awesome-copilot

    Official

    Generates, edits and validates draw.io files with correct mxGraph XML, covering flowcharts, architecture, sequence, ER and UML class diagrams.

    40k GitHub starsUsed in 1 repo~4.9k tokens
    Auto-check passed

  • Credit Risk Data Cleaning

    github/awesome-copilot

    Official

    Cleans raw credit data and screens variables before loan modeling, dropping unstable, noisy or redundant features and writing an Excel report of every step.

    40k GitHub starsUsed in 1 repo~1.5k tokens
    Auto-check passed

  • Daily Focus Board

    github/awesome-copilot

    Official

    Builds a warm, browser-based daily focus board the user updates by talking to their agent, with Eisenhower priorities, a brain-dump box and kind not-today carryover.

    40k GitHub stars~3k tokensUpdated today
    Auto-check passed

  • Python Pypi Package Builder

    github/awesome-copilot

    Official

    End-to-end skill for building, testing, linting, versioning, and publishing a production-grade Python library to PyPI.

    40k GitHub starsUsed in 1 repo~4.6k tokens
    Auto-check passed

  • Terraform Azurerm Set Diff Analyzer

    github/awesome-copilot

    Official

    Analyze Terraform plan JSON output for AzureRM Provider to distinguish between false-positive diffs (order-only changes in Set-type attributes) and actual resource changes.

    40k GitHub starsUsed in 1 repo~547 tokens
    Auto-check passed

Works with

Categories

Questions about Acquire Codebase Knowledge

What does Acquire Codebase Knowledge do?

Maps an unfamiliar codebase into seven evidence-backed documents in docs/codebase/, using a scan script and templates, for onboarding or architecture write-ups. When you ask it to map, document or onboard you to an existing repository, this skill produces seven Markdown documents in docs/codebase/: STACK, STRUCTURE, ARCHITECTURE, CONVENTIONS, INTEGRATIONS, TESTING and CONCERNS. It works in phases: run a scan script, read intent documents such as a README, PRD or roadmap, investigate each area, fill in the templates, then validate all seven.

When should I use Acquire Codebase Knowledge?

Acquire Codebase Knowledge fits situations like: onboarding to an existing repository you have not worked in before; documenting the architecture and conventions of a codebase; creating a set of codebase docs grounded in the actual files; finding where a project's stated intent and its code have drifted apart.

How do I install Acquire Codebase Knowledge in Claude Code?

Run `npx skills add github/awesome-copilot --skill acquire-codebase-knowledge -a claude-code`. Or copy the skill folder (skills/acquire-codebase-knowledge in github/awesome-copilot) into .claude/skills/acquire-codebase-knowledge in your project. Claude Code loads it when a task matches its description.

How do I install Acquire Codebase Knowledge in Codex?

Run `npx skills add github/awesome-copilot --skill acquire-codebase-knowledge -a codex`. Or copy the skill folder (skills/acquire-codebase-knowledge in github/awesome-copilot) into .agents/skills/acquire-codebase-knowledge in your project. Codex loads it when a task matches its description.

Can I use Acquire Codebase Knowledge in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add github/awesome-copilot --skill acquire-codebase-knowledge -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/acquire-codebase-knowledge, .gemini/skills/acquire-codebase-knowledge, .github/skills/acquire-codebase-knowledge and .opencode/skills/acquire-codebase-knowledge in your project.

What does Acquire Codebase Knowledge need to run?

Going by SKILL.md and its folder, Acquire Codebase Knowledge needs Python for the scripts in its folder and the command-line tools its instructions call (python3). Our summary lists: Python 3.8+; git. Compatibility (from SKILL.md): Cross-platform. Requires Python 3.8+ and git. Run scripts/scan.py from the target project root..

Does Acquire Codebase Knowledge access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Acquire Codebase Knowledge safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. The check reads SKILL.md only: the scripts in the folder are not scanned, so read them before running anything.

What licence does Acquire Codebase Knowledge use?

Acquire Codebase Knowledge is published under the MIT licence (declared in SKILL.md). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Acquire Codebase Knowledge use?

About 2.3k tokens (SKILL.md is roughly 9.1k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 2.5k tokens, read only when the agent opens those files.

What are the alternatives to Acquire Codebase Knowledge?

Skills that share tags, products or a category with Acquire Codebase Knowledge: BiSheng Approval Module Reference (dataelement/bisheng, 12k stars), BTCA Local Repo Search (stickerdaniel/linkedin-mcp-server, 3.8k stars), Jgrep (keltokhy/jgrep, 136 stars) and Local File and Code Search (taxueseek/argo, 184 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Acquire Codebase Knowledge?

github (a GitHub organization, an official publisher) maintains it in github/awesome-copilot, which has 39,748 GitHub stars. The repository holds 417 skills in this directory. The repository was last updated on October 7, 2026.

Source: github/awesome-copilot on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.