obsidian-upgrade

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Obsidian Upgrade

Obsidian wiki升级

Audit and upgrade Obsidian wikis to the current format.

审计并将Obsidian wiki升级至当前格式。

Canonical Spec (Single Source of Truth)

权威规范（唯一可信来源）

The canonical spec is
skills/obsidian-plan-wiki/SKILL.md
and its
references/
folder.

This upgrade skill does NOT enumerate requirements. It points agents at the canonical spec and tells them to diff against it. When the canonical spec changes, this skill automatically upgrades to match.

权威规范为
skills/obsidian-plan-wiki/SKILL.md
及其
references/
文件夹。

本升级技能不会枚举要求。它会引导Agent查阅权威规范，并与现有内容进行差异对比。当权威规范更新时，本技能会自动适配最新要求。

When to Use

使用场景

User mentions "upgrade wiki", "migrate wiki", "update wiki format"
Wiki has old-format comments, outdated docs, or legacy structure

用户提及“升级wiki”、“迁移wiki”、“更新wiki格式”
Wiki存在旧格式注释、过时文档或遗留结构

Upgrade Strategy

升级策略

Launch parallel subtask agents to audit each area. Each agent reads the canonical spec first, then diffs the existing wiki against it.

// Launch in parallel - each reads canonical spec then audits one area
Task(worker_type: "general-purpose", prompt: "Audit AGENTS.md against canonical spec...")
Task(worker_type: "general-purpose", prompt: "Audit comment format against canonical spec...")
Task(worker_type: "general-purpose", prompt: "Audit directory structure against canonical spec...")
Task(worker_type: "general-purpose", prompt: "Audit reference files against canonical spec...")
Task(worker_type: "general-purpose", prompt: "Audit wiki links...")

Collect all findings, then present one unified upgrade plan.

启动并行子任务Agent来审计各个领域。每个Agent先阅读权威规范，再将现有wiki与规范进行差异对比。

// Launch in parallel - each reads canonical spec then audits one area
Task(worker_type: "general-purpose", prompt: "Audit AGENTS.md against canonical spec...")
Task(worker_type: "general-purpose", prompt: "Audit comment format against canonical spec...")
Task(worker_type: "general-purpose", prompt: "Audit directory structure against canonical spec...")
Task(worker_type: "general-purpose", prompt: "Audit reference files against canonical spec...")
Task(worker_type: "general-purpose", prompt: "Audit wiki links...")

收集所有审计结果，然后生成统一的升级方案。

1. AGENTS.md Audit (CRITICAL)

1. AGENTS.md审计（关键项）

Most important check. Outdated agent instructions cause wrong output.

Task(
  worker_type: "general-purpose",
  prompt: "Audit docs/AGENTS.md against canonical spec.

  FIRST: Read the canonical spec completely:
  - skills/obsidian-plan-wiki/SKILL.md (entire file, especially AGENTS.md Template section)
  - ALL files in skills/obsidian-plan-wiki/references/

  THEN: Read docs/AGENTS.md completely.

  DIFF: Report every difference between existing AGENTS.md and the canonical template.
  For each difference:
  - Line number in existing file
  - What exists (quote exactly)
  - What canonical spec requires
  - Whether it's missing, outdated, or wrong

  The canonical spec is the authority. If it says something should exist, check for it.
  "
)

最重要的检查项。过时的Agent说明会导致输出错误。

Task(
  worker_type: "general-purpose",
  prompt: "Audit docs/AGENTS.md against canonical spec.

  FIRST: Read the canonical spec completely:
  - skills/obsidian-plan-wiki/SKILL.md (entire file, especially AGENTS.md Template section)
  - ALL files in skills/obsidian-plan-wiki/references/

  THEN: Read docs/AGENTS.md completely.

  DIFF: Report every difference between existing AGENTS.md and the canonical template.
  For each difference:
  - Line number in existing file
  - What exists (quote exactly)
  - What canonical spec requires
  - Whether it's missing, outdated, or wrong

  The canonical spec is the authority. If it says something should exist, check for it.
  "
)

2. Comment Format Audit

2. 注释格式审计

Task(
  worker_type: "general-purpose",
  prompt: "Audit all Obsidian comments in docs/ directory.

  FIRST: Read skills/obsidian-plan-wiki/SKILL.md section on Task Tracking with Obsidian Comments.
  Read skills/obsidian-plan-wiki/references/obsidian-open-questions-system.md if it exists.

  THEN: Find EVERY file with %% comments in docs/.

  DIFF: For each comment, check if it matches the canonical format.
  Report each violation with:
  - File path and line number
  - Current comment (quote exactly)
  - What canonical spec requires
  - Proposed fix
  "
)

Task(
  worker_type: "general-purpose",
  prompt: "Audit all Obsidian comments in docs/ directory.

  FIRST: Read skills/obsidian-plan-wiki/SKILL.md section on Task Tracking with Obsidian Comments.
  Read skills/obsidian-plan-wiki/references/obsidian-open-questions-system.md if it exists.

  THEN: Find EVERY file with %% comments in docs/.

  DIFF: For each comment, check if it matches the canonical format.
  Report each violation with:
  - File path and line number
  - Current comment (quote exactly)
  - What canonical spec requires
  - Proposed fix
  "
)

3. Structure Audit

3. 结构审计

Task(
  worker_type: "general-purpose",
  prompt: "Audit wiki directory structure in docs/.

  FIRST: Read skills/obsidian-plan-wiki/SKILL.md section on Directory Structure.

  THEN: List actual structure of docs/ directory.

  DIFF: Report differences between actual structure and canonical structure.
  Note any legacy patterns that don't match the current spec.
  "
)

Task(
  worker_type: "general-purpose",
  prompt: "Audit wiki directory structure in docs/.

  FIRST: Read skills/obsidian-plan-wiki/SKILL.md section on Directory Structure.

  THEN: List actual structure of docs/ directory.

  DIFF: Report differences between actual structure and canonical structure.
  Note any legacy patterns that don't match the current spec.
  "
)

4. Reference Files Audit

4. 参考文件审计

Task(
  worker_type: "general-purpose",
  prompt: "Audit reference files in docs/reference/.

  FIRST: List all files in skills/obsidian-plan-wiki/references/

  THEN: Check if corresponding files exist in docs/reference/

  DIFF: For each canonical reference file:
  - If missing in docs/reference/: note as missing
  - If exists: diff content and report differences
  "
)

Task(
  worker_type: "general-purpose",
  prompt: "Audit reference files in docs/reference/.

  FIRST: List all files in skills/obsidian-plan-wiki/references/

  THEN: Check if corresponding files exist in docs/reference/

  DIFF: For each canonical reference file:
  - If missing in docs/reference/: note as missing
  - If exists: diff content and report differences
  "
)

5. Broken Links Audit

5. 失效链接审计

Task(
  worker_type: "general-purpose",
  prompt: "Audit all wiki links in docs/ directory.

  For every [[wiki-link]] found:
  1. Check if target file exists
  2. Check if anchor (#section) exists in target
  3. Check for unclosed links

  Report each broken link with file, line, and issue.
  "
)

Task(
  worker_type: "general-purpose",
  prompt: "Audit all wiki links in docs/ directory.

  For every [[wiki-link]] found:
  1. Check if target file exists
  2. Check if anchor (#section) exists in target
  3. Check for unclosed links

  Report each broken link with file, line, and issue.
  "
)

Upgrade Plan Format

升级方案格式

Collect all subtask findings into one plan:

markdown

undefined

将所有子任务结果整合为一个方案：

markdown

undefined

Upgrade Plan: [Wiki Name]

1. AGENTS.md Fixes (CRITICAL)

Line	Current	Canonical Requires	Action
...	...	...	...

Line	Current	Canonical Requires	Action
...	...	...	...

2. Comment Upgrades

File	Line	Current	Canonical Format
...	...	...	...

File	Line	Current	Canonical Format
...	...	...	...

3. Structure Changes

Current	Canonical
...	...

Current	Canonical
...	...

4. Reference Files

File	Status
...	missing/outdated/ok

File	Status
...	missing/outdated/ok

5. Broken Links

File	Line	Link	Issue
...	...	...	...

File	Line	Link	Issue
...	...	...	...

Summary

AGENTS.md: X fixes (CRITICAL)
Comments: Y upgrades
Structure: Z changes
Reference files: N missing/outdated
Links: M broken

Approve? (y/n)

---

AGENTS.md: X fixes (CRITICAL)
Comments: Y upgrades
Structure: Z changes
Reference files: N missing/outdated
Links: M broken

Approve? (y/n)

---

Execution Order

执行顺序

Structure first (affects all paths)
AGENTS.md pointer (quick fix)
AGENTS.md documentation (so spec is correct)
Reference files (copy from canonical if missing)
Comments (now they match the spec)
Validate links (after all moves)
Report results

先处理结构（影响所有路径）
AGENTS.md指针修正（快速修复）
AGENTS.md文档更新（确保规范正确）
参考文件同步（缺失则从权威规范复制）
注释格式升级（使其匹配规范）
验证链接（所有移动操作完成后）
提交结果报告

Validation

验证

After upgrades, verify:

Task(
  worker_type: "general-purpose",
  prompt: "Validate wiki upgrade.

  Read: skills/obsidian-plan-wiki/SKILL.md and all references/

  Then verify docs/ matches the canonical spec:
  - AGENTS.md matches template
  - Comments match format
  - Structure matches spec
  - Reference files present
  - No broken links

  Report pass/fail for each with evidence.
  "
)

升级完成后，进行验证：

Task(
  worker_type: "general-purpose",
  prompt: "Validate wiki upgrade.

  Read: skills/obsidian-plan-wiki/SKILL.md and all references/

  Then verify docs/ matches the canonical spec:
  - AGENTS.md matches template
  - Comments match format
  - Structure matches spec
  - Reference files present
  - No broken links

  Report pass/fail for each with evidence.
  "
)