这次我们直接聊一个很实际的问题skill 的更新。如果你经常接触 Claude Code、Codex 这类 AI Code Agent 的 skill 生态你会发现一个尴尬的事实——今天是这个 skill 作者发了 v0.3明早起来一看已经更新到 v0.5 了要是作者凌晨又改了 prompt 模板或者修了一个解析 bug你可能完全不知道。等你在某个任务里发现输出质量不对去仓库里一查才发现原来这个 skill 已经更新了三个版本而你本地还在跑老版本。这个问题不是个别现象而是目前 skill 生态里一个很普遍的设计缺口发布端的版本更新不具备提醒能力消费端的 skill 运行又是本地快照模式。两边一叠加就出现了“作者更新越勤快用户越难跟上”的情况。这篇文章就以“skill 更新提醒机制”为主线拆解为什么 skill 的更新难以被感知以及从用户侧、分发侧、协议侧三个层面怎么补一套可落地的更新提醒方案。内容不涉及具体某个 skill 的私有实现只讲工程思路、目录结构、脚本设计和 API 调用模板你可以直接迁移到自己的 skill 项目里用。1. 核心能力速览在展开之前先把整个问题域和文章会涉及的“能力”汇总成一张速览表方便你快速判断这篇内容的适用度。能力项说明问题定位skill 发布端与消费端之间缺少版本变更通知通道核心痛点高频更新、无提醒、本地快照老版本继续运行适用对象skill 作者、skill 使用者、Agent 工具链维护者提醒方案层级用户侧本地检测、仓库侧Release/CI 通知、协议侧集成 manifest 元数据工程依赖Git、shell 脚本、JSON/YAML、GitHub Actions可选、Webhook 或 RSS可选是否支持批量任务支持可通过批量比对 manifest 清单扫描本地 skill 目录是否提供 API可选可自建一个轻量 API 服务托管 skill 元数据供客户端轮询硬件门槛无纯软件工程方案本文验证重点本地 skill 清单扫描、版本比对、更新推送流程这里要先声明一点本文不写死任何具体 skill 的版本号、接口地址或更新频率。原因很简单——每个 skill 的发布节奏和托管位置不同硬套一个数字没有意义。下面所有代码和流程都采用通用模板设计替换成你自己的仓库地址和字段即可。2. 为什么 skill 的更新难以被感知2.1 skill 的“本地复制”模式是根因大多数 skill 的安装方式本质上是一次性复制。比如把仓库里的 SKILL.md 拖到个人配置目录或者通过一条 install 命令把 skill 拉下来之后就和你本地环境绑定了。它不像 npm 包那样有 node_modules 与 package-lock.json 精确锁版本也不像 pip 包那样有 site-packages 的元数据目录。安装动作完成之后本地就是一个“快照”。所谓更新是作者在远端仓库的改动但本地不会自动同步。等到用户下次主动去仓库拉取或者重新安装才会得到新版本。所以第一个问题就是skill 的架构天然缺少“运行时检查更新”这一环。2.2 高频更新导致人工检查失效如果一个 skill 一年更新两次靠用户手动刷新问题不大。但现在热门 skill 的迭代节奏明显更快尤其是 Prompt 引导型 skill、Math 建模类 skill、UI 设计规范类 skill。作者发现一个 prompt 变量没写清楚或者某个步骤顺序会导致 Agent 理解偏差可能当天就改一版。这种高频节奏下人工去仓库看 Release Notes 的成本就变得很高。用户不会因为一个 skill 每天去刷一次 GitHub 页面哪怕是每周一次的批量检查也很容易漏掉中间版本。2.3 分发渠道没有“推送”能力现在 skill 的分发方式大概有三类GitHub 仓库分发用户自己 clone 或下载 release 包。云端 skill 库网站用户在线浏览描述、点击复制。命令行工具分发通过类似 skm、plug 等管理器安装。这三种渠道中GitHub 仓库本身是支持 Watch Release 的但很多用户根本没开skill 库网站大部分只做静态展示命令行管理器虽然可以支持 update 命令但需要用户手动执行。结论是没有任何一个默认的推送通道会主动告诉你“这个 skill 更新了”。这就是“没有更新提醒机制”的现状。2.4 缺少版本元数据协议更底层的原因是 skill 自身缺少标准化的版本描述文件。npm 有 package.jsoncrates 有 Cargo.tomlGo module 有 go.mod而 skill 目前没有一套统一协议。有些 skill 只有一个 SKILL.md连版本号都没有有些虽然写了 agent 感知的 version 字段但没有 release notes有些更新了 prompt 内容却不改版本号。没有元数据就没有比对的基础。你都不知道自己装的是 v1.0 还是 v1.1更不可能实现自动提醒。3. 更新提醒机制的方案选型在设计更新提醒机制之前先明确三个可选的实现层级从轻到重依次是3.1 用户侧手动化在 skill 仓库中提供一份CHANGELOG.md或UPDATE.md用户定期查看本地 skill 目录与远程仓库的差异手动决定要不要更新。优点实现成本最低作者只需要维护一份更新日志。 缺点依然依赖用户主动行为提醒能力弱。3.2 分发侧通知化在 GitHub 仓库开启 Release 版本的 Webhook通过 CI 或第三方平台把更新信息推送到用户群、邮件、RSS 或企业微信/钉钉机器人。优点用户被动接收提醒不依赖手动检视。 缺点需要仓库作者维护 CI 流程且通知者维度覆盖不了所有用户。3.3 协议侧自动化为 skill 增加一个skill.json或者skill.yaml元数据文件里面包含name、version、description、author、homepage、updated_at等字段。用户的本地工具定期读取所有 skill 的元数据与远端 manifest 对比提示“有 N 个 skill 可更新”。优点这是最接近 npm/pip 体验的方案可以做成批量扫描、批量更新。 缺点需要 skill 作者遵守协议也需要一套客户端工具支持。从长期维护的角度看第 3 层是正解但实际落地可以从第 1 层和第 2 层先做起再逐步升级到第 3 层。4. 环境准备与前置条件不管选择哪一层方案你都需要准备以下基础环境。4.1 本地工具清单Git用来克隆仓库、拉取远程版本信息。Shell 环境Windows 下建议 Git BashLinux/macOS 直接使用自带的 bash/zsh。Python 3可选如果要用脚本做 JSON 元数据比对Python 比较方便。jq可选处理 JSON 数据时使用。检查这些工具是否已安装git --version python --version jq --version如果没有 jq在 Ubuntu/Debian 上可以这样安装sudo apt update sudo apt install jq -ymacOS 使用brew install jq如果你的环境里没有 jq也可以用 Python 的 json 模块代替后面会给出对应方案。4.2 skill 目录路径确认你需要先找到本地存放 skill 的位置。不同 Agent 工具配置不同常见的路径可能包括~/.claude/skills~/.config/codex/skills你手动指定的某个工作目录比如./skills请根据你自己的配置确认目录位置下面的脚本都用变量SKILLS_DIR统一表示实际操作时替换成你的真实路径。4.3 远端仓库信息你需要知道 skill 的远端仓库地址例如SKILL_REPOhttps://github.com/yourname/your-skill-repo.git SKILL_MANIFEST_URLhttps://raw.githubusercontent.com/yourname/your-skill-repo/main/skill.json后面的脚本模板中都使用这两个变量。5. 为 skill 仓库补充版本元数据如果说前面几段是“讲问题、选方案”那从这一节开始就是“直接动手改”。先做成本最低、价值最高的一步给 skill 仓库补一份元数据文件。5.1 创建 skill.json在 skill 仓库根目录新增一个skill.json文件建议内容结构如下{ name: my-skill, version: 1.2.0, description: A skill for some specific task, author: yourname, homepage: https://github.com/yourname/my-skill, updated_at: 2025-01-10T09:00:00Z, changelog: [ { version: 1.2.0, date: 2025-01-10, change: 优化 prompt 变量解析逻辑 }, { version: 1.1.0, date: 2025-01-08, change: 修复图表生成步骤中的缩进问题 } ] }这个文件就是更新提醒机制的事实基础。没有它后面的版本比对、远程检查、Webhook 通知都无法成立。如果你不想额外维护 JSON 文件也可以把字段写在 SKILL.md 的 frontmatter 里。很多 skill 的 SKILL.md 自带 YAML frontmatter可以在头部增加version和last_updated字段。例如--- name: my-skill version: 1.2.0 last_updated: 2025-01-10 description: A skill for some specific task --- # 使用说明 ...这里更推荐单独维护skill.json原因是机器解析方便也方便后续做自动批量扫描。5.2 使用 CHANGELOG.md 提高变更透明度除了机器可读的元数据再维护一份人眼可读的CHANGELOG.md。每次发版都记录# Changelog ## [1.2.0] - 2025-01-10 ### Changed - 优化 prompt 变量解析逻辑 ## [1.1.0] - 2025-01-08 ### Fixed - 修复图表生成步骤中的缩进问题这一步对使用者非常友好。如果用户已经手动在 GitHub 仓库页面查看更新至少能一眼看出“这个版本改了什么”。5.3 将版本号写入 Release发布时尽量打 Git tag 和 GitHub Releasegit add skill.json CHANGELOG.md git commit -m feat: release v1.2.0 git tag v1.2.0 git push origin main --tags打 Release 不只是为了给用户看更重要的是为后面的 Webhook 和 CI 通知方案做铺垫。6. 用户侧更新检查脚本接下来实现一个本地扫描脚本。它的功能是扫描本地 skill 目录中的skill.json从远端拉取最新的版本信息比对后输出“哪些需要更新”。6.1 使用 curl jq 的快速版本#!/bin/bash SKILLS_DIR$HOME/.claude/skills MANIFEST_URLhttps://raw.githubusercontent.com/yourname/my-skill/main/skill.json echo 检查 skill 更新 for skill_dir in $SKILLS_DIR/*/; do skill_name$(basename $skill_dir) skill_json$skill_dir/skill.json if [ ! -f $skill_json ]; then echo [$skill_name] 缺少 skill.json跳过 continue fi local_version$(jq -r .version $skill_json) echo [$skill_name] 本地版本: $local_version # 远端 manifest 统一放在一个 URL 映射中 case $skill_name in my-skill) remote_json$(curl -s $MANIFEST_URL) ;; *) echo [$skill_name] 未配置远端地址跳过 continue ;; esac remote_version$(echo $remote_json | jq -r .version) if [ $local_version ! $remote_version ]; then echo [$skill_name] 有新版本: $remote_version建议更新 else echo [$skill_name] 已是最新版 fi done这段脚本的逻辑很清晰读取本地每个 skill 的版本然后拉取远端版本不一致就是有更新。6.2 使用 Python 实现跨平台版本比对如果你的环境主要在 Windows 上又不想装 jq用 Python 更稳。先准备一份本地映射文件skill_registry.json表示哪些目录对应哪个远端 manifest 地址{ my-skill: { local_dir: $HOME/.claude/skills/my-skill, remote_url: https://raw.githubusercontent.com/yourname/my-skill/main/skill.json }, another-skill: { local_dir: $HOME/.claude/skills/another-skill, remote_url: https://raw.githubusercontent.com/yourname/another-skill/main/skill.json } }然后用 Python 脚本执行批量检查import json import os import urllib.request from pathlib import Path def load_json(path): with open(path, r, encodingutf-8) as f: return json.load(f) def fetch_remote(url): req urllib.request.Request(url, headers{User-Agent: skill-update-checker}) with urllib.request.urlopen(req, timeout10) as resp: return json.load(resp) def main(): registry_path Path(skill_registry.json) if not registry_path.exists(): print(缺少 skill_registry.json) return registry load_json(registry_path) update_found False for skill_name, meta in registry.items(): local_dir Path(os.path.expandvars(meta[local_dir])) skill_json_path local_dir / skill.json if not skill_json_path.exists(): print(f[{skill_name}] 本地缺少 skill.json跳过) continue local_meta load_json(skill_json_path) local_version local_meta.get(version, 0.0.0) try: remote_meta fetch_remote(meta[remote_url]) remote_version remote_meta.get(version, 0.0.0) except Exception as exc: print(f[{skill_name}] 检查失败: {exc}) continue if local_version ! remote_version: update_found True local_date local_meta.get(updated_at, 未知) remote_date remote_meta.get(updated_at, 未知) print(f[{skill_name}] 可更新) print(f 本地版本: {local_version} (更新时间: {local_date})) print(f 远端版本: {remote_version} (更新时间: {remote_date})) else: print(f[{skill_name}] 已是最新版本 v{local_version}) if not update_found: print(所有 skill 均为最新版本) if __name__ __main__: main()执行方式python check_skill_updates.py这个脚本已经足够支撑一天一次或一周一次的批量任务检查。把它加入 crontab 或 Windows 计划任务就可以实现定时提醒。6.3 批量任务的输出优化如果本地有很多 skill建议把输出结果追加到一个日志文件里方便事后处理python check_skill_updates.py skill_update.log 21或者只输出需要更新的条目便于通知机器人抓取python check_skill_updates.py --outdated-only在实际实现里你可以在命令行参数解析中加入--outdated-only用最简单的方式过滤输出。7. 仓库侧的自动通知机制本地检测是用户侧方案还有一种情况是你是 skill 作者你想主动通知所有订阅者。这时可以在仓库侧把“更新提醒”做起来。7.1 基于 GitHub Webhook 的消息推送当你在 GitHub 仓库创建 Release 时GitHub 会发送一个release事件的 Webhook 到你的服务器或云函数。你只需要监听这个事件然后把更新信息推到你的通知渠道。简易 Python Web 服务模板如下from flask import Flask, request, jsonify import json app Flask(__name__) def send_notification(payload): # 这里替换成你的通知函数比如推送到群机器人 print(收到 Release 事件:, payload.get(action)) release payload.get(release, {}) tag_name release.get(tag_name) name release.get(name) html_url release.get(html_url) print(f新版本: {tag_name} - {name}) print(f发布地址: {html_url}) app.route(/webhook/release, methods[POST]) def handle_release(): payload request.json if payload and payload.get(action) published: send_notification(payload) return jsonify({status: ok}) if __name__ __main__: app.run(host0.0.0.0, port8080)在 GitHub 仓库 Settings - Webhooks 中添加这个地址选择Release事件即可。这个方案的前提是你有一个公网可访问的服务器。如果没有公网服务器可以退而求其次使用 RSS 订阅或者 GitHub Release 页面的 Atom Feed。7.2 通过 GitHub Actions 定时检查并推送如果你不想自建 Webhook 服务也可以在仓库中配置 GitHub Actions定时检查远端版本变化然后把变更信息推送出去。简单的工作流文件.github/workflows/check-update.yml模板如下name: check-skill-update on: schedule: - cron: 0 0 */2 * * jobs: check: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkoutv4 - name: Check latest release env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} run: | latest$(curl -s -H Authorization: token $GITHUB_TOKEN \ https://api.github.com/repos/yourname/my-skill/releases/latest) echo $latest | jq .tag_name - name: Notify run: | # 在这里调用你的通知脚本或 curl 推送命令 echo 有新版本发布通知订阅者这个模板的思路是每两天检查一次最新 Release如果发现新 tag 就触发通知动作。你可以把Notify步骤中的 echo 替换成实际的群机器人 curl 请求。7.3 群机器人推送示例如果你使用钉钉、飞书或企业微信只需要把版本信息拼成文本发给机器人即可。以钉钉群机器人为例一个通知 POST 请求可以写成curl -X POST https://oapi.dingtalk.com/robot/send?access_tokenYOUR_TOKEN \ -H Content-Type: application/json \ -d { msgtype: text, text: { content: skill my-skill 已更新到 v1.2.0请查看 changelog } }实际接入时请替换成你自己的应用身份和地址并确认有权限发送到目标群。8. 协议侧的未来演进方向上面的方案可以解决当前的大多数问题但从更长远的角度看skill 生态应该有一次“元数据标准化”的演进。8.1 统一 skill manifest 标准参考 npm、Homebrew、Cargo 的思路skill 可以有一个标准化的 manifest 文件。最小字段建议包括字段说明是否必填nameskill 名称必填version语义化版本号必填description简短描述必填author作者信息选填homepage项目主页推荐updated_at最后更新时间推荐dependencies依赖的其他 skill 或工具选填min_agent_version最低支持版本选填如果这个标准被广泛采纳所有 skill 管理器都能提供“列出可更新项”“一键更新所有 skill”的命令类似skill list --outdated skill update my-skill skill update --all8.2 本地 skill 管理器加入更新订阅未来的 skill 管理工具可以维持一个本地订阅索引记录skill 名称远端仓库地址本地安装版本远端最新版本上次检查时间然后在每次启动 Agent 时静默检查一次有新版时输出提示。这就是最接近“更新提醒机制”的理想体验。8.3 增量更新与依赖冲突更新提醒不只是通知“有新版本”还要处理“更新后是否影响现有工作流”。如果一个 skill 依赖另一个 skillA 更新后 B 可能不兼容。所以 manifest 中最好带上依赖声明。在协议不统一的现状下稳妥做法是更新时间尽量避开任务高峰期更新前备份旧版本。9. 常见问题与排查方法问题现象可能原因排查方式解决方案本地脚本找不到 skill.jsonskill 目录内没有元数据文件检查 skill 安装路径和文件结构手动补充 skill.json 或改用 SKILL.md 的 frontmatter远端 manifest 拉取失败URL 错误或网络受限用 curl 手动访问 URL 查看响应核对 raw 链接必要时配置代理版本比对一直提示“有更新”两边 version 字段格式不一致检查是否有多余空格或不同命名规则统一版本号格式例如 v1.2.0 或 1.2.0保持一致Webhook 收不到事件仓库 Webhook 未配置或服务器无公网地址查看 GitHub Webhook 最近投递记录改用 GitHub Actions 定时轮询方案更新后 skill 行为异常新版本与其他依赖不兼容对比新旧 changelog回滚旧版本更新前备份旧 skill 目录保留快速回滚能力Windows 下脚本无法执行没有 bash 环境检查 Git Bash 是否安装改用 Python 脚本不依赖 shelljq 命令不存在未安装 jq执行 jq --version安装 jq 或改用 Python 解析 JSON这套排查思路适用于大多数本地检查和自动通知场景。10. 最佳实践与使用建议10.1 对 skill 使用者给每个本地 skill 建立统一的目录结构统一放入skill.json元数据。定期运行检查脚本不要等 Agent 输出异常再排查。更新前记录当前行为基线。例如先用旧版本跑一个测试用例更新后再跑同样的用例对比输出差异。大版本更新和修 bug 的小版本更新分开评估。小版本可以直接跟大版本建议观察两天。保留一份已知可用版本的备份目录。10.2 对 skill 作者每次修改 SKILL.md 或脚本逻辑时同步更新skill.json中的version和updated_at。在 Release Notes 中写清楚改了什么、因为什么改、是否影响原有用法。如果变更涉及 prompt 行为变化最好给出旧版示例和新版示例的对比。不要频繁修改 skill 名称和入口文件名否则依赖该 skill 的用户会全部失效。可以考虑在 README 里加入一个醒目的更新时间徽章或最近的版本记录降低使用者的确认成本。10.3 对团队工具链维护者如果团队内部维护了一批 skill建议在 CI 脚本里加入更新检查步骤。把 skill 更新提醒接入团队协作群这样成员能第一时间感知。遇到升级导致的问题要有快速回滚通道。比如保留上一个 release 包或者提供自动回退命令。如果多个 skill 共享配置或依赖更新时要做好全量回归。11. 总结与下一步skill 的更新提醒机制本质上是一套“发布端到消费端的状态同步”工程。它不依赖某个大厂 SDK也不需要特殊硬件支持用 Git 仓库加一个文件加一个脚本就能跑起来。最值得先动手的部分是创建 skill.json 元数据文件。这个文件是一切提醒机制的基础。第二步做本地批量检查脚本。它解决你自己感知不了更新这个问题。第三步做GitHub Actions 或 Webhook 通知。这解决你的团队或订阅者无法感知更新的问题。最容易踩的坑有三个版本号格式不统一导致比对永远失败。没有写 changelog通知发了但用户不知道改了什么。更新后不备份出问题时无法快速回滚。建议先在单个 skill 上完整跑一遍“添加元数据 - 本地检查 - 远端更新 - 通知推送”的流程确认稳定后再推广到所有 skill 和团队成员。这套流程跑顺之后skill 就不再是“只能手动反复拉取”的黑盒而是一套可以被持续集成和持续交付的规范资产。
