wiki-init

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

wiki-init

Use this skill to initialize or migrate a repo into the wiki + QMD + agent hook pattern.

The user may use natural language. Route intent like this:

"como esta a estrutura?", "preciso migrar?", "doctor", "qmd esta ok?" -> run
```
doctor
```
.
"instala", "prepara esse repo", "configura hooks" -> run
```
install
```
as dry-run first, then ask the user to confirm the suggested wiki location and index before
```
--write
```
.
"migrar para o formato novo" -> run
```
migrate
```
as dry-run first, then ask the user to confirm the suggested wiki location and index before
```
--write
```
.
"corrigir qmd", "managed qmd", "patch qmd" -> run
```
doctor
```
, then use
```
install --write
```
or
```
update-hooks --write
```
with explicit approval to prepare the managed QMD checkout and wrappers.

使用本技能可将代码仓库初始化或迁移至wiki + QMD + agent钩子模式。

用户可能会使用自然语言表述需求，按以下方式识别意图：

"como esta a estrutura?"、"preciso migrar?"、"doctor"、"qmd esta ok?" → 执行
```
doctor
```
命令。
"instala"、"prepara esse repo"、"configura hooks" → 先以试运行模式执行
```
install
```
，然后在执行
```
--write
```
前，询问用户确认建议的wiki位置和索引。
"migrar para o formato novo" → 先以试运行模式执行
```
migrate
```
，然后在执行
```
--write
```
前，询问用户确认建议的wiki位置和索引。
"corrigir qmd"、"managed qmd"、"patch qmd" → 执行
```
doctor
```
，然后在获得明确批准后，使用
```
install --write
```
或
```
update-hooks --write
```
来准备托管式QMD检出和包装器。

Project root

项目根目录

All paths in this skill (

wiki/

AGENTS.md

CLAUDE.md

.mcp.json

, hook scripts, etc.) are relative to the project root passed via

--project <path>

, not the agent's current working directory.

Always pass
```
--project <absolute-or-relative-path>
```
to the script — it does not fall back to CWD silently.
The QMD wrapper commands (
```
<wrapper> collection add <wiki-path>
```
) accept absolute paths; prefer absolute paths when the agent CWD might differ from the project root.
When invoked from a sibling repo (e.g., meta/skills repo while the target project lives elsewhere), confirm the
```
--project
```
value with the user before
```
--write
```
.

本技能中的所有路径（

wiki/

、

AGENTS.md

、

CLAUDE.md

、

.mcp.json

、钩子脚本等）都是相对于通过

--project <path>

传入的项目根目录，而非Agent的当前工作目录。

务必向脚本传入
```
--project <绝对或相对路径>
```
——它不会默认回退到当前工作目录。
QMD包装器命令（
```
<wrapper> collection add <wiki-path>
```
）接受绝对路径；当Agent的当前工作目录可能与项目根目录不同时，优先使用绝对路径。
从同级仓库调用时（例如，在meta/skills仓库中操作其他位置的目标项目），在执行
```
--write
```
前需与用户确认
```
--project
```
的值。

Workflow

工作流程

Run

scripts/wiki-init.ts doctor --project <path>

first.

Read the report: wiki layout, AGENTS/CLAUDE, harnesses, hooks, cache migration, installed drift, and QMD status.
For changes, run
```
install
```
or
```
migrate
```
without
```
--write
```
and show the planned file actions plus the suggested topology.
Ask the user explicitly: local wiki or shared wiki? Do not silently default to a sibling path. Use the harness's structured-question tool (see Prompting).
- Local — wiki lives inside this repo at
```
wiki/
```
  . Default for standalone projects and private experiments.
- Shared — wiki lives outside this repo (sibling, central knowledge base, monorepo location). When the user picks shared, ask for the absolute or relative path in free-form text; detected siblings (
```
../knowledge-base
```
  , etc.) are suggestions the user must confirm or replace.
Confirm the QMD index name with the user (free-form input). Suggest a sensible default (project basename for local, organization or product name for shared) but let the user override.
Only run with
```
--write
```
after passing explicit
```
--wiki
```
and
```
--index
```
. The script blocks writes without those flags.
Re-run
```
doctor
```
after writes.
```
--write
```
prepares the managed QMD checkout under the skill cache (
```
~/.local/share/skills/qmd/checkouts/qmd
```
) and points project wrappers at that checkout. It clones
```
https://github.com/tobi/qmd.git
```
when missing and installs dependencies there.

If the target project needs an index, initialize QMD with the generated wrapper:

<wrapper> collection add <wiki-path> --name <index> --mask "**/*.md"

, then

<wrapper> update

and

<wrapper> embed

Run
```
scripts/validate-wiki-init.ts
```
before changing reusable templates or scripts.

首先执行

scripts/wiki-init.ts doctor --project <path>

。

读取报告：wiki布局、AGENTS/CLAUDE配置、工具集、钩子、缓存迁移、安装偏差以及QMD状态。
若需要变更，先不带
```
--write
```
执行
```
install
```
或
```
migrate
```
，展示计划的文件操作以及建议的拓扑结构。
明确询问用户：使用本地wiki还是共享wiki？ 不要默认使用同级路径。使用工具集的结构化提问工具（参见提示规范）。
- 本地——wiki位于当前仓库内的
```
wiki/
```
  目录下。适用于独立项目和私有实验的默认选项。
- 共享——wiki位于当前仓库外（同级目录、中央知识库、单体仓库位置）。当用户选择共享时，询问绝对或相对路径（自由文本输入）；检测到的同级路径（如
```
../knowledge-base
```
  等）仅作为建议，需用户确认或替换。
与用户确认QMD索引名称（自由文本输入）。建议合理的默认值（本地wiki使用项目基名，共享wiki使用组织或产品名称），但允许用户修改。
仅在传入明确的
```
--wiki
```
和
```
--index
```
参数后，才可执行带
```
--write
```
的命令。脚本在缺少这些标志时会阻止写入操作。
写入完成后重新执行
```
doctor
```
。
```
--write
```
会在技能缓存目录（
```
~/.local/share/skills/qmd/checkouts/qmd
```
）下准备托管式QMD检出，并将项目包装器指向该检出目录。当缓存缺失时，会克隆
```
https://github.com/tobi/qmd.git
```
并在其中安装依赖。

若目标项目需要索引，使用生成的包装器初始化QMD：

<wrapper> collection add <wiki-path> --name <index> --mask "**/*.md"

，然后执行

<wrapper> update

和

<wrapper> embed

。

修改可复用模板或脚本前，先执行
```
scripts/validate-wiki-init.ts
```
。

Prompting

提示规范

Follow the project-wide convention in

CLAUDE.md

AGENTS.md

("Skill Prompting Conventions"). Use the harness's structured-question tool —

AskUserQuestion

(Claude Code),

ask_user_question

(Codex), or

question

(OpenCode) — for the decision points below. Use free-form text only where a path or identifier is needed.

Decision point	Why structured	Suggested options
Wiki location	Branches the whole install: paths, hooks, presets	Local (in-repo `wiki/` ) · Shared (separate path)
Cache migration when legacy detected	Hard-to-undo copy operation	Copy now (preserve legacy) · Skip migration
Drift remediation when installed files diverge	Triggers `update-hooks --write`	Update all · Show diffs first · Ignore
Harness selection (multi-select) when more than one is detected	Avoids configuring agents the user doesn't want	claude · codex · opencode

After the answer, restate the choice in your own words before running

--write

Free-form prompts (no structured tool):

The shared wiki path
The QMD index name
Any custom QMD command (
```
--qmd-command
```
)
Any field where the user needs to type a value the skill cannot enumerate

遵循

CLAUDE.md

AGENTS.md

中的项目级约定（"Skill Prompting Conventions"）。针对以下决策点，使用工具集的结构化提问工具——Claude Code的

AskUserQuestion

、Codex的

ask_user_question

或OpenCode的

question

。仅在需要路径或标识符等用户输入值时使用自由文本。

决策点	使用结构化提问的原因	建议选项
Wiki位置	决定整个安装流程：路径、钩子、预设	本地（仓库内 `wiki/` ）· 共享（独立路径）
检测到旧版缓存时的缓存迁移	难以撤销的复制操作	立即复制（保留旧版）· 跳过迁移
已安装文件存在偏差时的偏差修复	触发 `update-hooks --write`	全部更新· 先显示差异· 忽略
检测到多个工具集时的工具集选择（多选）	避免配置用户不需要的Agent	claude · codex · opencode

收到用户回复后，用自己的话重述选择，再执行

--write

。

自由文本提示（不使用结构化工具）：

共享wiki路径
QMD索引名称
任何自定义QMD命令（
```
--qmd-command
```
）
任何需要用户输入技能无法枚举的值的字段

What the doctor reports

诊断命令报告内容

doctor

is the always-safe entry point. It reports:

wiki_path, qmd_index, recommended topology, and harness coverage.
Presence of canonical files (
```
AGENTS.md
```
,
```
CLAUDE.md
```
,
```
.wiki-guardrails.yml
```
, MCP/agent configs).
Markdown drift — tracked
```
.md
```
files outside the configured wiki path.
Cache migration — detects a legacy
```
~/.local/share/essential-skills/qmd
```
cache and reports whether
```
--write
```
will copy it to the current
```
~/.local/share/skills/qmd
```
location. The legacy directory is preserved (never deleted) for safety.
Installed drift — for every file the latest templates would generate, compares the on-disk content against the desired content. Reports stale paths (e.g., references to the legacy cache), outdated managed blocks in
```
AGENTS.md
```
/
```
CLAUDE.md
```
, and hooks/configs that fall behind the templates. The recommended fix is
```
wiki-init update-hooks --write
```
.
QMD status — managed checkout location, version, patch report, index status.
Planned actions — every file the next
```
install
```
/
```
migrate
```
/
```
update-hooks
```
run would create or update.

doctor

是始终安全的入口点。它会报告：

wiki_path、qmd_index、推荐的拓扑结构以及工具集覆盖情况。
标准文件的存在情况（
```
AGENTS.md
```
、
```
CLAUDE.md
```
、
```
.wiki-guardrails.yml
```
、MCP/Agent配置）。
Markdown偏差——已跟踪的
```
.md
```
文件位于配置的wiki路径之外。
缓存迁移——检测到旧版缓存
```
~/.local/share/essential-skills/qmd
```
，并报告执行
```
--write
```
时是否会将其复制到当前的
```
~/.local/share/skills/qmd
```
位置。为安全起见，旧版目录会被保留（永不删除）。
安装偏差——对于最新模板会生成的每个文件，将磁盘上的内容与预期内容进行对比。报告过时路径（例如，对旧版缓存的引用）、
```
AGENTS.md
```
/
```
CLAUDE.md
```
中过时的托管块，以及落后于模板的钩子/配置。推荐的修复方式是执行
```
wiki-init update-hooks --write
```
。
QMD状态——托管式检出位置、版本、补丁报告、索引状态。
计划操作——下一次
```
install
```
/
```
migrate
```
/
```
update-hooks
```
运行时会创建或更新的所有文件。

Script

脚本

Primary script:

bun skills/wiki-init/scripts/wiki-init.ts doctor --project .

QMD-focused alias:

bun skills/wiki-init/scripts/qmd-doctor.ts --project .

The script is intentionally dry-run by default. It writes only with

--write

Common examples:

bun skills/wiki-init/scripts/wiki-init.ts doctor --project /path/to/project
bun test skills/wiki-init/scripts/wiki-init.test.ts
bun skills/wiki-init/scripts/wiki-init.ts migrate --project /path/to/project --wiki ../knowledge-base --index my-index
bun skills/wiki-init/scripts/wiki-init.ts install --project /path/to/project
bun skills/wiki-init/scripts/wiki-init.ts install --project /path/to/project --wiki ../knowledge-base --index my-project --harness claude,codex,opencode --write

主脚本：

bun skills/wiki-init/scripts/wiki-init.ts doctor --project .

QMD专用别名：

bun skills/wiki-init/scripts/qmd-doctor.ts --project .

脚本默认以试运行模式运行，仅在带

--write

参数时才会写入。

常见示例：

bun skills/wiki-init/scripts/wiki-init.ts doctor --project /path/to/project
bun test skills/wiki-init/scripts/wiki-init.test.ts
bun skills/wiki-init/scripts/wiki-init.ts migrate --project /path/to/project --wiki ../knowledge-base --index my-index
bun skills/wiki-init/scripts/wiki-init.ts install --project /path/to/project
bun skills/wiki-init/scripts/wiki-init.ts install --project /path/to/project --wiki ../knowledge-base --index my-project --harness claude,codex,opencode --write

Presets

预设

Use

references/presets.md

for the supported project shapes: local wiki, central sibling wiki, multi-repo org wiki, and docs-only migration.

参考

references/presets.md

获取支持的项目类型：本地wiki、中央同级wiki、多仓库组织wiki以及仅文档迁移。

Wiki content scaffolding

Wiki内容脚手架

wiki-init

configures infrastructure (configs, hooks, MCP, QMD wrapper) but does not create the wiki content. After

install --write

, the agent must create the minimum wiki scaffolding the other wiki skills assume:

<project-root>/wiki/
├── index.md          # navigable catalog
├── CONVENTIONS.md    # schema, frontmatter, naming, audience separation
├── log.md            # append-only operation log
├── business/         # business/product rules (audience: business)
├── apps/             # app-level technical docs (audience: dev)
├── ops/              # operational procedures (audience: ops)
├── data/             # data models and schemas (audience: dev)
└── sources/          # ingested source summaries (one per slug)
<project-root>/raw/
└── index.md          # raw source materials inventory

The audience separation and frontmatter conventions are defined by

wiki-ingest/SKILL.md

. Treat that as the source of truth for naming, frontmatter, and content layout when scaffolding.

After scaffolding, initialize the QMD index per step 9 of the workflow.

wiki-init

负责配置基础设施（配置文件、钩子、MCP、QMD包装器），但不会创建wiki内容。执行

install --write

后，Agent必须创建其他wiki技能所需的最小wiki脚手架：

<project-root>/wiki/
├── index.md          # 可导航目录
├── CONVENTIONS.md    # Schema、前置元数据、命名规则、受众区分
├── log.md            # 追加式操作日志
├── business/         # 业务/产品规则（受众：业务人员）
├── apps/             # 应用级技术文档（受众：开发人员）
├── ops/              # 操作流程（受众：运维人员）
├── data/             # 数据模型与Schema（受众：开发人员）
└── sources/          # 导入的源内容摘要（每个slug对应一个文件）
<project-root>/raw/
└── index.md          # 原始源材料清单

受众区分和前置元数据约定由

wiki-ingest/SKILL.md

定义。搭建脚手架时，以此作为命名、前置元数据和内容布局的权威依据。

搭建完成后，按照工作流程第9步初始化QMD索引。

Boundaries

边界限制

Do not auto-ingest wiki content. Hooks only raise signal; the agent decides semantically.
Do not patch or install QMD globally.
Prefer a managed project wrapper for QMD over shell aliases or
```
bunx
```
. The wrapper must be accompanied by a provenance manifest recording the managed checkout, upstream repo/ref, wrapped binary, version, patch report, language, and embedding model.
Keep reusable skill files free of user-specific absolute paths. Local absolute paths may appear only in generated per-machine wrappers/manifests/config after install.
Keep templates inside this skill directory.

不要自动导入wiki内容。钩子仅触发信号，由Agent进行语义决策。
不要全局修补或安装QMD。
优先使用项目托管式QMD包装器，而非shell别名或
```
bunx
```
。包装器必须附带来源清单，记录托管式检出、上游仓库/引用、包装的二进制文件、版本、补丁报告、语言以及嵌入模型。
可复用技能文件中不要包含用户特定的绝对路径。本地绝对路径仅可出现在安装后生成的每台机器专属的包装器/清单/配置中。
模板需保存在本技能目录内。