zwyin/paoding-skills

paoding-version-check

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

소스 보기

사용 방법

  1. 설치 명령을 복사하고 자신의 에이전트 환경에 설치하기 전에 소스 패키지를 확인하세요.
  2. 필요한 도구, 인증 정보, 지원 환경은 원본 문서에서 확인하세요.
  3. 입력과 원하는 산출물을 설명하고 출처와 결과를 대조하세요.
npx skills add https://github.com/zwyin/paoding-skills --skill paoding-version-check

시작 전 확인

  • 설치에는 모델 구독, API 한도, 파일 접근 권한이 포함되지 않습니다.
  • 별점 수와 설치 수는 활동 지표이며 독립적인 품질·보안 검증이 아닙니다.
원본 Skill 문서

원본 저장소의 제목, 예시, 코드, 표, 링크, 이미지를 유지해 표시합니다.

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(静态校验本地一致性)正交。
같은 저장소의 Skills

더 많은 Skills

모든 Skills