SkillSpec：让 AI Agent 的 Skill 从「不可控」变「可验证」

Skill超级捕获手 技术创作者 2026-09-07 13 阅读

SkillSpec 让 AI Agent 的 Skill 从「不可控」变「可验证」

功能与原则

SkillSpec 是一个开源 Rust CLI 工具，专注于解决 AI Agent 执行自然语言指令（SKILL.md）时的可靠性问题。它不取代任何 Agent 运行时或编排平台，而是在现有框架（Claude Code、Codex CLI、Cursor 等）之上增加一层结构化验证，让 Skill 的执行变得可追踪、可测试、可证明。核心原则是：Skill 应该是合同，而不是散文。

认可度

  • GitHub star：739（截至 2026-09-06）
  • Forks：58
  • 近期 trending：在 Trendshift 的月度 AI 榜单中有记录，关键词命中「AI agent skills」「AI evals」
  • Social mentions：在 X（Twitter）上有开发者社区讨论，被多个 AI 开发者资讯账号转发
  • License：Apache 2.0 / MIT 双许可，可商业使用

链接

GitHub：https://github.com/modiqo/skillspec

原作者

modiqo（GitHub username: modiqo），目前社区可见的维护者。该项目采用纯社区驱动维护，暂无大型企业背书。

介绍

SkillSpec 的诞生背景很清晰：当你给 Agent 写了一份洋洋洒洒的 SKILL.md，Agent 真的读了吗？它会不会跳过了藏在第 80% 位置的安全规则？会不会用了文档里没声明的工具然后声称”完成了”？

这个工具分两步走。第一步是「Doctor」诊断：运行 skillspec doctor ./my-skill，CLI 会分析目标 SKILL.md 的风险，输出量化风险分数（0-100），并指出具体问题——比如「14 条 must/never 义务出现在文档 60% 之后，容易被忽略」「工具被使用但依赖从未声明」「没有测试和追踪表面，’完成’无法被验证」。

第二步是「导入 + 编译」：执行 skillspec import ./my-skill，将 prose 格式的 SKILL.md 转化为结构化的 skill.spec.yml 文件，定义路由、规则、禁止行为和证据期望。编译后的 Skill 伴随一个对齐摘要生成器，Agent 每次执行完都会产出可审计的执行记录——走了哪条路由、完成了哪些步骤、是否遵守了合同规则。

特点

  • Doctor 风险报告：对 SKILL.md 进行量化风险评估，涵盖发现风险、上下文负载、义务放置、依赖声明和证明需求五个维度
  • 结构化契约：将非结构化 prose SKILL.md 转化为 skill.spec.yml 格式，定义精确的技能行为规则
  • 可审计执行记录：每次执行后生成对齐摘要（alignment summary），记录实际执行路径与契约的偏差
  • 路由模式（Router Mode）：当 Agent 的能力列表预算有限时，帮助 Agent 精确定位到特定 Skill
  • 零运行时依赖：不引入新的 Agent 运行时或编排平台，纯 CLI，可与任何 Agent harness 集成
  • 支持多 Agent 客户端：Claude Code、Codex CLI、Cursor 等均兼容

使用方法

安装（任选一种）：

# 官方安装脚本（推荐）
curl -fsSL https://skillspec.sh/install.sh | sh

# 或通过 Rust 包管理器
cargo install skillspec

# 或下载预编译二进制（GitHub Releases）

基本调用：

# 诊断一个 Skill 的风险
skillspec doctor ./my-skill

# 导入并编译为结构化契约
skillspec import ./my-skill

# 编译 + 测试 + 安装到 Agent
skillspec compile --test --install

# 针对公开 Skill URL 直接诊断
skillspec doctor https://github.com/user/repo/tree/main/skills/my-skill

使用场景与人群

适用场景：
– 需要在团队内部署和共享 Agent Skill 的 DevOps/平台工程师
– 需要对第三方 Skill 做安全审计的安全团队
– 构建内部 Agent 能力市场的公司（需要对 Skill 质量做量化把控）
– Skill 作者：对自己的 SKILL.md 做自检，提高被 Agent 正确执行的几率

目标用户： AI 工程团队、Agent 框架开发者、DevRel/技术布道师，以及对 AI 输出可审计性有合规要求的行业（金融、医疗、企业服务）。

输入与输出案例

案例 1：Doctor 诊断

输入（运行 skillspec doctor ./my-skill）：

対象：某团队编写的支付退款 SKILL.md
文档长度：约 300 行 prose

输出（Doctor 报告节选）：

Agent follow-through risk: HIGH (74/100)

Findings:
- 14 must/never obligations appear after 60% of the body → easy to miss
- tools and commands are used, but dependencies are never declared
- no tests and no progress/trace surface → "done" can't be checked

Likely consequence:
An agent may follow the broad task but skip a late safety gate,
use an undeclared tool, or claim completion without evidence.

案例 2：契约化转换

输入：skillspec import ./refund-skill
输出：生成 skill.spec.yml，包含路由定义（refund/partial、refund/full、escalate）、规则（never approve >$500 without secondary approval）、禁止行为（never reveal internal ticket IDs to customer）、证据期望（execution log with approved_by field）。此后 Agent 执行该 Skill 的每一步均有记录可查。

GitHub: https://github.com/modiqo/skillspec

评论区

0 条评论

登录后可评论。

Skill超级捕获手 13 阅读