# Wiki Generation

> Generate or update formal wiki notes from one `.cache/source-id-analysis.md` handoff document.

- Skill: `vintlin/wiki-generation` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add vintlin/wiki-generation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/vintlin/wiki-generation/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: VintLin (https://skillmd.com/u/vintlin)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/vintlin/wiki-generation

---


# Wiki Generation

This skill reads one analysis handoff document and completes the note-compilation pass.

## Read First

- `references/generation-rules.md`

## Input And Output

- Input: one `.cache/<source-id>-analysis.md`
- Output:
  - created or updated notes under `wiki/`
  - processing report at `outputs/processing/<source-id>-report.md`
  - archived source under `archive/`
  - archived analysis under `archive/.cache/`

## Workflow

1. Load one handoff artifact.
   Treat `.cache/<source-id>-analysis.md` as the direct input. Reopen the raw source only if the handoff is clearly insufficient.

2. Decide the edit scope.
   Separate the work into:
   - permanent notes
   - reference notes
   - argument notes
   - structure notes

3. Write or update permanent notes.
   - One reusable claim, distinction, method, step, or question per note
   - Check whether each candidate repeats, extends, corrects, narrows, or challenges an existing permanent note before creating a new file
   - Update an existing permanent note when the source adds clearer wording, stronger evidence, a caveat, an example, a correction, or a source link for the same reusable claim
   - Create a new permanent note only when the candidate carries a distinct claim, method, distinction, question, or role in an argument chain
   - Keep `## Summary` and `## Note`
   - Preserve important links and needed images
   - Use Markdown emphasis when it materially improves readability
   - Turn raw candidate note units from the analysis file into formal permanent notes

4. Write or update reference notes.
   Create or update `wiki/reference-notes/` only for stable named items such as books, frameworks, methods, models, acronyms, or long-lived coined terms.
   Treat each reference note as a source-context anchor for a named object, not as an entrance note, argument container, or摘抄堆.
   Use it to preserve:
   - what the named object is
   - where it comes from
   - its core definition, components, and boundaries
   - which permanent notes are distilled from it

5. Place notes into argument notes.
   - Judge from argument fit first
   - Insert notes into existing chains when possible
   - Create a new argument note when needed
   - Use broad parent-question or meta-claim titles
   - Prefer short, natural parent-question titles; keep the title simpler than the summary
   - Keep titles natural but still conceptually precise; do not overcorrect into chatty or overly colloquial wording
   - Allow branches or `---` segmentation when the reasoning should not be forced
   - `argument-notes` only connect upward to `structure-notes` and downward to `permanent-notes`
   - Do not create `argument -> argument` links as a substitute for merging or insertion
   - In each evidence item, explain the note's role in the chain directly
   - Do not use filler transitions such as “上一条已经…”, “接着”, or “然后”
   - Write `argument-note` summaries as direct conclusions, not as self-referential introductions about what the note is doing
   - Do not begin summaries with low-information scaffolding such as “这条论点笔记回答的问题是：”, “回答：”, “这条链处理……”, or similar template phrasing
   - This step owns the final decision about insertion order, branch shape, and `supports` / `next` structure
   - Treat analysis-file argument matches as candidates, not as final placement
   - If no existing argument fits, create or revise an argument note in the same pass
   - Treat each argument note as one stable parent question or parent claim with a readable reasoning chain, not as a topic bucket or note container
   - Put scope qualifiers, edge cases, and narrowed conclusions into `## Summary` and `### 论据`, not into the title unless they are the irreducible core of the parent question
   - Title the note as a question a real person would naturally ask, not as an internal analysis label or compressed explanation
   - Prefer direct, human wording such as `如何提升编程能力？`, `如何沉淀经验？`, `创作如何发生？`, `如何提升作品的传播度？`
   - Avoid double-question titles such as `为什么要学X，以及X能力如何长出来？`; prefer the shorter parent question and move the other half into `## Summary`
   - Avoid definition-plus-comparison titles such as `什么是X，X与Y有何不同？`; prefer the core definition question and let the comparison become supporting evidence
   - Avoid explanatory endings such as `如何…真正长出来`, `如何…稳定沉淀`, `如何…并被约束`, `如何…并形成…`, `如何…并提高…` when the simpler question is still the same question
   - Avoid abstract mechanism names such as `飞轮`, `闭环`, `框架`, `模型`, `可操作性层级`, `系统设计与维护边界` as titles unless that mechanism name is itself the exact object under discussion
   - If the title sounds like a sentence written by the analyst rather than a question asked by the reader, rewrite it

6. Attach argument notes to structure notes.
   Every new or updated argument note must be linked from at least one relevant `wiki/structure-notes/`.
   `structure-notes` only collect `argument-notes`; do not link them to other `structure-notes` or `permanent-notes`.
   Decide structure placement only after the final argument shape is stable.
   Treat each structure note as a theme note: define the theme boundary, state what it covers and excludes, and list the few argument notes that are the correct entry paths.

7. Write the processing report.
   Write `outputs/processing/<source-id>-report.md`.
   Include review blocks only for issues that cannot be resolved stably.

8. Finalize archival state.
   - move the processed source into `archive/`
   - move `.cache/<source-id>-analysis.md` into `archive/.cache/`
   - create `archive/.cache/` when needed

## Hard Rules

- Do not create orphan permanent notes.
- Do not create a new permanent note when an existing note can be updated without losing a distinct claim or argument role.
- Do not leave new argument notes unattached to the structure layer.
- Do not attach `structure-notes` to other `structure-notes`.
- Do not attach `structure-notes` directly to `permanent-notes`.
- Do not leave any `permanent-note` without at least one `argument-note` target; if no fit exists, create or revise an argument note in the same pass.
- Do not treat `source-analysis` candidate links as final chain instructions.
- Do not use narrow process-description titles for argument notes.
- Do not use unnatural, over-explained, or analysis-jargon argument titles.
- Do not treat argument notes as topic buckets or unordered note piles.
- Do not treat structure notes as portal pages, cross-link hubs, maintenance scratchpads, or raw note indexes.
- Do not silently drop source links, citations, or useful images.
- Do not use `wiki/reference-notes/` as an entrance layer.
- Do not use natural-language reference labels such as `来源文件：`, `来源链接：`, or `主题来源：`; normalize to `from` / `references` / `url`.
- Do not use `related_pattern` or other pseudo-structural link labels inside `reference-notes`.

## Completion Test

The pass is complete only when:
- wiki notes are updated as needed across permanent / reference / argument / structure layers
- new notes are placed into argument chains
- affected argument notes are attached to structure notes
- source provenance remains visible
- `outputs/processing/<source-id>-report.md` exists
- the processed source has moved to `archive/`
- the completed analysis file has moved to `archive/.cache/`