sync-metadata

以 package.json 为唯一真相源（single source of truth），将项目名称、版本、描述等元数据同步到 README.md、SPEC.md 等 Markdown 文档中。

工作原理

1. 读取 package.json，解析所有顶层字段
2. 如果有 package.nls.json / package.nls.zh-CN.json，解析 %key% 占位符引用
3. 在目标文件中查找 \x3C!-- sync:FIELD -->...\x3C!-- /sync --> 标记
4. 用 package.json 中的实际值替换标记间的内容
5. 报告每个文件被更新了哪些字段

支持的字段

以下 package.json 字段均可通过 \x3C!-- sync:FIELD --> 同步：

嵌套字段用点号分隔：\x3C!-- sync:repository.url -->

使用方法

1. 在 Markdown 文件中添加标记

\x3C!-- README.md -->
# \x3C!-- sync:displayName -->AI History Auto Record\x3C!-- /sync -->

> \x3C!-- sync:description -->项目描述...\x3C!-- /sync -->

项目地址：[\x3C!-- sync:name -->](\x3C!-- sync:repository.url -->)

\x3C!-- SPEC.md -->
# SPEC: \x3C!-- sync:displayName -->AI History Auto Record\x3C!-- /sync -->

> **Version:** \x3C!-- sync:version -->0.0.1\x3C!-- /sync -->

2. 运行 Skill

在 Claude Code 中输入 /sync-metadata，或直接说"同步元数据"。

Skill 会自动：

• 扫描项目中所有 .md 文件里的 \x3C!-- sync:... --> 标记
• 与 package.json 比对
• 替换过期内容
• 输出变更摘要

3. 仅检查（CI 模式）

说"检查元数据是否同步"或"check metadata sync"，Skill 会只检查不修改，类似 --dry-run。

i18n 支持

如果项目有 package.nls.json 和 package.nls.zh-CN.json：

// package.nls.json
{ "displayName": "AI History Auto Record" }

// package.nls.zh-CN.json
{ "displayName": "AI历史自动记录" }

则 Skill 会：

• 默认使用 package.nls.json（英文）
• 当用户说"同步中文元数据"时使用 package.nls.zh-CN.json
• 如果字段值以 % 开头结尾（如 "%displayName%"），自动从 nls 文件解析

执行步骤

当用户调用此 Skill 时，按以下步骤执行：

1. 读取 package.json — 解析所有字段作为真相源
2. 读取 nls 文件（可选） — 如果有 package.nls.json，解析 %key% 引用
3. 扫描目标文件 — 用正则 \x3C!-- sync:([\w.]+) -->(.*?)\x3C!-- /sync --> 搜索所有 .md 文件
4. 比对差异 — 对比标记内的当前值与 package.json 中的值
5. 输出报告 — 列出每个文件的变更，格式：

📦 元数据同步报告
─────────────────
README.md
  displayName: "AI History Auto Record" → ✅ 已同步
  version:     "0.0.1" → "0.1.0"        ✏️ 已更新
  description: "自动追踪..." → ✅ 已同步

SPEC.md
  version:     "0.0.1" → "0.1.0"        ✏️ 已更新
─────────────────
2 个文件，2 处更新

6. 用户确认后写入 — 展示变更后，征得用户确认再实际修改文件

最佳实践

• 版本号用 \x3C!-- sync:version --> 标记，发版后一键同步
• 项目描述统一用 \x3C!-- sync:description -->，改 package.json 后 README/SPEC 自动跟上
• 仓库地址用 \x3C!-- sync:repository.url -->，迁移仓库后不用手动改 README
• 不要把所有内容都标记，只标记跨文件重复的元数据