TARE-Learn/deliverables/ai-engineering-skills-delivery/skills/project-knowledge-builder/SKILL.md

name, description

name	description
project-knowledge-builder	Use when a user asks “项目知识库”, “看项目”, “整理项目”, or otherwise wants to inspect a software project deeply, build/refresh a project knowledge base, create onboarding docs, architecture maps, domain glossaries, ADRs, generated API/config/database indexes, or RAG-ready repository documentation.

Project Knowledge Builder

Overview

Build a source-grounded project knowledge base that helps humans and AI agents understand, extend, troubleshoot, and index a codebase. Treat the knowledge base as a maintained system artifact, not a README rewrite.

Quick Use

Users should not need to remember commands, script paths, or $project-knowledge-builder.

The shortest trigger is enough:

• 项目知识库

Treat the current repository as the target and docs/project-knowledge/ as the output path unless the user says otherwise. Run the bundled inventory script yourself and write the docs. Only show manual commands when the user explicitly asks for command-line usage.

Language And Audience Defaults

If the user writes in Chinese or asks for Chinese, write human-facing narrative docs in Chinese by default: README, context, architecture, runtime, backend, frontend, data, auth/permissions, extension, troubleshooting, RAG guidance and ADRs. Keep source paths, class names, commands, API paths, config keys, table names, permission codes and metadata enum values unchanged.

Treat beginners as a primary audience. A useful knowledge base should let a new maintainer answer four questions without extra coaching:

1. What is this project and where are the main modules?
2. How do I run it locally or identify the active runtime mode?
3. How do I find the backend endpoint, frontend page, database table and permission code for a feature?
4. What must change when adding a normal feature, especially menu/button permissions?

Do not make generated indexes overly friendly at the cost of precision. Keep generated files machine-refreshable; make narrative docs readable.

Core Rule

Every claim must be traceable to the repository or to an explicitly marked inference. Prefer source paths, commands, generated inventories, and unresolved-question lists over confident prose.

Workflow

1. Set scope. Confirm or assume the output location. Default to docs/project-knowledge/. If the user mentions RAG, Feishu/Lark, Dify, Notion, onboarding, architecture review, or API docs, tailor the output contract.
2. Read local instructions first. Check root docs plus AGENTS.md, CLAUDE.md, GEMINI.md, .codex/, .agents/, package manifests, build files, env examples, Docker files, and module READMEs.
3. Generate an inventory. Run scripts/project_inventory.py from this skill against the repo. Use its output as a factual base, then inspect important files manually.
4. Map contexts. Identify bounded contexts, runtime modes, major modules, owners implied by paths, external systems, and data stores. Use CONTEXT.md and CONTEXT-MAP.md style docs.
5. Extract generated indexes. Produce machine-refreshable docs where possible: endpoints, frontend routes/views, config keys, env variables, database tables, permission codes, scheduled jobs, queues, and extension points.
6. Write human guides. Produce onboarding, architecture, local run/deploy, data model, auth/permission, extension, troubleshooting, and glossary docs. Match the user's language for narrative docs; for Chinese users, use Chinese section titles such as 已观察来源, 核心事实, 操作影响, and 未知与风险.
7. Create ADRs for real decisions. Record important architecture decisions already embodied in the code. Do not invent future decisions unless marked as proposed.
8. Add RAG metadata guidance. Include chunking, source-path metadata, stale-data policy, and exclusion rules.
9. Verify. Re-run the inventory, scan docs for placeholders, broken relative links, stale paths, and unsupported claims. Report what was verified and what remains uncertain.

Output Contract

Read references/output-contract.md when creating or upgrading a full knowledge base.

Minimum useful set:

docs/project-knowledge/
├── README.md
├── CONTEXT.md
├── CONTEXT-MAP.md
├── 01-architecture.md
├── 02-runtime.md
├── 03-backend.md
├── 04-frontend.md
├── 05-data-and-migrations.md
├── 06-auth-permissions.md
├── 07-extension-guide.md
├── 08-troubleshooting.md
├── 09-rag-indexing.md
├── adr/
│   └── 0001-current-runtime-architecture.md
└── generated/
    ├── project-inventory.md
    ├── backend-endpoints.md
    ├── frontend-routes.md
    ├── config-reference.md
    ├── database-dictionary.md
    └── permission-codes.md

Scale down only if the repo is small or the user requests a lighter artifact.

Source-Grounding Standards

• Cite source paths inline for non-obvious claims.
• Distinguish Observed from Inferred and Unknown.
• Do not summarize generated code, dependencies, or configs from memory. Read them.
• If external docs are needed for unstable facts, browse primary sources and link them.
• Preserve project-specific conventions. If a repo requires trace comments, ADR format, or issue IDs, document and follow that.

Cross-Platform Compatibility

Read references/compatibility.md when the user asks about macOS, Windows, Linux, CI, portability, or installing/running the skill across machines. The bundled inventory script is intended to run on Python 3.9+ with only the standard library.

Inventory Script

Use this only for manual refreshes or when the user asks for the command. Run from the target repo:

macOS/Linux:

python3 /path/to/skill/scripts/project_inventory.py --root . --out docs/project-knowledge/generated

Windows PowerShell:

py -3 C:\path\to\skill\scripts\project_inventory.py --root . --out docs\project-knowledge\generated

Useful options:

python3 /path/to/skill/scripts/project_inventory.py --root . --out ./kb-inventory --json
python3 /path/to/skill/scripts/project_inventory.py --root . --out docs/project-knowledge/generated --max-files 20000

The script is a starting point, not a replacement for reading core files. Inspect representative files before writing narrative docs.

Quality Gates

Before final response:

• List generated docs with a platform-appropriate command, such as find docs/project-knowledge -type f | sort on macOS/Linux or Get-ChildItem docs/project-knowledge -Recurse -File on PowerShell.
• rg -n "TODO|TBD|待补|unknown|your/path|foo|bar" docs/project-knowledge
• Re-run the inventory script after edits.
• Check that top-level README links resolve.
• If the user is Chinese, scan narrative docs for English-only structural headings such as Observed Sources, Core Facts, Operational Implications, Unknowns/Risks, Architecture, Runtime, Backend, Frontend, Troubleshooting, and translate them unless they are code, metadata, or generated output.
• Check newcomer usefulness: README gives a reading order; runtime doc names local/Docker/cloud modes; auth doc explains menu/button permission flow; extension doc explains backend CRUD, frontend page and permission changes.
• git status --short to report changed files.

If the user asked for “deep” or “落地”, do not stop at a single overview. Deliver generated indexes plus human guides.