Acquire Codebase Knowledge
Turn an unfamiliar repo into evidence-backed architecture notes and a prioritized risk list before you change or ship anything.
Overview
Acquire Codebase Knowledge is an agent skill most often used in Build (also Idea research, Operate iterate) that produces evidence-backed architecture and prioritized codebase-concern reports from repository files.
Install
npx skills add https://github.com/github/awesome-copilot --skill acquire-codebase-knowledgeWhat is this skill?
- Six required architecture sections: style, flow, layers, patterns, risks, and file evidence
- Codebase concerns table with severity, evidence, impact, and suggested next actions
- Optional extensions: startup order, async topology, anti-pattern catalog, failure-mode analysis
- Evidence-first tables force file-backed claims instead of generic architecture guesses
- Reusable template for onboarding, audits, and pre-refactor discovery
- 6 required architecture sections
- 4–6 step system-flow narrative
- prioritized concerns table with severity column
Adoption & trust: 898 installs on skills.sh; 34.6k GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You are staring at a codebase you did not write and cannot explain its layers, flows, or top risks in one coherent brief.
Who is it for?
Solo builders onboarding to an existing service, auditing a fork before customization, or documenting structure before a large agent-assisted refactor.
Skip if: Greenfield projects with no code yet, or teams that already maintain current ADRs and want automated static-analysis-only dashboards with zero narrative.
When should I use this skill?
You need structured architecture and codebase-concern documentation grounded in repository evidence before changing or shipping code.
What do I get? / Deliverables
You get filled architecture and concern templates with file citations and a ranked risk table you can attach to plans, reviews, or iteration backlogs.
- Architecture document with style, flow, layers, patterns, risks, and evidence
- Codebase concerns matrix with severity and suggested actions
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Canonical shelf is Build because the primary output is structured documentation you create while working in the codebase, not a one-off idea brainstorm. Docs subphase fits the skill’s deliverables: architecture style, system flow, layer tables, patterns, and concern matrices grounded in file paths.
Where it fits
Map layers and integration points before deciding whether to fork a starter or build from scratch.
Produce an architecture brief your coding agent can reference for the next implementation sprint.
Attach a prioritized concerns table to a pre-merge review when scope touched core modules.
Refresh known architectural risks after incidents or dependency upgrades.
How it compares
Structured discovery template for narrative architecture maps—not a replacement for linters, SAST scanners, or live APM traces.
Common Questions / FAQ
Who is acquire-codebase-knowledge for?
Indie and solo developers who need fast, honest orientation to an existing repo before they commit to features, migrations, or ops changes.
When should I use acquire-codebase-knowledge?
During Idea research when evaluating a codebase to adopt; during Build docs when onboarding; during Ship review when framing risk; and during Operate iterate when refreshing technical-debt context.
Is acquire-codebase-knowledge safe to install?
Treat it like any third-party agent skill: review the Security Audits panel on this Prism page and only point the agent at repositories you are allowed to read.
SKILL.md
READMESKILL.md - Acquire Codebase Knowledge
# Architecture ## Core Sections (Required) ### 1) Architectural Style - Primary style: [layered/feature/event-driven/other] - Why this classification: [short evidence-backed rationale] - Primary constraints: [2-3 constraints that shape design] ### 2) System Flow ```text [entry] -> [processing] -> [domain logic] -> [data/integration] -> [response/output] ``` Describe the flow in 4-6 steps using file-backed evidence. ### 3) Layer/Module Responsibilities | Layer or module | Owns | Must not own | Evidence | |-----------------|------|--------------|----------| | [name] | [responsibility] | [non-responsibility] | [file] | ### 4) Reused Patterns | Pattern | Where found | Why it exists | |---------|-------------|---------------| | [singleton/repository/adapter/etc] | [path] | [reason] | ### 5) Known Architectural Risks - [Risk 1 + impact] - [Risk 2 + impact] ### 6) Evidence - [path/to/entrypoint] - [path/to/main-layer-files] - [path/to/data-or-integration-layer] ## Extended Sections (Optional) Add only when needed: - Startup or initialization order details - Async/event topology diagrams - Anti-pattern catalog with refactoring paths - Failure-mode analysis and resilience posture # Codebase Concerns ## Core Sections (Required) ### 1) Top Risks (Prioritized) | Severity | Concern | Evidence | Impact | Suggested action | |----------|---------|----------|--------|------------------| | [high/med/low] | [issue] | [file or scan output] | [impact] | [next action] | ### 2) Technical Debt List the most important debt items only. | Debt item | Why it exists | Where | Risk if ignored | Suggested fix | |-----------|---------------|-------|-----------------|---------------| | [item] | [reason] | [path] | [risk] | [fix] | ### 3) Security Concerns | Risk | OWASP category (if applicable) | Evidence | Current mitigation | Gap | |------|--------------------------------|----------|--------------------|-----| | [risk] | [A01/A03/etc or N/A] | [path] | [what exists] | [what is missing] | ### 4) Performance and Scaling Concerns | Concern | Evidence | Current symptom | Scaling risk | Suggested improvement | |---------|----------|-----------------|-------------|-----------------------| | [issue] | [path/metric] | [symptom] | [risk] | [action] | ### 5) Fragile/High-Churn Areas | Area | Why fragile | Churn signal | Safe change strategy | |------|-------------|-------------|----------------------| | [path] | [reason] | [recent churn evidence] | [approach] | ### 6) `[ASK USER]` Questions Add unresolved intent-dependent questions as a numbered list. 1. [ASK USER] [question] ### 7) Evidence - [scan output section reference] - [path/to/code-file] - [path/to/config-or-history-evidence] ## Extended Sections (Optional) Add only when needed: - Full bug inventory - Component-level remediation roadmap - Cost/effort estimates by concern - Dependency-risk and ownership mapping # Coding Conventions ## Core Sections (Required) ### 1) Naming Rules | Item | Rule | Example | Evidence | |------|------|---------|----------| | Files | [RULE] | [EXAMPLE] | [FILE] | | Functions/methods | [RULE] | [EXAMPLE] | [FILE] | | Types/interfaces | [RULE] | [EXAMPLE] | [FILE] | | Constants/env vars | [RULE] | [EXAMPLE] | [FILE] | ### 2) Formatting and Linting - Formatter: [TOOL + CONFIG FILE] - Linter: [TOOL + CONFIG FILE] - Most relevant enforced rules: [RULE_1], [RULE_2], [RULE_3] - Run commands: [COMMANDS] ### 3) Import and Module Conventions - Import grouping/order: [RULE] - Alias vs relative import policy: [RULE] - Public exports/barrel policy: [RULE] ### 4) Error and Logging Conventions - Error strategy by layer: [SHORT SUMMARY] - Logging style and required context fields: [SUMMARY] - Sensitive-data redaction rules: [SUMMARY] ### 5) Testing Conventions - Test file naming/location rule: [RULE] - Mocking strategy norm: [RULE] - Coverage expectation: [RULE or TODO] ### 6) Evidence - [path/to/lint-config] - [path/to/format-config] - [path/t