github/awesome-copilot

acquire-codebase-knowledge

Use this skill when the user explicitly asks to map, document, or onboard into an existing codebase.

查看源码

使用方法

  1. 复制安装命令,在自己的智能体环境安装前先检查源码包。
  2. 从原始文档核对所需工具、凭据和支持的宿主。
  3. 说明输入材料与期望交付物,并对照来源检查输出。
npx skills add https://github.com/github/awesome-copilot --skill acquire-codebase-knowledge

开始前需了解

  • 安装不包含模型订阅、API 额度或访问文件的权限。
  • 仓库星数和安装量反映活跃情况,不等于独立质量或安全测试。
仓库原始内容

按源仓库内容呈现,保留标题、案例、代码、表格、链接以及原文引用的演示图片。

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
  1. Search for PRD, TRD, README, ROADMAP, SPEC, DESIGN files and read them.
  2. 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].

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.py`Phase 1 — run first, before reading any code (Python 3.8+ required)
`references/inquiry-checkpoints.md`Phase 2 — load for per-template investigation questions
`references/stack-detection.md`Phase 2 — only if stack is ambiguous
`assets/templates/STACK.md`Phase 3 step 1
`assets/templates/STRUCTURE.md`Phase 3 step 2
`assets/templates/ARCHITECTURE.md`Phase 3 step 3
`assets/templates/CONVENTIONS.md`Phase 3 step 4
`assets/templates/INTEGRATIONS.md`Phase 3 step 5
`assets/templates/TESTING.md`Phase 3 step 6
`assets/templates/CONCERNS.md`Phase 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.

按任务相关推荐

来自同一仓库

更多 Skills

全部 Skills
github
官方

anti-ui-slop

Stop coding agents from shipping generic UI. Use UIZZE''s 800,000+ real web and iOS screens to build product-specific interfaces, define a design contract, cover required states, and run a hard finish gate. Use when designing, implementing, redesigning, critiquing, or pre-ship reviewing a web or iOS interface in Codex, Claude Code, Cursor, Copilot, or another coding agent. Trigger with "anti-ui-slop", "stop UI slop", "ground this UI in real screens", or "run the UI finish gate".

1小时安装量
7
GitHub Stars
4.1万
最近更新
11月20日
github
官方

javascript-typescript-jest

Best practices for writing JavaScript/TypeScript tests using Jest, including mocking strategies, test structure, and common patterns.

1小时安装量
4
GitHub Stars
4.1万
最近更新
11月20日
github
官方

multi-stage-dockerfile

Create optimized multi-stage Dockerfiles for any language or framework

24小时安装量
446
GitHub Stars
4.1万
最近更新
11月20日
github
官方

sql-code-review

Universal SQL code review assistant that performs comprehensive security, maintainability, and code quality analysis across all SQL databases (MySQL, PostgreSQL, SQL Server, Oracle). Focuses on SQL injection prevention, access control, code standards, and anti-pattern detection. Complements SQL optimization prompt for complete development coverage.

24小时安装量
437
GitHub Stars
4.1万
最近更新
11月20日