version-sync-skill v1.0

版本迭代 + 文件同步控制 — 升版時自動同步 README、CHANGELOG、所有文件。文件永遠不落後版本。

Version iteration control for AI agents. Bump version → docs stay in sync. Never publish with outdated README again.

痛點 / The Problem

你：升版到 3.5.0，發布到 npm
AI：✅ npm publish 成功！

（三天後）
用戶：你的 README 還寫 v3.1...
你：......

版本升了，文件沒跟上 = 每次都踩同一個坑。

解法 / The Solution

你：升版
AI：掃描版本地圖... 發現 README 落後... 已同步更新 5 處引用 ✅

一鍵安裝 / One-Click Install

方法一：npx（推薦）

npx version-sync-skill install

自動偵測 AI agent 平台，安裝到正確位置：

🔄 version-sync-skill installer

Detected 2 platform(s):

  ✅ Claude Code → ~/.claude/skills/version-sync/SKILL.md
  ✅ Cursor → .cursor/rules/version-sync.mdc

✨ Done! Use /version-sync or say '升版' to bump version with doc sync.

方法二：npm 全域安裝

npm install -g version-sync-skill
version-sync-skill install

方法三：手動

git clone https://github.com/redredchen01/version-sync-skill.git

各平台手動複製：

# Claude Code
mkdir -p ~/.claude/skills/version-sync
cp version-sync-skill/SKILL.md ~/.claude/skills/version-sync/SKILL.md

# Cursor
cp version-sync-skill/SKILL.md .cursor/rules/version-sync.mdc

# Cline / Roo Code
cp version-sync-skill/SKILL.md .cline/rules/version-sync.md

# Codex / Gemini CLI / Amp
cat version-sync-skill/SKILL.md >> AGENTS.md

移除 / Uninstall

npx version-sync-skill uninstall

支援平台 / Supported Agents

| Agent | 安裝方式 | |-------|---------| | Claude Code | ~/.claude/skills/version-sync/ | | Cursor | .cursor/rules/version-sync.mdc | | Windsurf | .windsurf/rules/version-sync.md | | Cline | .cline/rules/version-sync.md | | Roo Code | .roo/rules/version-sync.md | | OpenClaw | ~/.openclaw/skills/version-sync/ | | Codex | AGENTS.md (bootstrap) | | Gemini CLI | GEMINI.md (bootstrap) | | Amp | AGENT.md (bootstrap) | | GitHub Copilot | .github/copilot-instructions.md (bootstrap) |

使用方式 / Usage

用任何語言說「升版」：

| 語言 | 觸發詞 | |------|--------| | 中文 | 升版、版本更新、同步文件 | | English | bump version, update version, sync docs with version | | 日本語 | バージョンアップ |

或直接呼叫

/version-sync

功能 / Features

1. 版本地圖掃描

自動找出所有包含版本號的檔案，一眼看到哪些落後：

版本地圖 (Version Map):
  配置檔:
    ✅ package.json        → 3.5.0
    ✅ SKILL.md            → 3.5.0
  文件檔:
    ⚠️  README.md:1        → "# session-wrap v3.1"  ← 落後！
    ✅ CHANGELOG.md        → 有 v3.5 條目

2. 智慧版本升級

目前版本: 3.5.0
升版類型？
  patch  → 3.5.1    修 bug
  minor  → 3.6.0    新功能
  major  → 4.0.0    破壞性變更
  跳過   → 只同步文件

一次性更新所有配置檔：package.json、pyproject.toml、SKILL.md、VERSION...

3. 文件自動同步（核心）

| 更新項目 | 動作 | |---------|------| | README 標題 | # project v3.1 → # project v3.5 | | 功能段落 | 自動從 git log 生成新功能摘要 | | Changelog | 新增版本條目 + 日期 + 變更 | | 其他 docs | 掃描 + 更新舊版本引用 |

4. 歷史保護

Changelog 裡的舊版本號不會被改。只更新標題、描述、安裝指令中的當前版本引用。

5. 與 triple-publish 整合

/triple-publish
  └→ Pre-flight
  └→ Version bump
  └→ 🔄 Doc Sync (version-sync)  ← 自動插入
  └→ Commit
  └→ Publish

發布前強制同步，README 永遠跟上 npm/PyPI 上的版本。

支援的配置檔 / Supported Config Files

| 檔案 | 語言/平台 | |------|----------| | package.json | Node.js / npm | | pyproject.toml | Python / PyPI | | Cargo.toml | Rust / crates.io | | go.mod | Go | | SKILL.md | AI agent skill | | VERSION / VERSION.txt | 通用 | | __init__.py | Python | | setup.cfg | Python (legacy) |

常見問題 FAQ

Q: 會改到程式碼裡的版本常數嗎？ 不會。只負責配置檔（package.json 等）和 .md 文件。

Q: monorepo 怎麼辦？ 會問你要更新哪些 package。

Q: 沒有 changelog 怎麼辦？ 會在 README 末尾新增 changelog 段落。

Q: 可以只同步文件不升版嗎？ 可以。選「跳過」就只做文件同步。

版本歷史 / Changelog

| 版本 | 日期 | 變更 | |------|------|------| | v1.0 | 2026-03-26 | 初版：版本地圖掃描、智慧升版、文件自動同步、triple-publish 整合 |

Contributing

git clone https://github.com/redredchen01/version-sync-skill.git
cd version-sync-skill
# 修改 → 測試 → PR

License

MIT