llm-wiki-skill

LLM Wiki 技能

持续更新并扩展由相互链接的 Markdown 文件组成的持久化知识库。原始内容由人工整理，Agent 使用此技能收集、去重、交叉引用并将原始内容总结为结构化的 Markdown 文件。用户有以下需求时会启用此技能：

• 创建或启动 Wiki 或知识库
• 将原始内容导入、添加到 Wiki 或进行处理
• 询问有关 Wiki 或知识库的问题
• 检查、审计 Wiki 或进行健康检查，确保其状态良好

快速开始

目录结构

以下是 Wiki 目录结构示例：

llm-wiki/               # Layer 0: the root level wiki folder name
├── SCHEMA.md           # Layer 3: A document for User and LLM to co-evolve the wiki conventions, structure of wiki and tag taxonomy
├── index.md            # Always exists, regardless of SCHEMA.md definition. Catalog of everything, organizaed by categoies (entities, concepts etc), each page listed with a link and a one-line summary
├── log.md              # Always exists, regardless of SCHEMA.md definition. Chronological action log (append-only, rotated yearly)
├── raw/                # Layer 1: Always exists, regardless of SCHEMA.md definition. Immutable content curated by humans
│   ├── documents/      # Web articles, clippings, PDFs
│   └── assets/         # Images, diagrams referenced by sources
├── generated/          # Layer 2: Always exists, regardless of SCHEMA.md definition. LLM-generated directories and markdown files
│   ├── entities/       # Always exists, regardless of SCHEMA.md definition. Entity pages (people, orgs, products, models)
│   ├── topics/         # Always exists, regardless of SCHEMA.md definition. Topic pages (concepts, terms)
│   ├── comparisons/    # Side-by-side analysis (between entities or between topics)

接下来一节将介绍 3 个层级。Wiki 或知识库使用上述结构构建。由于 Agent 具有受限的文件系统权限，用户只能在 CLI Agent（Codex、Claude Code、Gemini 等）于 llm-wiki/（或用户自定义的文件夹名称）文件夹根目录中启动时应用此技能；这意味着其下应有 SCHEMA.md、index.md、log.md 以及 raw/、generated/ 文件夹。如果用户在 Wiki 子文件夹中的其他位置启动 CLI Agent，此技能将会中止。

index.md 模板

索引按类型划分。每个条目占一行：Wiki 链接 + 摘要。

# Wiki Index

> Format: `## Last Updated: [YYYY-MM-DDThh:mm:ss] | subject | Total pages: N`
> Subject: the term (entity/topic/comparison etc)
> Total pages: how many pages the term is brought up

## Entities


## Topics

## Comparisons

log.md 模板

# Log File

> Format: `## [YYYY-MM-DDThh:mm:ss] action | subject | files`
> Actions: ingest, update, lint, archive, delete
> Subject: the summary of what happened within 300 characters
> Files: related files such as raw documents locations, generated wikis
> When log.md exceeds 500 entries, rotate: rename to log-YYYY.md, start fresh.

SCHEMA.md 模板

根据用户的偏好进行调整。Schema 用于约束 Agent 的行为并确保一致性：

# Wiki Schema

## Conventions
- Raw files can be broken down to several markdown files that live in `entities/`, `topics/` etc.
- Only create the wiki pages when an entity/topic is mentioned in 2+ sources or is central to one source.
- File names: lowercase, hyphens, no spaces (e.g., `transformer-architecture.md`)
- Every wiki page starts with YAML frontmatter (see below)
- Use `[[wikilinks]]` to cross-link between pages (minimum 2 outbound links per page)
- Every new or updated page must link to at least 2 other pages via `[[wikilinks]]`.
- When updating a page, always bump the `updated` date
- When new information conflicts with existing content:
   1. Check the dates — newer sources generally supersede older ones
   2. If genuinely contradictory, note both positions with dates and sources
   3. Mark the contradiction in frontmatter: `contradictions: [page-name]`
   4. Flag for user review

## Frontmatter
>  ---
>  title: Page Title
>  created: YYYY-MM-DDThh:mm:ss
>  updated: YYYY-MM-DDThh:mm:ss
>  type: entity | topic | comparison
>  sources: [raw/documents/source-name.md]
>  ---

## Layer 1 (User can specify, otherwise default to this file)

### Documents
Any single document in different formats user put in

### Assets
Any media files, images, video links etc.

## Layer 2 (User can specify, otherwise default to this file)

### Entities
One markdown page per notable entity. Include:
- Overview / what it is
- Key facts and dates
- Relationships to other entities ([[wikilinks]])
- Source references

### Topics
One markdown page per concept or topic. Include:
- Definition / explanation
- Current state of knowledge
- Open questions or debates
- Related concepts ([[wikilinks]])

### Comparison Pages
Side-by-side analysis in markdown. Include:
- What is being compared and why
- Dimensions of comparison (table format preferred)
- Verdict or synthesis
- Sources

架构

三个层级

第 1 层 — 原始内容： 不可变的目录和文件。Agent 可以读取，但绝不能修改。 第 2 层 — Wiki 或知识库： 由 Agent 管理的目录和 Markdown 文件。由 Agent 创建、更新并交叉引用。 第 3 层 — Schema： SCHEMA.md 定义 llm-wiki/（或用户自定义的文件夹名称）的约定和标签分类体系，以符合用户偏好。

创建新 Wiki

1. 询问用户对第 0 层的偏好，然后按照目录结构创建目录结构。
2. 询问用户对第 1 层和第 2 层目录结构的偏好，并打印目录结构以确认用户意图。
3. 根据 SCHEMA.md 打印约定；如果用户想要更改，则询问其偏好。
4. 根据第 2 步和第 3 步中的用户偏好，更新 SCHEMA.md 模板，并将其写入 SCHEMA.md。
5. 根据 index.md 模板创建初始 index.md，并添加分节标题。
6. 根据 log.md 模板创建初始 log.md，并添加创建记录。
7. 确认 Wiki 已就绪，并建议用户导入首批来源。

将原始内容导入 Wiki

1. 使用下面的代码块读取 raw/ 中的文件，输出每个文件的元数据列表，其中包含 mtime。

python3 $HOME/.agents/skills/llm-wiki-skill/scripts/ingest.py --collect ./raw

2. 读取 log.md 的最后一行以获取“日期时间”，并使用下面的代码块获取其 mtime

python3 $HOME/.agents/skills/llm-wiki-skill/scripts/ingest.py --iso-to-mtime "date time"

然后找出第 1 步中生成的、在“日期时间”之后添加的文件。 3. 根据 SCHEMA.md 中的约定部分，概括每个新添加的文件。 4. 找出在该日期时间之前和当天添加的文件，以便为第 4 步和第 5 步做准备。 5. 对于文件内容冲突，请参照 SCHEMA.md 中定义的约定部分。 6. 在 generated/ 下创建新文件、更新现有文件，并为其添加新的交叉链接。 7. 更新 index.md，并添加分节标题。 8. 更新 log.md，并添加创建记录。 9. 列出所有新添加或已更改的文件。

提出有关 Wiki 的问题

1. 在 index.md 中查找相关标题。
2. 在 Wiki 下找到类似页面，并根据 SCHEMA.md 总结，格式如“根据 [[page-1]]、[[page-2]]……”
3. 以 Markdown 格式呈现给用户。
4. 询问用户是否希望将答案存回 Wiki。如果希望，请执行以下步骤：
   • 如果不存在 queries/ 文件夹，则创建一个
   • 如果问题是关于比较的，将文件放入 comparisons/；否则放入 queries/
5. 使用分节标题更新 index.md。
6. 在 log.md 中添加创建记录。
7. 向用户列出所有刚创建的文件；只需列出文件名，无需展示内容。

检查 Wiki 的语法、审计或健康状况

注意： 以下是我们检查的 4 条规则。检查完后，在 log.md 中添加一条检查记录，主题应为“通过规则：N，未通过规则：M，未通过的规则及其 200 个字符以内的简要说明”。

1. 务必先阅读 SCHEMA.md，查找 Wiki 中的任何违规情况和未解决的矛盾。
2. 使用以下代码查找任何未链接到其他页面的孤立页面。输出为孤立页面的文件名列表。

python3 $HOME/.agents/skills/llm-wiki-skill/scripts/links.py --orphan ./generated

3. 使用以下代码查找任何失效（不可访问）的交叉链接。输出为文件名到该文件所有失效链接的字典。

python3 $HOME/.agents/skills/llm-wiki-skill/scripts/links.py --broken ./generated

4. generated/ 下的每个 Wiki 页面都应列在 index.md 中；标记任何未列出的页面。

规则（必须遵守）

• 任务完成时务必向用户发送消息，并遵循以下模板：

|-------您的请求已处理完毕！---------|

• 切勿修改 raw/ 中的文件——源文件不可更改。修正内容应写入 Wiki 页面。
• 务必先了解情况——在新会话中执行任何操作前，先阅读 SCHEMA、index 和近期日志。 跳过此步骤会导致重复和遗漏交叉引用。
• 务必更新 index.md 和 log.md——跳过此步骤会导致 Wiki 质量下降。这两者是导航的支柱。
• 不要创建没有交叉引用的页面——孤立页面无法被发现。每个页面都必须链接到至少另外 2 个页面。
• 必须包含 Frontmatter——它支持搜索、筛选和过期检测。
• 保持页面易于浏览——Wiki 页面应能在 30 秒内读完。超过 200 行的页面应拆分。将详细分析移至专门的深入分析页面。
• 批量更新前先询问——如果一次导入会涉及 10 个或更多现有页面，或创建 10 个或更多新页面，应先向用户确认范围。
• 轮换日志——当 log.md 超过 500 条记录时，将其重命名为 log-YYYY.md 并重新开始。Agent 应在检查时确认日志大小。
• 明确处理矛盾——不要悄悄覆盖。记录双方说法及日期，在 frontmatter 中标记，并提醒用户审查。