---
name: project-knowledge-builder
description: 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:

```text
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:

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

Windows PowerShell:

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

Useful options:

```sh
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.