# 我扫了 275 个 Agent Skill，94.5% 没写"什么时候不该用"

> 本文适合正在写 Agent Skill（Claude Code / Codex / Cursor）的开发者。核心结论一句话：**skill 的失败大多不在正文，而在 `description` 没有写边界。**

## 一、起因是一件很无聊的事

我的仓库里有一份 skill，存了两个位置：

```
plugins/skill-forge/skills/skill-forge/   ← canonical，改这里
skills/skill-forge/                       ← 镜像，skills.sh 和手动安装读这里
```

为什么两份？因为 Claude 插件市场要求 `plugins/<name>/skills/<skill>/` 这个结构，而 `npx skills` 和手动 `cp -r` 的人读的是仓库根目录的 `skills/`。两边都得有。

于是就有了一个每次发版都会犯的错：改完 canonical，忘了同步镜像。

结果不是报错，是**装了的人拿到旧版本，而且没人知道**。这种 bug 最贵——它不报警，只是慢慢让所有人跑在不同的代码上。

我想把这个流程沉淀下来，让它变成一件不用记的事。

## 二、最常见的做法，以及它为什么没用

如果你直接对 AI 说"把我们同步镜像的流程写成一个 skill"，你会得到类似这样的东西：

> 1. 检查 canonical 目录和镜像目录是否一致
> 2. 如果不一致，将 canonical 的内容复制到镜像
> 3. 验证同步结果

读起来没问题，但它不能执行。

"检查是否一致"——用什么检查？`diff -r`？它会因为 `.gitignore` 里的文件报一堆噪音。

"验证同步结果"——验证到什么程度算通过？退出码？还是打印一行字？

Agent 拿到这三行，每一步都要现场发挥。**你在教它做事，但没给它任何可执行的证据。**

## 三、换成从证据里抽

真正可靠的写法是反过来的：不描述流程，而是从这次真实跑过的东西里把步骤抽出来，**每一句都能追到一个真实存在的命令和真实的输出**。

这个仓库里真实存在的东西是：

| 证据 | 来源 |
|---|---|
| `scripts/sync_mirror.py --check` 退出码 1 = 有漂移 | 脚本实现 |
| 退出码 0 = 已同步 | 脚本实现 |
| 第一次跑会创建镜像并打印源/目标路径 | 本次会话输出 |
| 第二次跑打印 `mirror is in sync` | 本次会话输出 |
| `--check` 在漂移时列出具体差异文件 | 脚本实现 |

于是流程变成：

```bash
python scripts/sync_mirror.py --check     # 退出 0 或 1，1 时列出漂移文件
python scripts/sync_mirror.py             # 镜像
python scripts/sync_mirror.py --check     # 必须打印 "mirror is in sync"
```

每一步都有退出条件，每个退出条件都有真实出处。**写不出证据的步骤，就不写。**

这个 skill 最后长这样：103 行，约 890 tokens。

## 四、然后我给它过了 8 道门

写完之后我没有直接发布，而是拿一套评分卡逐项打分，每项 0/1/2 分，满分 16：

| # | 门禁 | 得分 | 依据 |
|---|---|---|---|
| 1 | 触发精度 | 2/2 | 3 个正向触发 + 1 个排除项 |
| 2 | 渐进披露 | 2/2 | 103 行，没有内联参考资料 |
| 3 | Token 预算 | 2/2 | ~890 tokens，远低于 5k 核心预算 |
| 4 | 可执行性 | 2/2 | 5 步，每步都有命令和退出条件 |
| 5 | 证据锚定 | 2/2 | 来自 `sync_mirror.py` 和两次真实运行 |
| 6 | 安全 | 2/2 | 不删源数据；只写镜像；无密钥、无网络安装 |
| 7 | 可移植性 | 2/2 | 路径从仓库根发现，无绝对路径 |
| 8 | 可证明性 | 2/2 | 5 个正向 + 3 个负向触发；dry run 跑了两次 |

16/16，可以发。

但注意第 1 道和第 8 道门都在说同一件事——**触发**。这两道门才是大部分 skill 真正失败的地方。

## 五、最反直觉的一条：什么时候"不该"激活

8 道门里我觉得最有用的一条，是这个 skill 的第三个负向触发：

| 用户说什么 | 预期行为 |
|---|---|
| "Publish the skill to skills.sh." | **不激活** |

为什么？因为"发布"和"同步镜像"是两件不同的事。

如果这里误激活了，会发生什么：用户说要发布，agent 很勤快地去做了镜像同步，然后告诉你"已完成"。

**看起来做了事，实际做错了事，而且不报错。**

这类错误比"不会做"贵得多。不会做至少会停下来问你；做错了会安静地把结果交给你。

所以这个 skill 里专门写了一段：

```markdown
## When to use
- 仓库把 plugins/<name>/skills/<skill>/ 作为 canonical，skills/<skill>/ 作为镜像
- SKILL.md、references/、assets/、scripts/ 有改动
- 即将打 release tag
- 安装方报告内容与仓库不一致

Do not use when the repository has only one copy,
or when the two directories are intentionally different.
```

还有一张失败处理表，专门覆盖误判的情况：

| 失败 | 信号 | 恢复 |
|---|---|---|
| 认错了 canonical | 镜像后漂移反向 | 从 git 恢复，确认源，重跑 |
| 镜像里有未跟踪文件 | `extra in mirror` | 删掉多余文件，**绝不反向复制回去** |
| 脚本缺失 | `canonical skill not found` | 修路径常量，或从仓库根运行 |
| 目录是软链接 | 复制失败或死循环 | 先替换成真实文件再发版 |

## 六、我统计了 275 个 skill

我写了个脚本，扫了本机所有 host 目录下已安装的 `SKILL.md`，看 `description` 里有没有任何形式的负向触发（`Do not use` / `Not for` / `Avoid using` / `Not intended for`）。

```
SKILL.md 文件数:     374
去重后唯一 skill:   275
有 description:     275
含负向触发:          15
负向触发率:         5.5%
```

为什么 374 个文件只有 275 个 skill：同一个 skill 往往被装进了 `.claude/skills`、`.agents/skills`、`.cursor/skills`、`.codex/skills` 好几个目录。不去重的话，装得最多的那几个 skill 会被反复计数，把结果带偏。

**94.5% 的 skill，没有告诉 agent"什么时候不该用我"。**

拆开看分组，差距很大：

| 来源 | 数量 | 写了负向触发 | 比例 |
|---|---|---|---|
| 微软 Azure 系列（厂商 curated） | 19 | 4 | 21.1% |
| 社区与其他 | 256 | 11 | 4.3% |

厂商比社区规范将近 **5 倍**。但这个"规范"也只是相对而言——**即便是精心维护的 Azure 包，也有 79% 的 skill 没写边界**。

样本说明：这 275 个来自我一台机器上的安装记录，主要构成是几个公开合集（Anthropic 官方示例、微软 Azure 包、superpowers、gstack）加零散安装。**不是随机抽样，不是全网普查。** 你在自己机器上重跑，数字会变。但 21.1% 对 4.3% 这个量级的差距，不太可能是样本偶然。

这意味着什么：agent 只能靠 `description` 判断该不该加载这个 skill。如果 `description` 只说了"我能做什么"，它就只能在**所有相似场景**里都加载一次，然后靠正文里的内容自己判断要不要真的执行。

触发范围失控的 skill，本质上是在给 agent 一个边界模糊的工具。**正文写得再详细，边界错了就是错的。**

## 七、可以直接抄走的 4 条

不用装任何东西，这四件事你现在就能做：

### 1. 在 `description` 末尾加一句 `Do not use for ...`

具体到能分辨的场景，不要写"不适用于无关任务"这种废话。

可以直接套这个模板：

```yaml
description: >-
  <一句话说清做什么，动词开头>.
  Use when <具体触发场景 1>, <场景 2>, <场景 3>.
  Do not use for <最容易被误判的相邻任务> (use <那个 skill> instead),
  or <另一种边界情况>.
```

关键是最后那句：**写出你最怕它被误用的那个场景**。想不出边界，通常意味着这个 skill 的职责还不够窄。

### 2. 至少写一个负向触发测试

想一句用户可能说的、但你不希望它激活的话，写进 skill 的验证清单。

我的是这 3 句：

| 用户可能说 | 预期 |
|---|---|
| "Sync my fork with upstream." | 不激活 |
| "Copy this directory to another drive." | 不激活 |
| "Publish the skill to skills.sh." | 不激活 |

每一句都是在这个仓库里完全可能出现的真实请求，但都应该路由到别处。没有它们，"sync" 和 "mirror" 这两个词会把所有东西都吸进来。

### 3. 把每个步骤的"完成条件"写死

不是"确认同步成功"，而是"`--check` 打印 `mirror is in sync`"。

### 4. 数字优先于形容词

`~890 tokens` 比"很轻量"有用，`退出码 1` 比"检查失败"有用。

## 八、写在最后

这套东西我整理成了一个可执行的流程（8 道门禁 + 打分卡 + 触发测试模板），仓库在 [github.com/YaBoom/skill-forge](https://github.com/YaBoom/skill-forge)，103 行的完整示例在 `examples/sync-skill-mirror/`，上面那个统计脚本在 `scripts/survey_triggers.py`，你可以直接在自己机器上跑，看看自己的数字是多少。

但说实话，**上面四条你手写也能做到**。工具只是让这件事不容易漏。

---

如果你今天只能改一件事，改 `description` 里的负向触发。它便宜、见效快，而且是唯一一条能直接减少 agent"做错事"的改动。

我扫了 275 个 Agent Skill，94.5% 没写"什么时候不该用" 本文适合正在写 Agent Skill（Claude Code / Codex / Cursor）的开发者。核心结论一句话：skill 的失败大多不在正文，而在 description 没有写边界。 一、起因是一件很无聊的事 我的仓库里有一份 skill，存了两个位置： plugins/skill-forge/skil

我扫了 275 个 Agent Skill，94.5% 没写“什么时候不该用“

人工智能

开发工具

测试

扫描275个Agent Skill后发现94.5%未写明"何时不该用"。核心问题在于description缺乏边界定义，导致agent误触发。以syncmirror.py为例，通过证据锚定法将流程转化为可执行命令，并建立8道门禁评分体系。关键改进：添加负向触发语句（Do not use for...），明确完成条件，用具体数字替代模糊描述。厂商技能负向触发率21.1%，远超社区4.3%。

路由

Python

GitHub

Agent

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

扫描275个Agent Skill后发现94.5%未写明"何时不该用"。核心问题在于description缺乏边界定义，导致agent误触发。以syncmirror.py为例，通过证据锚定法将流程转化为可执行命令，并建立8道门禁评分体系。关键改进：添加负向触发语句（Do not use for...），明确完成条件，用...

我扫了 275 个 Agent Skill，94.5% 没写“什么时候不该用“-腾讯云开发者社区-腾讯云

我扫了 275 个 Agent Skill，94.5% 没写“什么时候不该用“

我扫了 275 个 Agent Skill，94.5% 没写“什么时候不该用“

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐