Agent Skill 自更新机制

Joost de Valk（Yoast 创始人）于 2026-04-14 发表的工程实践文章，描述如何让安装在 ~/.claude/skills/ 的 Agent Skill 保持自动更新，避免”缓存文档”问题。

背景：问题所在

Skills 以目录形式安装在磁盘上（~/.claude/skills/），Agent 直接执行磁盘上的版本，没有内置机制感知上游是否有新版。当作者更新了对应博文和 Skill 逻辑，用户本地仍运行旧版本，形成”缓存文档”（cached documentation）——有用，直到它变错。

演进路径

第一版（内嵌 self-check）

在每个 SKILL.md 中内嵌四件套：

frontmatter 中的 version: 字段
仓库根目录 versions.json 统一存所有版本号
SKILL.md 中的指令段落：让 Agent 在调用时主动对比 manifest，有新版则提示更新
CI 检查保持两者同步

问题：每次调用都消耗 tokens 对比版本；若需要重装则打断当前任务；作者误判”这需要 Claude Code 未暴露给 skill 作者的 harness 支持”。

当前推荐模式（SessionStart Hook）

社区反馈（Felix Arntz、Dovid Levine）指出两个更优方案：

① npx skills update 命令

npx skills CLI 支持 --skill flag，可精准更新单个 skill：

# 安装
npx skills add jdevalk/skills --skill astro-seo
npx skills add jdevalk/skills   # 安装全部
 
# 更新
npx skills update               # 更新全部
npx skills update astro-seo     # 更新单个

② SessionStart Hook（零 token 成本）

在 ~/.claude/settings.json 注册 hook，在每个 session 启动时（context 加载前）自动拉取最新 skill：

{
  "hooks": {
    "SessionStart": [
      {
        "type": "command",
        "command": "npx skills update -g -y 2>/dev/null"
      }
    ]
  }
}

关键优势：

运行在 context window 外，零 token 消耗
在 session start、/clear、compaction 时均触发
Skill 文件在 session 读取前就已是最新版
无需 runtime、service、额外发布流程

若 /clear 时的延迟不可接受，可在 hook input 中检查 source 字段，仅在真正的 session start 时执行。

对 Skill 维护者的建议

无需发布 release：npx skills update 直接拉 main 分支
建议添加 per-skill README.md：skills.sh 会在 skill 详情页展示
在 README 中包含 SessionStart hook 代码片段，方便用户一键启用零摩擦更新

核心洞察

“An agent skill without a version check is cached documentation. Useful until it’s wrong.”

SessionStart hook 是 Claude Code 提供给 skill 作者的正确扩展点——在 context 外运行，不消耗 token，透明地保持 skill 时效性。

关联页面

agent-skill-loading — Skill 加载机制：轻量摘要注入 + 两阶段展开
agentara-skills — 使用 npx skills CLI 安装的 Skill 库实例
superpowers — 包含 SessionStart hook 的完整 Agent 开发方法论
claude-code-permissions — Claude Code settings.json 权限与 hook 配置

zhaoweiguo 的知识库

目录