# Agent 真正能遵循的技能
[](https://github.com/modiqo/skillspec/actions/workflows/ci.yml)
你写了一份很好的 `SKILL.md`。但 Agent 真的遵循它了吗？还是跳过了末尾的安全规则，抓取了未声明的工具，然后没有提供任何证明就报告“完成”了？
**SkillSpec 会告诉你答案。** 运行一条命令即可获取风险报告。然后，将任何技能转化为 Agent 必须遵循的契约，并在最终获得可供检查的记录。
不需要新的 agent runtime。不需要编排平台。只需要一个 CLI 和一个位于你的 `SKILL.md` 旁边的小型 `skill.spec.yml`。
## 30 秒内查看效果
将 Doctor 指向任何技能，可以是本地文件夹或公开的 GitHub URL：
```
skillspec doctor ./my-skill
```
```
SkillSpec Doctor
================
Target: ./my-skill Shape: simple_skill
Agent follow-through risk: HIGH (74/100)
Findings
- description is short and generic -> automatic discovery may be unreliable
- active skill load is 8,482 tokens -> above the balanced target
- 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.
Next step
Ask your agent: /skillspec import ./my-skill, compile it, test it, install it,
and print the alignment summary.
```
试用无需安装。将公开的技能 URL 粘贴到托管页面：
**
**
## 为什么会有这个项目
`SKILL.md` 只是一段文本。harness 会加载它，并期望模型能读取到正确的部分。对于一次性的技能，这可能没问题。但对于你依赖的技能来说，“期望”并不能算作一个计划：
- **被掩埋的规则会被跳过。** 重要的“永远不要做 X”位于第 400 行，而模型在上下文的开头和结尾最可靠，在中间则不然。
- **每一次遗漏都会增加文本量。** 每次失败都会变成新的一段话，这使得下一次遗漏更有可能发生。
- **你只能看到最终答案。** 没有持久的记录来显示运行了哪条路由、发生了哪些步骤，或者跳过了什么。
SkillSpec 将承重部分从纯文本中移出，放入一个小巧的结构化契约中：
- 何时使用该技能
- 选择哪条路由
- 什么是被禁止的
- 必须存在哪些依赖项
- 必须通过哪些检查
- 最终应该存在什么证明
## 安装说明
安装 CLI：
```
curl -fsSL https://skillspec.sh/install.sh | sh
skillspec --version
```
或者使用 Cargo：
```
cargo install skillspec
skillspec --version
```
然后将插件添加到你的 harness 中。
Claude Code：
```
claude plugin marketplace add modiqo/skillspec --sparse .claude-plugin plugins/skillspec
claude plugin install skillspec@skillspec
claude plugin list
```
Codex：
```
codex plugin marketplace add modiqo/skillspec --ref main --sparse .agents --sparse plugins/skillspec
codex plugin add skillspec@skillspec
```
其他平台、固定版本、直接下载和本地开发
预构建的二进制文件可在
[发布页面](https://github.com/modiqo/skillspec/releases)找到：
- `skillspec-macos.tar.gz`
- `skillspec-linux-x86_64.tar.gz`
- `skillspec-windows-x86_64.zip`
发布构件包含 `.sha256` 校验和。安装程序默认会验证校验和并写入 `~/.local/bin`。
固定版本或选择安装目录：
```
curl -fsSL https://skillspec.sh/install.sh \
| SKILLSPEC_VERSION=v0.1.0 SKILLSPEC_INSTALL_DIR="$HOME/.local/bin" sh
```
安装未发布的 `main`：
```
cargo install --git https://github.com/modiqo/skillspec --package skillspec --force
skillspec --version
```
从本地检出版本安装：
```
cargo install --path crates/skillspec-cli --force
skillspec --version
```
本地开发也可以直接安装技能文件夹：
```
# Codex
skillspec install skill skills/skillspec --target codex --retire-existing
# Agents
skillspec install skill skills/skillspec --target agents --retire-existing
# Claude 本地项目
skillspec install skill skills/skillspec --target claude-local --retire-existing
```
对于日常开发，代码库包含一个 `Justfile`，它将 crate 拆分和本地 harness 安装流程集中在一处：
```
# 显示本地 crate 层次结构和依赖方向。
just packages
# 构建每个 workspace package。
just build-debug
just build-release
# 将此 checkout 安装为活动的本地 CLI。
just install-debug
just install-release
# 查看 SkillSpec 可以安装到哪些 harness 根目录。
just install-targets
# 将 repo 的 SkillSpec skill 安装到一个 harness，或所有检测到的 harness。
just install-skill codex
just install-skill agents
just install-skill claude-local
just install-skill-all
# Debug 构建、debug CLI 安装，以及所有检测到的 harness skill 安装。
just dev-install-all
# 选择性加入本地 proof：复制你已认证的 rote binary 和 ~/.rote 配置
# 到 lab 中（排除 workspaces），并证明某个命令使用了 `rote exec --`。
just harness-lab-live-durable-rote-exec
# 推送前的本地 preflight：锁定的 CI 检查、package 列表、examples 和 conformance。
just preflight
```
`just preflight` 刻意使用普通的 Cargo 命令，而不是额外的 preflight 依赖。它运行格式化、锁定的 workspace 检查/clippy/测试、每个拆分 crate 的包文件列表检查、示例验证/测试/依赖项，以及一致性 fixture 检查。PR CI 使用包文件列表检查而不是 `cargo publish --dry-run`，因为同版本的拆分 crate 图无法对其下游 crate 执行 publish-dry-run，直到它们的同级依赖项已存在于 crates.io 上；打标签的发布会按依赖顺序发布这些 crate。
完整的安装说明：
[docs/install](https://github.com/modiqo/skillspec/blob/main/docs/README.md)
## 循环：评估 -> 移植 -> 证明
插件安装完成后，在聊天中向你的 Agent 请求结果。SkillSpec 会选择命令并保持运行一致。
**1. 评估** 在你修改技能之前进行评估。
你会得到一个基准：发现风险、上下文负载、隐藏的义务、未声明的依赖项、缺失的证明，以及 Agent 遵循情况的可能后果。
**2. 移植** 将其转化为契约。
SkillSpec 会在你的 `SKILL.md` 旁边生成一个 `skill.spec.yml`：路由、规则、禁止的操作、依赖项、检查、测试和证明期望。它还会编译一个轻量级的 loader，从而使活动的提示词保持较小。
**3. 证明** 证明它按照预期的方式运行。
每次运行都会留下一份你可以阅读的对齐摘要：选择的路由、已完成的步骤、缺失的证明、禁止操作状态、token 使用情况，以及可用时的墙上时钟指标。不仅仅是“完成”——而是一份记录。
技能库太拥挤了？
Router 模式会路由到那个真正重要的技能，而不是让 harness 一次暴露太多技能。
## SkillSpec 是什么，不是什么
你可以用它做的四件事：
- **导入** 将现有的文本 `SKILL.md` 导入为结构化的 SkillSpec 契约。
- **运行** 在你的 harness 中运行由 SkillSpec 支持的技能，然后查看对齐和 token 报告。
- **路由** 当 harness 列表预算导致发现不可靠时，通过显式 Router 路由多项技能。
- **捕获** 持久的执行轨迹，并将观察到的 CLI/API/MCP 工作转化为可复用的技能。此路径由 [Rote](https://www.modiqo.ai) 提供支持。
| 它是 | 它不是 |
| --- | --- |
| 位于 `SKILL.md` 旁边的契约。 | 技能的替代品。 |
| 一个用于评分、移植、编译和记录的 CLI。 | 一个新的 agent runtime 或编排平台。 |
| 一种使技能更容易在 Codex、Claude 和 Agents 之间进行比较的方法。 | 一种承诺每个 harness 行为完全一致的保证。 |
| 任务完成后你可以审计的运行记录。 | 一个安全沙箱。 |
最后一行很重要。SkillSpec 使运行变得**可审计**：你可以看到声明了什么，并根据契约进行检查。工具边界的强制执行仍然是 harness 的工作。
## 公开的 Doctor 报告
想在安装或移植公开技能之前检查它吗？请使用托管的 Doctor 页面：
**
**
你也可以提交一个
[Doctor 报告请求](https://github.com/modiqo/skillspec/issues/new?template=doctor-report.yml)
并附上公开的 GitHub 技能仓库或文件夹 URL。GitHub Actions 会验证目标，运行 `skillspec doctor`，发布带有 Markdown 报告的评论，并附上 Markdown、HTML、JSON 和文本构件。
公开的 Actions 不会检查私有仓库。对于私有技能，请在本地安装 SkillSpec：
```
skillspec doctor /path/to/local/skill
skillspec doctor /path/to/local/skill --markdown > skillspec-doctor.md
skillspec doctor /path/to/local/skill --html > skillspec-doctor.html
```
使用 Doctor 作为基准。然后要求你的 harness 导入该技能：
```
/skillspec import
, compile it, verify it, test it, and prove it. Print the alignment summary.
```
将基准报告、生成的 `skill.spec.yml`、编译的 loader 和对齐报告与仓库或 pull request 一起发布，以便审查者既能看到原始技能风险，也能看到移植后的证明。
## 为什么评分是可信的
Doctor 不是凭感觉。每个风险条件都引用了已发表的研究或关于 Agent 如何失败的本地 SkillSpec 方法论：上下文位置效应、有效的上下文限制、可验证的指令遵循、过程级 Agent 评估以及技能元数据路由。
报告明确区分了什么是测量值，什么是策略阈值。从这里开始：
- [Doctor Agent 漂移风险](https://github.com/modiqo/skillspec/blob/main/docs/design/operations/22-doctor-agent-drift-risk.md)
- [为什么选择 SkillSpec](https://github.com/modiqo/skillspec/blob/main/docs/overview/01-why-skillspec.md)
- [契约轨迹方法论](https://github.com/modiqo/skillspec/blob/main/docs/overview/08-contract-trace-methodology.md)
契约本身是一个真正的规范：一个类型化的 Rust 模型、JSON Schema、参考语法和
[一致性测试套件](https://github.com/modiqo/skillspec/tree/main/conformance)。
## 了解更多
- [工作原理](https://github.com/modiqo/skillspec/blob/main/docs/design/README.md)
- [命令参考](https://github.com/modiqo/skillspec/blob/main/docs/design/operations/16-command-log.md)
- [插件市场安装](https://github.com/modiqo/skillspec/blob/main/docs/design/operations/26-plugin-marketplace-install.md)
- [请求公开的 Doctor 报告](https://github.com/modiqo/skillspec/issues/new?template=doctor-report.yml)
- [贡献指南](https://github.com/modiqo/skillspec/blob/main/CONTRIBUTING.md)
## 许可证
SkillSpec 采用双重许可，可选择以下任一：
- [MIT](LICENSE-MIT)
- [Apache License, Version 2.0](LICENSE-APACHE)
你可以选择其中任何一种许可证。除非另有明确说明，否则贡献均按相同的双重许可接受。