STOP Protocol：给 Agent Skill 装上可观测性

Skill 是黑盒

用过 Agent 平台的人大概都踩过这个坑。你装了一个 Skill，调用它，然后……不知道发生了什么。

成功了？运气好。失败了？翻日志，猜。

Skill 生态还小的时候这不算事。但 SundialHub 上现在有 4 万多个 Skill，各家 Agent 框架都在推自己的体系。你要从里面选一个来用，怎么判断它靠不靠谱？

判断不了。因为 Skill 没有可观测性。

没有 stderr 的管道

写 Shell 脚本的时候，几个命令用管道串起来：

cat data.csv | process.sh | format.sh | upload.sh

upload.sh 报错了，你看 stderr，看退出码，看中间输出。Unix 几十年前就解决了这个问题。

Agent Skill 的世界里，我们连 stderr 都没有。

串联三个 Skill，最后一个挂了。是第一个输出有问题？第二个跳过了某步？还是第三个本身有 bug？不知道。你只知道”失败了”。

STOP 是什么

STOP（Skill Transparency & Observability Protocol）是一个开放规范。做的事情不复杂：让 Skill 变得透明、可调试、可信赖。

思路来自 SRE 的可观测性三支柱（Logs、Metrics、Traces），但做了适配。Skill 不是普通函数调用，它是 Prompt 和代码的混合体，执行流程由 LLM 驱动，需要不同的观测方式。

三个核心概念：

1. Manifest：声明你的 Skill 干什么

一个 skill.yaml 文件，机器可读的合约：

sop: "0.1"
name: github-issue-creator
version: 1.0.0
description: Create GitHub issues from bug reports

inputs:
  - name: repo
    type: string
    required: true
  - name: title
    type: string
    required: true

outputs:
  - name: issue_url
    type: url
  - name: issue_number
    type: number

tools_used:
  - exec

side_effects:
  - type: network
    description: POST to GitHub API
    destinations: ["api.github.com"]

requirements:
  env_vars: [GITHUB_TOKEN]

运行时在执行前就能知道这个 Skill 要做什么、需要什么、有什么副作用。不是文档，是合约。

现有的 SKILL.md 给 LLM 读，skill.yaml 给机器读。一个是自然语言指令，一个是结构化声明。

2. Trace：看清执行过程

执行时自动生成 span 树，对齐 OpenTelemetry 模型：

Trace: github-issue-creator
├── Span: parse inputs (2ms)
├── Span: exec: gh api (1200ms)
│   └── Span: HTTP POST api.github.com (1100ms)
├── Span: parse outputs (1ms)
└── Span: assertion check (1ms)

每个 span 记录时间、状态、属性。出问题的时候能精确定位到哪一步挂了，不用对着一个 “skill failed” 干瞪眼。

输出是 NDJSON 格式，能直接导入 Jaeger、Grafana。没有造轮子。

3. Assertion：怎么知道 Skill 真的成功了

Skill 自己声明”我成功了”的条件：

assertions:
  pre:
    - check: env_var
      name: GITHUB_TOKEN
      message: "GitHub token required"
  post:
    - check: output.issue_url
      matches: "^https://github\\.com/.+/issues/\\d+$"
    - check: output.issue_number
      greater_than: 0

前置断言检查环境是否就绪，后置断言验证结果是否正确。Skill 的成功标准从”没报错”变成”可验证地完成了预期行为”。

跑的次数多了，断言通过率就是一个天然的 Trust Score。平台可以拿这个分数帮用户筛选靠谱的 Skill。

渐进式采纳

STOP 不要求一步到位。四个等级，按需选择：

等级	你做什么	你得到什么
L0	加一个 skill.yaml	静态分析、安全审计、能力声明
L1	运行时自动生成	执行追踪、耗时分析、错误定位
L2	写几条断言	自动验证、Trust Score、回归检测
L3	定义自定义指标	成本追踪、异常检测、SLA 监控

多数 Skill 从 L0 开始就够了。一个 YAML 文件，零运行时开销。需要调试升 L1，需要信任保证升 L2。L3 留给生产环境。

为什么是现在

Skill 生态在爆发，数量上去了，质量控制没跟上。Agent 从单 Skill 调用走向多 Skill 编排，链条越长，黑盒越危险。企业想用 Agent 但不敢用，因为不知道 Skill 在做什么。

可观测性是建立信任的基础设施。现在不做，后面补的成本更高。

参与

STOP 是开放规范，不属于任何公司或项目。

• GitHub：github.com/echoVic/stop-protocol
• Discussions 已开放
• PR welcome

如果你在做 Agent 开发，或者在维护 Skill 平台，来聊聊。

---

Stop. Look inside. Understand what your skills actually do.