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.

Workflow

1. Run scripts/wiki-init.ts doctor --project <path> first.
2. Read the report: wiki layout, AGENTS/CLAUDE, harnesses, hooks, cache migration, installed drift, and QMD status.
3. For changes, run install or migrate without --write and show the planned file actions plus the suggested topology.
4. 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.
5. 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.
6. Only run with --write after passing explicit --wiki and --index. The script blocks writes without those flags.
7. Re-run doctor after writes.
8. --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.
9. 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.
10. Run scripts/validate-wiki-init.ts before changing reusable templates or scripts.

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

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.

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

Presets

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

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.