Claude Code 明明配置了 Skill，为什么还是会跳过？我连夜写了一个本地验证器

Claude Code 的 Skill 可以保存项目规则，但 Skill 存在于仓库中，不代表 agent 在当前任务里真的读取过。长对话和上下文压缩会让这个问题更明显。

比如今年夏天我在工作项目里给 Claude Code 配置了几个 Skills。

范围也不大,概括了工程风格、产品调研方法和发布流程。数量并不多，大约只有七八个。

但在上下文变长以后,特别是超过百万后,我发现还是需要不厌其烦地问：

你真的读取了这个任务要求的 Skill 吗？(真实对话里我没有这么礼貌)

有时 Claude 会主动读取；有时它直接开始修改文件；有时它说自己遵守了规则，但我找不到实际读取记录被放了鸽子。

继续往提示词里加一句"请务必阅读 Skill"，只能再提醒一次,这样有时又会导致大模型重新调取大量上下文,Token哐哐烧, 那么能不能有个一个能在动作发生前检查证据的环节呢?

所以我做了 Miko：一个运行在 Claude Code Hooks 上的本地验证器。

我们不解决"怎么写 Skill"

Skill 可以告诉 agent 应该怎样完成任务。

Miko 专注的是另一件事：

在修改受保护文件之前，宿主是否真的观察到了必需的 Skill 或参考文档读取？

一个最小流程是这样的：用户要求修改 UI 后，Claude 尝试编辑文件；Miko 发现 product-design Skill 尚未读取，于是暂停这次编辑。Claude 读取缺失的 Skill 和参考文档后重试，Miko 放行，并在任务完成时给出一行回执。

有试用的朋友起初误以为这是用一个模型来拦另一个模型, Miko并不调用任何LLM,不主动消耗token, 大概率也不需要每次修改前弹出人工审批.

Miko 的核心验证器不调用 LLM。它检查 Claude Code 通过 Hooks 暴露的可观察事件，再根据项目里的规则作出确定性判断。(Deterministic)

三个检查阶段

Miko 把一次任务分成三个阶段。

1. PREPARE：准备证据

检查需要的 Skill 和参考文档是否已经读取。

例如，修改 src/ui 前必须读取：

product-design Skill
docs/design-system.md

2. PRE_ACTION：动作范围

检查即将执行的工具、文件路径和风险范围是否符合规则。

例如：

可以编辑 src/ui
不允许删除文件
不允许越过配置的目录范围

3. COMPLETE：完成证据

检查任务结束前是否出现了约定的测试、检查或产物证据。

Agent 只说一句"测试已经通过"不会自动成为可信证据。Miko 可以保留这类自述用于审计，但不会把它当作宿主实际观察到的测试结果。

规则写在项目里

Miko 使用项目根目录的 miko.json。下面是一个简化示例：

js 复制代码

{
  "$schema": "./node_modules/koma-miko/schema/miko.schema.json",
  "version": 1,
  "specs": [
    {
      "id": "ui-change-v1",
      "appliesWhen": {
        "action": {
          "tools": ["Edit", "Write"],
          "pathPrefixes": ["src/ui"]
        }
      },
      "requires": {
        "skills": [
          {
            "name": "product-design",
            "reloadAfterCompaction": true
          }
        ],
        "references": [
          "docs/design-system.md"
        ]
      },
      "mode": "guided"
    }
  ]
}

这里的意图是：

当 agent 准备修改 src/ui 时，先确认当前上下文中已经读取 product-design 和设计规范；上下文压缩后需要重新读取。

规则可以跟随仓库进入版本控制。用户能够审查它，也能知道为什么某次动作被暂停。

为什么使用 Hooks

前阵子大火的 MCP 固然很适合给 agent 提供工具，但普通 MCP 工具仍然需要 agent 主动调用。

Miko 要检查的是"修改发生之前是否满足条件"，所以它接入 Claude Code 的生命周期 Hooks, 我个人认为这是目前在高层能够干预agent行为的有效方式之一:

Claude Code 的 Hook 事件 → Miko 适配器把事件标准化为证据 → Agent Spec 验证器判断 → 放行、暂停或拒绝本次动作。

如果证据缺失呢?

🔴 Miko DENY · PREPARE

缺少准备证据：product-design Skill 尚未读取；docs/design-system.md 尚未读取。

下一步：读取缺失的 Skill 和参考文档后，重试刚才被拦截的动作。

我们就可以在一定程度上"强行建议" Agent可以根据这个结果补齐证据并重试。用户不需要再次复制整段 Skill 内容.

三条命令开始试用

在项目根目录运行：

sql 复制代码

npm install -D koma-miko@alpha
npx koma-miko init --host claude
npx koma-miko doctor --host claude --strict

然后：

项目实际情况修改生成的 miko.json。
启动一个新的 Claude Code 会话。
让 Claude 修改受保护目录里的一个小文件。
观察它是否经历"暂停 → 读取 Skill → 重试"。

要注意:Miko 不会替你安装 Skills。配置中填写的 Skill、参考文档和路径必须在项目中真实存在。

它能证明什么，不能证明什么

Miko 可以确认宿主是否观察到了 Skill、文件读取、工具调用和测试等事件。

它不能证明模型真正理解了 Skill，也不能保证最后生成的代码一定正确。绕过宿主适配器发生的动作，也不在它的观察范围内。

因此，更准确的说法是：

Miko 把"希望 agent 记得规则"变成"在可观察的动作边界检查规则证据"。

这是一条工程约束，不是读取模型思想的工具。

什么项目适合使用

Miko 更适合这些情况：

仓库已经有多个 Skills 或项目规范；
某些目录修改前必须阅读特定说明；
长对话或上下文压缩后容易遗失规则；
团队需要看到测试、审查或产物证据；
你已经开始反复提醒 agent 做同一件事。

如果项目只有一条固定检查，一个简单的原生 Hook 通常就够了。Miko 的价值主要在可复用的 Agent Spec、上下文压缩后的证据失效、恢复提示和本地证据记录。

当前状态

Miko 目前仍是公开 alpha：

Claude Code 是主要使用路径；
Codex CLI 处于 Technical Preview；
验证器在本地运行，不调用 LLM；
项目使用 MIT 协议。

觉得我写的太啰嗦的可以直接先看无需安装的浏览器回放：

在线演示： koma-demo.swbuilds.workers.dev

浏览器页面是确定性的流程模拟，并非嵌入了一个真实 Claude 进程。真实 Claude Code 测试过程和限制记录在仓库的评估文档中。

GitHub： github.com/swnotmetal/...

Miko 中文文档： packages/koma-miko/README.zh-CN.md

如果你正在使用 Claude Code Skills，希望大姐能给我三个反馈：

第一次安装和 Hook 激活是否顺利；
有没有出现错误拦截或应该拦截却没有拦截；
完成一个任务后，你是否愿意在第二个任务里继续开着它。

感谢阅读.