Code Wiki
Three commands, one file to write:
node <skill>/scripts/wiki.mjs brief <repo> # index + export facts + print the brief
→ you write .codexqa-wiki/<repo>/notes.json # names and sentences only
node <skill>/scripts/wiki.mjs build <repo> # validate + render one HTML file
The script owns every fact on the page: modules, sizes, call counts, groups,
the architecture diagram, public symbols, files, links, search. You own the
words: what the repo is, what each module does, and which reading path fits
which task. You never edit HTML, CSS, or diagrams.
<skill> is this skill's directory. <repo> is a local checkout (preferred).
README.md / README.zh-CN.md are for humans; do not load them.
Documents (load on demand)
| File |
Load when |
SKILL.md (this file) |
always |
| references/notes.md |
before writing notes.json |
| references/playbook.md |
one module only, index problems, persisting for the Web UI |
| references/cli.md |
codexqa missing, PATH, repo ids, maintenance |
Default flow
- Brief. Run
node <skill>/scripts/wiki.mjs brief <repo>. It indexes
incrementally, exports codexqa wiki inputs, and writes
.codexqa-wiki/<repo>/ with inputs.json, meta.json, brief.md, and a
notes.json scaffold (kept if it already exists). Read the printed brief:
groups, suggested paths, and per module its files, calls, callers, public
symbols, and key flows.
- Notes. Read references/notes.md, then fill
notes.json. Every P01-style id and group id in it must exist in the
brief. Write 简体中文 unless the user asked for English ("lang": "en").
- Build. Run
node <skill>/scripts/wiki.mjs build <repo>. If it prints
error: lines, fix those fields and rerun; they name the field and the fix.
check <repo> validates without writing HTML.
- Deliver. Tell the user the printed file path plus two or three lines on
what the wiki says. Do not paste the HTML or open it in chat.
The user only wants a quick look → build <repo> --draft right after
brief. The page uses rule-based names and says it is a draft. Offer to
write the notes afterwards.
Useful flags: brief --limit 8 (large repos), brief --lang en,
brief --skip-index (index is fresh), build --out FILE,
build --source-url 'https://host/repo/blob/{commit}/{path}' (file links
when the remote is not GitHub / GitLab / Gitee / Bitbucket).
Scenario routing
| User is asking… |
Do |
| What is this repo / module map / architecture wiki / knowledge graph |
Default flow |
| Where should I start reading / onboarding path |
Default flow; put the effort into guides |
| What does module X do / who does it talk to |
Answer from brief.md; deeper digest in playbook Explain one module |
| Store a rule-only wiki for the CodexQA Web UI |
playbook Persist rule-only wiki |
brief failed / empty export / wrong branch |
playbook Index health |
Change review, callers of a symbol, test gaps, and stack traces belong to
codexqa-code-analyzer.
Rules
- Facts come only from this run's export. Do not add modules, calls, or
responsibilities that the brief does not support; do not use the README or
a website as evidence for a module's role.
- A reading path follows real calls: each step must call or be called by the
next.
build rejects anything else and lists the valid neighbours.
- Standalone modules (no calls to or from other modules) get a name and a
role, never a layer.
- Write for someone who just cloned the repo. No internal field names
(
deps, cross_community, called_by, wiki inputs); build rejects
them.
- Do not run
codexqa wiki without --no-llm, wiki embed, or query wiki.
Those call a model or need model-written pages.
- Do not hand-edit the generated HTML. Change
notes.json and rebuild.
1---2name: codexqa-code-wiki3description: >4 Builds a local architecture wiki for a repository from the CodexQA symbol5 graph (no model needed): modules, who calls whom and how often, reading6 paths, and one self-contained HTML page. Use when the user mentions7 codexqa-code-wiki, code-wiki, wiki, knowledge graph, architecture wiki,8 module map, reading guide, 代码知识图谱, 架构 Wiki, 模块地图, 阅读导览,9 wiki inputs, --no-llm, community detection, 社区检测, HTML 报告, or asks10 to map modules / generate a repo wiki without an LLM. Not change review11 (that is codexqa-code-analyzer), not CodexQA evidence-pack HTML review12 (that is codexqa-code-reviewer), and not SAST+agent code-risk scan reports13 (that is codexqa-defect-analyzer). Former skill name: code-wiki.14license: Apache-2.015compatibility: >16 Requires Node.js >= 18 and the `codexqa` CLI17 (`npm i -g @openqa-cn/codexqa`) on PATH. Index and `wiki inputs` need no18 LLM. Data lives in ~/.codexqa/.19metadata:20 source: https://skillmd.com/skills/openqa-cn/codexqa-code-wiki21 author: open-source22 version: "2.0.0"23 open-standard: agentskills24---2526# Code Wiki2728Three commands, one file to write:2930```text31node <skill>/scripts/wiki.mjs brief <repo> # index + export facts + print the brief32 → you write .codexqa-wiki/<repo>/notes.json # names and sentences only33node <skill>/scripts/wiki.mjs build <repo> # validate + render one HTML file34```3536The script owns every fact on the page: modules, sizes, call counts, groups,37the architecture diagram, public symbols, files, links, search. You own the38words: what the repo is, what each module does, and which reading path fits39which task. You never edit HTML, CSS, or diagrams.4041`<skill>` is this skill's directory. `<repo>` is a local checkout (preferred).42`README.md` / `README.zh-CN.md` are for humans; do not load them.4344## Documents (load on demand)4546| File | Load when |47|---|---|48| `SKILL.md` (this file) | always |49| [references/notes.md](references/notes.md) | before writing `notes.json` |50| [references/playbook.md](references/playbook.md) | one module only, index problems, persisting for the Web UI |51| [references/cli.md](references/cli.md) | `codexqa` missing, PATH, repo ids, maintenance |5253## Default flow54551. **Brief.** Run `node <skill>/scripts/wiki.mjs brief <repo>`. It indexes56 incrementally, exports `codexqa wiki inputs`, and writes57 `.codexqa-wiki/<repo>/` with `inputs.json`, `meta.json`, `brief.md`, and a58 `notes.json` scaffold (kept if it already exists). Read the printed brief:59 groups, suggested paths, and per module its files, calls, callers, public60 symbols, and key flows.612. **Notes.** Read [references/notes.md](references/notes.md), then fill62 `notes.json`. Every `P01`-style id and group id in it must exist in the63 brief. Write 简体中文 unless the user asked for English (`"lang": "en"`).643. **Build.** Run `node <skill>/scripts/wiki.mjs build <repo>`. If it prints65 `error:` lines, fix those fields and rerun; they name the field and the fix.66 `check <repo>` validates without writing HTML.674. **Deliver.** Tell the user the printed file path plus two or three lines on68 what the wiki says. Do not paste the HTML or open it in chat.6970The user only wants a quick look → `build <repo> --draft` right after71`brief`. The page uses rule-based names and says it is a draft. Offer to72write the notes afterwards.7374Useful flags: `brief --limit 8` (large repos), `brief --lang en`,75`brief --skip-index` (index is fresh), `build --out FILE`,76`build --source-url 'https://host/repo/blob/{commit}/{path}'` (file links77when the remote is not GitHub / GitLab / Gitee / Bitbucket).7879## Scenario routing8081| User is asking… | Do |82|---|---|83| What is this repo / module map / architecture wiki / knowledge graph | Default flow |84| Where should I start reading / onboarding path | Default flow; put the effort into `guides` |85| What does module X do / who does it talk to | Answer from `brief.md`; deeper digest in [playbook](references/playbook.md) **Explain one module** |86| Store a rule-only wiki for the CodexQA Web UI | [playbook](references/playbook.md) **Persist rule-only wiki** |87| `brief` failed / empty export / wrong branch | [playbook](references/playbook.md) **Index health** |8889Change review, callers of a symbol, test gaps, and stack traces belong to90`codexqa-code-analyzer`.9192## Rules9394- Facts come only from this run's export. Do not add modules, calls, or95 responsibilities that the brief does not support; do not use the README or96 a website as evidence for a module's role.97- A reading path follows real calls: each step must call or be called by the98 next. `build` rejects anything else and lists the valid neighbours.99- Standalone modules (no calls to or from other modules) get a name and a100 role, never a layer.101- Write for someone who just cloned the repo. No internal field names102 (`deps`, `cross_community`, `called_by`, `wiki inputs`); `build` rejects103 them.104- Do not run `codexqa wiki` without `--no-llm`, `wiki embed`, or `query wiki`.105 Those call a model or need model-written pages.106- Do not hand-edit the generated HTML. Change `notes.json` and rebuild.