zwyin/paoding-skills

paoding-version-check

Check version consistency across a skill collection (marketplace, CHANGELOG, frontmatter, dist copies).

Vedi sorgente

Come usare

  1. Copia il comando e controlla il pacchetto prima di installarlo nel tuo ambiente agente.
  2. Controlla strumenti, credenziali e ambienti richiesti nel documento originale.
  3. Descrivi input e risultato desiderato; confronta l’output con le fonti.
npx skills add https://github.com/zwyin/paoding-skills --skill paoding-version-check

Prima di iniziare

  • L’installazione non include abbonamenti, quote API o accesso ai file.
  • Stelle e installazioni indicano attività, non un test indipendente di qualità o sicurezza.
Documento Skill originale

Contenuto dal repository con titoli, esempi, codice, tabelle, link e immagini preservati.

paoding-version-check — 版本一致性检查器

只读核对一个 skill 合集里所有版本号是否一致。不 bump、不改文件、不联网——读每一处版本声明,与 canonical(SKILL.md frontmatter)比对,不一致就报出来。

何时跑

  • 发版前:bump 完版本号、跑 release.sh 之后、commit/push 之前
  • 怀疑版本错乱:用户报告"显示旧版本""badge 不对""CHANGELOG 跟不上"
  • CI:每次 push 跑一次,版本漂移直接红灯
  • 接入新 skill 后:确认新 skill 的版本各处都挂上了

何时不跑(近邻误触发)

  • 升级依赖版本(npm install / pip install)→ 这是包管理,不是版本一致性
  • git log / 看 commit 历史 → 那是 git 的事
  • "帮我 bump 一下版本号" → 那是 release.sh 的动作,本 skill 只读不写
  • Python/Node 运行时版本、node_modules 版本冲突 → 与 skill 版本无关

怎么跑

bash
# 检查整个合集(默认当前目录)
python3 skills/paoding-version-check/scripts/validate_versions.py --root .

# 只查单个 skill
python3 skills/paoding-version-check/scripts/validate_versions.py --root . --skill paoding-project-walkthrough

# JSON 输出(给 CI / 其他工具消费)
python3 skills/paoding-version-check/scripts/validate_versions.py --root . --format json

# 严格模式(发版前建议):WARN 也算不通过
python3 skills/paoding-version-check/scripts/validate_versions.py --root . --strict

退出码:2 有 FAIL;默认模式只有 WARN 时 0(WARN 不阻塞 CI);加 --strict 时只有 WARN → 1(发版前体检用)。

报告解读

=== paoding-version-check ===
root: /path/to/paoding-skills
collection version: 0.9.4

[FAIL] CHANGELOG.md:3
      collection CHANGELOG latest: expected 0.9.4, found 0.9.0
      -> release.sh only rewrites existing entries; insert the missing version block

[WARN] dist/opencode/.opencode/skills/paoding-project-walkthrough/SKILL.md:3
      dist/opencode frontmatter: expected 1.6.5, found 1.6.4
      -> dist drift; rerun `bash scripts/convert.sh --all`

Summary: 1 FAIL, 5 WARN, 11 PASS (exit 2)

每条 finding 含:

  • 级别:FAIL(必须修,发版阻塞)/ WARN(可能要修,人工判断)/ PASS(默认不显示)
  • 位置:file:line
  • 期望/实际:canonical 应是多少,实际找到多少
  • 修复提示:一句话告诉你怎么修

检查项清单

合集层:

  • .claude-plugin/marketplace.json 的 collection version(semver 格式)
  • CHANGELOG.md 最新 ## [X.Y.Z] 条目 == collection version

每个 skill(canonical = SKILL.md frontmatter version):

  • .claude-plugin/plugin.json "version"
  • .claude-plugin/marketplace.json "version"
  • skill 自己的 CHANGELOG.md 最新条目
  • skill 自己的 README.md version badge
  • 合集 README.md / README.en.md 里该 skill 的 badge 存在且版本对
  • SKILL.md 正文里的 Phase 0 banner(> **Version X.Y.Z**)
  • SKILL.md 正文里的 --version 文档字符串
  • SKILL.md 正文里的启动版本串(如 Project Walkthrough vX.Y.Z,无 --version 前缀的形式)

dist 平台副本(WARN,不阻塞但提示):

  • dist/opencode、dist/cursor、dist/windsurf 里对应 skill 的 frontmatter + banner
  • 不一致 → 提示 rerun bash scripts/convert.sh --all(dist 是生成物,重跑就修复,不要手改)

测试字面量(WARN):

  • tests/*.py 里硬编码的版本字面量与 canonical 不符
  • 可能是过期断言(要改),也可能是测试 fixture 的假数据(忽略)—— hint 会提示区分

常见问题修复指引

报错根因修法
Phase 0 banner != frontmatterrelease.sh 的 sed 模式匹配不到 > **Version X.Y.Z** 格式手动改 SKILL.md banner,或扩展 release.sh 加这个模式
collection CHANGELOG 滞后release.sh 只能改写已存在的 ## [X.Y.Z] 标题,不会 insert手动补 CHANGELOG 条目
README badge != frontmatter手改版本号时忘了 badge手动改 badge URL,或让 release.sh 覆盖
dist 副本漂移改了 SKILL.md 但没重跑 convert.shbash scripts/convert.sh --all
测试字面量过期release.sh 改了版本但测试里的硬编码没动判断是断言还是 fixture 数据,分别处理

范围边界(不做什么)

  • 不 bump 版本:只读检查,不修改任何文件
  • 不检查 description 文本一致性:SKILL.md / plugin.json / marketplace.json 三处 description 措辞不同是已知问题,留给"触发契约优化"那步
  • 不管 frontmatter schema:字段规约(triggers / allowed-tools 该有什么)留给"skill 编写规范"
  • 不管自包含 / 进度披露:那是 checkselfcontained.py 和独立任务的职责
  • 不通用化(pilot 阶段):当前聚焦 paoding-skills 自己的结构,参数化已预留但未充分测试外部合集

与现有工具的关系

  • `skills/paoding-github-safe-publish/scripts/validate_skill.sh`:只覆盖 1 个 skill 的 4 处,本 skill 是它的泛化 + 扩展(合集层 + dist + banner + test 字面量)。两者可共存,本 skill 不替换它。
  • `scripts/check_self_contained.py`:检查 SKILL.md/references 不外链,与本 skill 正交。
  • `hooks/session-start` + `check_update.sh`:运行时通知用户远端有新版,与本 skill(静态校验本地一致性)正交。
dallo stesso repository

Altri Skills

Tutti gli Skills