数据STUDIO

Agent 入门先搞懂 Harness:权限、记忆、子代理、Skill ...

Image

用 Claude Code 、 Codex 或者 WorkBuddy 写了一段时间代码,大概都会遇到同一个问题:工具一样、模型一样,为什么有人越用越顺,有人每隔几天就想推倒重来。

差别往往不在模型,而在工具外面那层东西。

社区里把它叫 harness。名字听着像新概念,拆开看都是工程习惯:给 Agent 定权限、写项目说明、放规则和文档、管理记忆、判断什么时候先做计划、什么时候派子代理、哪些流程值得写成 Skill。

单拎出来都不难,难的是判断哪一层现在真的需要。下面按这个顺序讲,能直接配的地方给配置,不值得折腾的地方也直说。

01先把权限和沙箱定下来

最容易被忽略的一件事:这些工具不会自动替你守住项目边界。

Claude Code 的权限写在 settings.json 里,全局配置放 ~/.claude/settings.json,项目级配置放 .claude/settings.json。这里要分两件事看:permissions 决定 Claude 能对哪些工具做什么;sandbox 保证已经放行的命令不会跑到项目目录外面。

{
"permissions": {
"defaultMode": "acceptEdits",
"blockReadsOutsideWorkingDirectories": true,
"allow": [
"Bash(git add *)",
"Bash(git commit *)"
],
"ask": [
"Bash(git push *)"
],
"deny": [
"Read(//**/.env)"
]
},
"sandbox": {
"enabled": true,
"failIfUnavailable": true,
"allowUnsandboxedCommands": false,
"filesystem": {
"denyRead": [
"~/**/.env"
],
"denyWrite": [
"~/**/.env"
]
}
}
}

这里有个很容易误解的地方:沙箱主要管的是命令别跑出项目,不等于帮你收紧读取范围。写操作会被挡住,读往往还是通的。真要挡 .env、~/.ssh 这类路径,denyRead 得自己写。

云朵君自己的习惯是先在 deny 里把密钥和凭据路径列全,再逐条放开需要的能力。权限收得越紧,Agent 在项目里活动越费劲,所以顺序应该是“先挡死,再按真实需要放开”,而不是反过来。

Codex 用另一套配置,全局文件在 ~/.codex/config.toml。

default_permissions = "my-workspace"
approval_policy = "on-request"

[permissions.my-workspace]
extends = ":workspace"

[permissions.my-workspace.filesystem]
":root" = "deny"
":minimal" = "read"
glob_scan_max_depth = 6
"~/.ssh" = "deny"
"~/.aws" = "deny"

两边的粒度也不同。Claude Code 可以逐条放行 git add、git commit 这类命令;Codex 要么整体放行 git,要么保持默认,每次询问。一个比较稳妥的划分是让 Agent 能 add 和 commit,但不允许它自己 push 或回退——提交是回溯坏改动成本最低的方式,而 push 和回退影响的是共享状态。

配完别只看文档,实际测一次:让它读一个该被挡住的文件,再让它跑一条 deny 里的命令,看行为对不对。权限配置最怕的不是没写,而是写了却没生效。

还有两个边界要清楚。它能挡住误读误写和一部分密钥泄漏,但挡不住提示注入和其他恶意行为。另一个反向成本是,权限收得越紧,Agent 在项目里活动就越费劲,这也是这些工具默认不会一上来就锁死的原因。

02AGENTS.md:小一点,当索引用

AGENTS.md 是可选的,但应该小。200 行左右是个合理的上限,再长就会占用更多上下文,Agent 遵循起来也不那么稳定。

它的职责是让 Agent 知道这个项目的特殊之处:常用命令、不常见的约定、关键系统放在哪、哪些事情通常不变,而不是教它怎么做软件工程。原则、架构、设计这类更长的内容,放到别的文件里,由它引用过去。

project/
├── AGENTS.md   # 每次加载
├── CLAUDE.md   # 现在可选
├── docs/
└── src/

一个 iOS 项目的 AGENTS.md 大概可以长这样:

# Project instructions

## What this project is
[...] iOS app.

## Commands
- Dev on device: `nvm use 22 && npx expo start --dev-client`
- Typecheck: `nvm use 22 && npx tsc --noEmit`
- Widget/Live Activity layouts: `npm run check:widget` after ANY edit to `src/widgets/`
- Release: `eas build --platform ios --profile production --clear-cache` → TestFlight.

## How we work in this repo
- Changes land one at a time: build it → typecheck → commit with a what+why message →
  the user verifies on device → next change.
- Every distinct change gets its own commit, and notable ones get a `docs/CHANGELOG.md`
  entry the same day.
- Structural calls are never made unilaterally.
- Comment budget: lean. Default is no comment.

## Project documentation
- `docs/PRINCIPLES.md` — how we build and the rules we don't break.
- `docs/ARCHITECTURE.md` — canonical current-state.
- `docs/BUGS.md` — the bug register with statuses.
- `docs/CHANGELOG.md` — dated log, newest first.
- `docs/PENDING-FIXES.md` — agreed-but-unbuilt fixes, priority index on top.

2026 年 9 月,Stride 分析过 7,370 个公开 GitHub 仓库里的 AGENTS.md。其中 73.5% 提到了测试、构建或 lint 命令,39.3% 提到安全或密钥,10.6% 明确禁止泄漏密钥。文件的中位数大约是 819 个词、105 行。内容分布上,测试说明占 55.7%,代码风格与约定占 54.3%,项目结构占 54.3%,Git 与 PR 流程占 47.6%,命令占 44.0%。

这组数字有意思的地方在于:大家实际写的东西,和建议他们写的东西,并不完全一致。很多人把它写成了项目百科,但它更适合做一页目录。

至于 Claude Code 的 /init,态度可以谨慎一点。它会读现有仓库并生成一份 starter 说明文件,现在还会顺带提出 Skill 和 hook 的建议;对已经有 CLAUDE.md 的项目,重跑会给修改建议而不是覆盖重建。

但在结构很乱的老项目上,它给出的结果往往不理想。原因不难理解:很多软件的真实知识活在某个人的脑子里,他知道这个文件连着那个文件、这个决定是因为当年某个约束。Agent 只能从仓库里已有的痕迹反推,能猜对一部分,也会猜错一部分。

更麻烦的是把矛盾写进文档。Agent 后面会优先相信这些文档,等你发现问题时,很难判断它到底被哪一条带偏了。2026 年 2 月一篇苏黎世的研究(Evaluating AGENTS.md)也提到,概览部分经常重复代码库里已经存在的信息,反而制造冗余;/init 也无法发现仓库里没有体现的产品决策和领域理解。

对干净的新项目,/init 值得一试,前提是你愿意逐条核对它写出来的内容。文档之间有矛盾时,Agent 的工作会变得很难预测。

03规则和文档:让信息出现在该出现的地方

项目变大以后,不同目录往往需要不同的说明。前端、后端、账单系统各有一套约定,你不想在改后端时把前端的规则也塞进上下文。

Claude Code 的做法是在 .claude/rules/ 下按文件放规则,用 paths 指定作用范围。

project/
├── AGENTS.md
├── .claude/
│   ├── rules/
│   │   ├── subscriptions.md
│   │   ├── billing-system.md
│   │   └── backend.md
│   └── settings.json
└── src/

每个规则文件自己声明路径:

---
paths:
  - "src/subscriptions/**/*.ts"
---

When working on subscriptions remember the rules (whatever they are)

配置完还是要测:让 Agent 读一个目标文件,再问它当前生效的规则是什么,比看文档猜更可靠。

Codex 这边要麻烦一些,它靠每个目录下的 AGENTS.md 实现类似效果。想让 /audio 目录有自己的说明,就在那里放一个文件:

project/
├── AGENTS.md
├── src/
│   └── audio/
│       ├── AGENTS.md   # Codex 的目录级说明
│       └── script.ts

这里有个已知限制:从项目根目录启动 Codex,并不保证之后编辑 src/audio/generation.ts 时,src/audio/AGENTS.md 会自动注入。可以用 AGENTS.override.md 试着解决,但它会覆盖主 AGENTS.md,用之前最好先确认实际行为。

规则解决了上下文注入的位置问题,也带来新的维护问题:文档越多,配置漂移和过期说明的概率越高。Agent 严格照着一条 CLAUDE.md 执行,而那条说明引用的组件或架构已经不存在了——结果看起来像幻觉,实际上是它忠实地执行了错误上下文。

社区里有项目在处理这件事。Stemma 关注如何在多个编码 Agent 之间维护共享说明;config-drift-checker 则检查每个 Agent 实际能加载什么、为什么加载、这些重复上下文要花多少 token。另一种做法是用 hook 清理文档,但让 Agent 专注维护文档本身也要消耗 token,划不划算要看项目规模。

docs/ 目录承担的是更长的那部分知识:原则、领域模型、架构、决策记录。它和记忆的区别在于,这份知识不只服务一个 Agent,而是所有在这个项目里工作的人共用。

project/
├── AGENTS.md        # 每次加载
└── docs/            # 按需加载
    ├── product.md
    ├── domain-model.md
    ├── architecture.md
    ├── PRINCIPLES.md
    ├── BUGS.md
    ├── CHANGELOG.md
    ├── PENDING-FIXES.md
    └── decisions/
        └── 001-character-voice-model.md

AGENTS.md 在这里扮演索引:它指向最重要的几份文档,而不是把所有内容复制一遍。实际维护时,docs/ 很容易被 Agent 塞成一堆按日期命名的文件,隔一段时间清理到一个 legacy/ 目录里,会省下后面的很多上下文。

决策记录(ADR)也值得单独留位置。假设你曾经决定某些数据必须留在服务端、某些可以本地保存,并把它写进了架构文档。过一段时间,另一个 Agent 觉得本地保存更高效。架构文档只说“不要这样做”,但不解释原因;一条决策记录就能补上缺失的部分:

# decisions/002-server-entitlements.md
Status: Accepted

## Decision
Keep subscription entitlements server-authoritative.

## Reasons
- Notifications may arrive out of order.
- Users can have multiple devices.
- Event processing must be idempotent.

## Rejected alternative
Client-maintained credit balances with periodic synchronization.

它省下的是反复解释同一个问题的时间,不是一次搜索的时间。有些决策只活在脑子里,每次都要重新讲一遍,讲到最后自己也会疲惫。

04记忆:别让写进去的东西都变成事实

Claude Code 的记忆和 AGENTS.md 最大的区别是:这些文件由 Agent 自己写、自己更新。

主文件在
~/.claude/projects/<project>/memory/下,结构大致是这样:

~/.claude/projects/<project>/memory/
├── MEMORY.md
├── user_role.md
├── feedback_testing.md
└── ...

MEMORY.md 是个索引,应该控制在 200 行或 25 KB 以内,其余内容放在引用文件里,由 Claude 判断什么时候需要读。

按设计,它应该保存四类东西:你偏好怎么工作、你给过的纠正、从仓库里看不出来的进行中工作或决定、以及相关信息在仓库外哪里能找到。

问题在于,保存下来的东西不一定对,而且错了以后不一定被替换。常见的情况是:一份几个月前的 codebase-map.md 还在描述已经不存在的结构,一份设计说明里留着模型自己编错的信息,一个对应功能早在第一周就被删掉了,记忆文件却还在。

于是就出现了“失忆”循环:

会话 1 → Claude 判断某块状态归客户端所有,实际归服务端。你纠正了它。
会话 2 → 记忆重新加载,Claude 又从错误前提出发。你再纠正,但旧记录未必被替换。
会话 3 → 同样的问题回来,你继续纠正。

这不是简单的“忘了一件事”,而是记住了一件错的事,并把它带进后续所有判断。

社区里有几种解法:Dejavu 试图阻止过期信息继续影响 Agent;Friday 用带版本的事实,让后来的决定可以替换之前的;Beacon 则尽量避免每一段对话——包括 Agent 自己推错的结论——都自动变成永久知识。

共同的原则是:Agent 学到的东西不该全部变成永久事实,已经保存的事实也不该永远有效。隔一段时间翻一遍记忆文件,删掉过期项,比不断纠正同一个错误便宜得多。

05计划:不是每个任务都值得先想

和 Agent 一起做计划,用的就是 /plan 模式。

/plan figure out how to add subscription upgrades without
changing how existing subscriptions work.

这里真正要解决的问题是:Agent 可以实现得很好,同时对“要解决什么问题”判断得很差。所以不能只说一句“给我的 iOS App 加订阅升级”,然后指望它读懂你的想法。

你仍然要回答:订阅有哪些、应该怎么工作、哪些功能要付费、用户没用完的额度怎么办、降级会怎样、升级又会怎样。

但计划也不是越细越好。“找出所有边界情况”这种要求对 Agent 没什么用,它会把大量信息堆回来,反而让你更难判断。换成“如果用户生成视频但失败了,我们打算怎么把额度还回去”,讨论才能落到具体决定上。

2026 年 6 月,Anthropic 研究过 40 万次 Claude Code 会话,发现人类贡献了大约 70% 的计划决策(做什么、用哪种方案、什么算完成),只贡献了大约 20% 的执行决策(改哪些文件、写什么代码、跑哪些命令)。

计划之所以还需要人,是因为它涉及系统架构、项目领域知识、优先级,而 Agent 目前还无法稳定独立处理这些东西。同一项研究还发现,对任务更专业的人成功率更高,也更能从 Agent 遇阻时恢复过来。这里的专业性不一定是编程能力,也可能是业务能力——懂对账规则的会计,做记账软件会比不懂的人有效得多;熟悉儿童 App 体验设计的人,做儿童 App 也会更顺。

2026 年 9 月还有一篇An Empirical Study of Harness Design for Coding Agents (https://arxiv.org/abs/2609.20804),结论有点反直觉:对较弱模型,计划能显著提高成功率;对较强模型,计划主要减少浪费的工作和成本,对准确率影响不大,有时甚至会让准确率下降。OpenAI 和 Anthropic 在 2026 年也都提醒过,不要堆过度复杂的指令、过长计划流程,或者强迫 Agent 走它并不需要的步骤。

计划因此不该变成默认动作。遇到不熟悉的代码、需要解释领域、要比较架构方案、要协调一次复杂的改动,或者要先确定怎么验证,这时才值得先计划。

06子代理和 worktree:并行要先算成本

子代理是有自己上下文的 Agent(通常是独立上下文)。可以把它理解成从主任务上分出去的一支:它有自己的说明、工具,也可以只拿到指定的 Skill。

主 Agent 可以自己派生代理,也可以使用内置的 explore、plan、general-purpose 这类代理,或者自己写代理定义。Claude Code 用 Markdown,Codex 用 TOML。

your-project/
├── .claude/
│   └── agents/
│       └── ux-reviewer.md
└── .codex/
    └── agents/
        └── ux-reviewer.toml

Claude Code 的代理文件至少要有名称和描述,再加上它该做什么:

---
name: ux-reviewer
description: Review implemented UI for product and UX problems
model: sonnet
effort: high
tools: Read, Grep, Glob, Agent
maxTurns: 12
---

Review the implemented UI against the product model
and the approved requirements.
Find concrete behavior or UX problems.
Return file references and describe the impact.
Do not edit the implementation.

tools 决定它能用哪些能力。这里允许它调用其他 Agent,也可以读文件、用 Grep 和 Glob。如果想进一步限制它能跑的 git 命令,要到 settings.json 里写 allow 和 deny;只写 Bash 不写具体命令,等于把整个 shell 放开了。

还有一个配置叫 omitClaudeMd,它会在子代理的上下文里去掉 CLAUDE.md 或 AGENTS.md。社区里有人报告这样能显著降低 token 消耗,具体幅度因项目而异,值得自己测一次再决定。

子代理、子任务和 fork 也不是一回事。普通子代理是干净上下文加一份委托任务;子任务拿到整段对话的副本,结果回到当前对话;fork 则从主 Agent 分出独立的背景会话,可以之后再回来查看或发消息。子任务能共享父会话的 prompt cache,在上下文相同的任务上通常更便宜。

Codex 的代理文件长这样:

name = "ux_reviewer"
description = "Review implemented UI for product and UX problems"
model = "gpt-6-luna"
model_reasoning_effort = "high"
developer_instructions = """
Review the implemented UI against the product
model and approved requirements.
Use the verify-product-ui Skill when applicable.
Return concrete findings with file references.
Do not modify code.
"""

Codex 没有 Claude Code 那样的 tools 白名单,自定义代理会继承父会话的工具、沙箱、审批、MCP 服务器和 Skill。全局的 [agents] 段可以控制嵌套深度和并发数:

[agents]
enabled = true
max_depth = 2
max_concurrent_threads_per_session = 8
default_subagent_model = "gpt-6-luna"
default_subagent_reasoning_effort = "medium"

子代理适合什么任务?需要干净上下文的代码库调查、需要并行收集的多份文档、需要独立视角的代码审查,都是典型场景。比如一个生成媒体挂错草图的问题,要跨二十个文件、多个服务的 ID 和几种可能原因去追,让子代理去查并返回文件位置和证据,比在主会话里边读边聊更清楚。

但成本也真实存在。让主 Agent 自己决定何时派生子代理去收集不同模型的实现文档,经常会出现两种浪费:它把时间花在无用的事情上,token 消耗也很高;或者信息在转交中丢失,最后还要回主会话重查。重复劳动、委派失败导致整个任务失败,都要算进去。

Claude Code 里还有两个仍处实验阶段的功能,值得知道但不必急着用。Agent Teams 允许 worker 之间更直接地通信,2026 年 10 月时仍默认关闭,需要在 settings.json 里设置:

{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}

Ultracode 则是用生成的 JavaScript 脚本编排并行子代理,脚本在独立运行时执行,可以程序化管理循环、条件分支、验证轮次和重试。它适合把多代理流程固定下来,但也意味着多了一层需要调试的脚本。

worktree 值得单独说,因为它和多个子代理同时工作直接相关。

Git worktree 比 AI 编程 Agent 早出现很多年,只是现在多个 Agent 同时写代码,它才变得更重要。同一个仓库可以同时维护多个工作目录:各自有独立分支和检出状态,共享同一个 Git 数据库。

你的电脑
├── project/
│   ├── 代码文件 (your-branch)
│   └── .git/  ← 共享的 Git 仓库
│
├── project-new-design/  ← 新的 worktree
    └── 代码文件 (feature/new-design)

优势不只是“整洁”,而是多个工作目录由一个 Git 仓库管理,不需要你在多个独立仓库之间同步。

Claude Code 创建子代理时可以直接指定 isolation: worktree:

---
name: builder
description: Implements independent features
model: opus
effort: high
tools: Read, Grep, Glob, Edit, Write, Bash
isolation: worktree
maxTurns: 30
---

You are responsible for implementing a delegated feature.

这样它会在独立的 worktree 里工作,结束后把改动留在该 worktree 的分支上,等你或主 Agent 合并。

但 worktree 不是隔离的保证。不同 Agent 改不同功能,不代表实现互相兼容;文本上能干净合并,也可能在语义上冲突。比如 A 改了某个函数的返回类型,B 在另一个文件里仍然按旧类型写代码。两个文件不冲突,合并成功,运行时却会坏。这种问题只能靠编译、测试、代码审查或其他验证发现。另外,每个 worktree 仍然占用磁盘空间。

07Skill:把踩过的坑写成流程

Skill 是一份“某件事该怎么做”的蓝图。它可以包含说明、参考资料、脚本、测试和评估,交给 Agent 执行。

它和 Agent 的分工可以用一句话区分:需要独立上下文去跑任务,用子代理;需要把一套可重复的做法写下来,用 Skill。

Skill 要解决的是某个具体流程和不明显的坑,不是教 Agent 做软件工程。比如与其说“UI 要做好”,不如写一份具体的 UI 审查流程,规定怎么走查、要收集哪些证据;与其说“数据库要小心”,不如写一套带脚本和参考资料的迁移与回滚流程。

Anthropic 提到过一个判断:如果 Agent 能验证自己的工作,它就更容易独立跑完。产品验证类 Skill 对输出质量的影响最可测,例如在浏览器里跑注册和结账流程。

一个 Skill 的主体是 SKILL.md,里面有名称、描述和工作流步骤。描述是最关键的第一步,因为它决定 Skill 会不会被选中。

一个数据库迁移 Skill 如果描述成“用于数据库、查询、模型或持久化”,几乎任何数据库任务都可能触发它;明确写“schema 迁移与发布”会准确得多。

正文里最有价值的部分,往往是“坑”那一节:那些不明显、从真实失败里学来的东西。常见的例子包括内部库的意外行为、误导性的命名,以及看起来成功但下游已经失败的部署命令。

再往下是脚本。比如 Agent 每次都要重新写 Python 代码来比较数据库 schema,Skill 里可以直接放一个已经验证过的 compare_schema.py。取数、清洗、转换这类固定动作,也可以做成脚本。

理想状态下,Skill 提供流程和工具,模型负责判断怎么把它们用到当前任务上。

目录结构上,Claude Code 和 Codex 各有一套,通常用软链接共享同一份内容:

project/
├── .claude/
│   └── skills/
│       └── inference-engineer/
│           ├── SKILL.md
│           ├── references/
│           ├── scripts/
│           ├── tests/
│           └── evals/    # 仅 Claude,Codex 不读
└── .agents/
    └── skills/
        └── inference-engineer → ../../.claude/skills/inference-engineer

SKILL.md 一旦加载,它的说明会在之后每条消息里都留在上下文。所以主文件建议控制在 500 行以内,更长的内容放进 references/。scripts/ 放可执行辅助脚本,tests/ 验证这些脚本本身,evals/ 则测试“用了这个 Skill 的 Agent 是否做对了”。

如果写的是一个模型部署或推理优化 Skill,开头至少要把这些字段交代清楚:

字段
要回答的问题
模型产物
精确的模型 ID、版本、许可证、是否需要 trust_remote_code
任务边界
整篇文档、单页、裁剪区域,还是多阶段流水线
输入
支持格式、图片数量、PDF/多页行为、分辨率策略
Prompt
实际任务提示词、chat template、特殊 token、是否开启推理
上下文
总上下文、视觉 token/像素上限、输出上限
输出
文本/Markdown/JSON 契约、停止条件、重复控制
后端
支持的推理引擎与版本、必需插件、同步/异步接口
数值模式
dtype/量化方式与硬件限制
批处理
原生批处理、连续批处理、动态批处理,还是都不支持
资源
权重内存、KV cache、CPU/内存、候选 GPU

没查到的事实就写没查到,不要按同名模型类推一个 prompt 或 token 上限。

Claude Code 可以用 /skill-creator 创建 Skill,也可以手写。手写的最小形态是这样:

---
name: stats-api
description: >
  Investigate statistics using the internal API, including
  following relationships between summary and detail results.
when_to_use: >
  Use for investigations requiring statistics to be traced
  through multiple API responses.
---

Instructions
1. do this
2. then this
Note: this is important too.

when_to_use 会追加到描述后面,两者合计上限是 1,536 个字符。

Skill 还可以接受参数。比如把某个统计记录的 ID 传进去:

---
name: investigate-stat
description: Investigate a statistics record through the internal API
argument-hint: "[stat-id]"
arguments:
  - stat_id
disable-model-invocation: true
user-invocable: true
---

Investigate statistics record $stat_id.
Follow the documented drill-down workflow in /references/drill-down.md.
Use the script scripts/get_data.py to get API data, validate in tests/validate_data.py
Report the records and evidence used.

disable-model-invocation: true 表示只有人能调用它,模型不能自己触发;user-invocable: true 则保证你能在命令行里用 /investigate-stat id-123 这样调用。

工具权限也可以在 Skill 头里声明:

---
name: inspect-project
description: Investigate project files and report findings
allowed-tools:
  - Read
  - Grep
  - Glob
disallowed-tools:
  - Write
  - Edit
---

这里有个容易忽略的漏洞:只禁掉 Write 和 Edit,并不能保证只读,因为 Agent 仍然可能通过不受限制的 Bash 命令写文件。

Claude Code 还支持 context: fork,让 Skill 在另一个干净上下文里运行,而不是加载进主会话。配合内置的 Explore 代理,可以变成一次独立调查:

---
name: review-api
description: Independently investigate an API issue
model: sonnet
effort: high
context: fork
agent: Explore
background: false
---

Investigate the API issue supplied in $ARGUMENTS.
Read relevant code and documentation.
Return findings with evidence.
Do not modify files.

Skill 也可以只在特定路径下触发,效果类似前面说的 rules:

---
name: subscription-review
description: Review changes to the subscription and credit system
paths:
  - "src/payments/**/*.ts"
  - "src/subscriptions/**/*.ts"
---

Codex 的 Skill 结构略有不同,多了一个可选的 agents/openai.yaml,用来放展示信息、调用策略和外部工具依赖:

.agents/skills/review-schema-migration/
├── SKILL.md
├── agents/
│   └── openai.yaml
├── scripts/
├── references/
└── assets/
interface:
display_name: "Stats API Guide"
short_description: "Investigate statistics using the Safron API"
default_prompt: "Use this skill to investigate a tech trends"

policy:
allow_implicit_invocation: true

没有这个文件也能用,基础 Codex Skill 只需要 SKILL.md。Codex 的全局 config.toml 还可以控制 Skill 目录的 token 预算,或者单独禁用某个 Skill:

[skills]
max_context_tokens = 6000

[[skills.config]]
path = "/Users/me/projects/my-app/.agents/skills/old-api/SKILL.md"
enabled = false

那 Skill 到底有没有用?SWE-Skills-Bench 测过大约 565 个仓库级任务和 49 个公开软件工程 Skill,使用 Claude Code 和 Claude Haiku 4.5。

结果很值得记住:49 个 Skill 里,39 个对通过率没有影响,7 个提高了通过率,3 个降低了通过率。

造成负面效果的三个是 springboot-tdd(−10.0 个百分点)、linkerd-patterns(−9.1)、django-patterns(−9.1)。以 Linkerd 为例,Agent 本来能选对 API 版本,用了 Skill 反而照抄了旧版本,还加了一个无关资源。

真正有帮助的 risk-metrics-calculation 把成功率从 70% 提到 100%,同时少用了 34.8% 的 token;tdd-workflow 把成功率从 21.4% 提到 28.6%,但多用了 78.6% 的 token。

同一项研究还按领域看了差异:医疗、制造、网络安全这些领域,专门领域 Skill 带来的提升更明显;软件工程领域最弱。这符合直觉——基础模型越不熟悉的专业流程,越可能从外部知识里受益。2026 年 7 月的一次更新中,最强模型在 SWE 任务上大约提升了 10 个百分点,而不是 4.5,但测量口径可能不同,比较时要注意。

这也带出了评估问题:Skill 被触发,不等于它有用。

Claude Code 的 Skill Creator 可以做两类测试。一类是发现性测试:这个 Skill 会不会在正确的任务上被选中,在错误的任务上不触发。另一类是效果测试:在同一批任务上跑“有 Skill”和“无 Skill”两组对照,看结果差异。

效果测试会生成一个 evals.json:

{
"skill_name": "stats-api",
"evals": [
{
"id": 1,
"prompt": "Investigate why keyword traffic for 'renewable energy' dropped last month.",
"expected_output": "A traced investigation across the summary and detail endpoints, with the records and evidence used.",
"files": []
}
]
}

每个测试用例会同时启动两个子代理,一个带 Skill,一个不带,使用相同提示,都从干净上下文开始。运行产物放在 Skill 旁边的 stats-api-workspace/iteration-1/<case>/ 下,分别记录 with_skill 和 without_skill 的输出、耗时和 token;最后由 grader 代理逐条检查预期并写入 grading.json,汇总成 benchmark.json。根据反馈重写 Skill 后,可以继续跑 iteration-2/。

发现性测试用的是 eval_set.json:

[
{ "query": "Investigate why keyword traffic for 'renewable energy' dropped last month.", "should_trigger": true},
{ "query": "Fix the failing unit test in api_client.py.", "should_trigger": false}
]

优化循环会在后台把每个查询跑三次,得到一个相对稳定的触发率,再让模型根据失败样本改写描述,然后重测。

这套流程不代表 Skill 一定值得写。更实际的态度是:先确认有一个流程真的被反复解释,再写 Skill;写完顺手评估它,至少确认它会在该触发的时候触发,并且真的改善了结果。

08/loop、/goal、/batch 各自解决什么

除了自己写 Skill,工具本身也带了一些值得知道的命令。挑三个最常用的说。

/loop 是一个 Skill,用来在本地 Claude Code 会话里安排重复工作,本质上就是一个定时任务:

/loop 5m check the deploy
/loop check CI and address any new review comments
/loop

第三种写法不带间隔,由 Claude 根据观察到的情况决定下次什么时候跑,范围大概在 1 分钟到 1 小时之间。只写 /loop 时,它会读 .claude/loop.md 里的默认提示词:

# .claude/loop.md
Check the pull request associated with the current branch.
Use the review-pr Skill to inspect new review comments and failing CI checks.
Address actionable issues and verify changes.
If there is nothing new, report that no action is needed.
Do not push changes without authorization.

要清楚它不是持续自主推理:Claude 每轮结束后拿到新信息,再决定下一轮做什么。

限制也很明确:需要本地会话一直开着,而且会在七天后过期。更长期的任务可以换成云端 /schedule,每次执行会新开一个云会话、克隆指定仓库,也能调用仓库里提交的 Skill;代价是每次都是全新会话,最小间隔大约一小时。相对地,云端任务可以响应 GitHub 事件或 API 调用,比反复轮询“有没有变化”更合适。

/goal 关注的是结果,而不是做法。它解决的问题很具体:Agent 可能记住了最初的目标,却逐渐被某个子任务带偏,最后认真地在解决另一个问题。

一个可用的 /goal 需要三个东西:可观察的成功标准、约束条件、停止条件。

/goal Reduce p95 checkout latency below 120 ms on the checkout benchmark while keeping the correctness suite green.

反面例子是把“这个 benchmark 到底公不公平”直接当目标。这句话没法定义“公平”,也没法排序哪些问题更重要,最后很容易跑上几个小时,陷进兔子洞。

机制上,每一轮结束后会有一个更小的模型判断条件是否满足、不满足或不可能满足,然后决定是否继续。它是执行控制,不是独立验证:它只能判断对话里已经呈现的证据,如果 Agent 在对话里说了一件不真实的事,评估器不会自动发现。所以目标里最好带上确定性的验证手段;对奖励黑客问题感兴趣的,可以去读 SpecBench 相关的研究。

/batch 是大规模并行执行,用到了前面说的子代理和 worktree。文档里的例子是代码迁移:

/batch migrate src/ from JavaScript to TypeScript

按文档描述,它会把工作拆成 5 到 30 个独立单元,先给出计划,然后为每个单元在隔离的 worktree 里派生一个后台子代理,各自实现、跑测试、提交改动。

这适合文件所有权可以清晰分开的任务,但也继承了 worktree 的问题:各单元的改动可能做出互相矛盾的假设。对耦合紧密的迁移,顺序执行可能反而更省事,哪怕看起来文件已经分得足够开。

09社区 Skill:先看安全,再看效果

Skill 这个概念出现的时间不长,但生态已经很大。Vercel 在 2026 年 9 月 25 日的报告里提到:到 2026 年 8 月,注册表里有 100 万个 Skill,记录在案的安装量是 2.8 亿次。

不过分布极其集中:62% 的安装来自排名前 0.04% 的 375 个 Skill,接下来的 32% 来自前 1.16%。接近一半的 Skill 只被安装过一次。

找 Skill 的地方不少:Anthropic 官方仓库、ComposioHQ 的 awesome-claude-skills、VoltAgent 的 awesome-agent-skills,以及 skills.sh 的排行榜;社区里比较常被提到的还有 mattpocock/skills、emilkowalski/skills。一些讨论显示,很多开发者仍然是通过 GitHub 和 Reddit 发现 Skill,而不是应用市场。

对社区 Skill,态度可以保守一点,理由有三个。

第一,有 Skill 不等于有效。前面那项 SWE-Skills-Bench 里用的都是热门 Skill,大多数并没有改变结果,少数还让表现变差。

第二,模型变强以后,很多 Skill 会变成冗余。软件工程领域在这项研究里提升最小,说明基础模型在这类任务上本来就做得不错。

第三,安装量和 GitHub 星数都不是效果指标,更不能当安全指标。

安全是更实际的问题。Snyk 检查过 3,984 个 Skill,发现 76 个恶意 Skill,13.4% 至少有一个严重级别的安全问题;Nvidia 分析了 31,132 个 Skill,发现 5.2% 有恶意意图迹象,26.1% 存在漏洞,检查范围包括提示注入、数据外泄和不安全依赖。

所以安装第三方 Skill 前,至少用Snyk Skill Inspector(https://labs.snyk.io/experiments/skill-scan/)
或
NVIDIA SkillSpector(https://github.com/NVIDIA/SkillSpector)扫一遍,再决定要不要放进项目。

10写在最后

Harness 拆开看是权限、项目说明、规则与文档、记忆、计划、子代理与 worktree、Skill、内置命令这几层,但真正要避免的,是“全都配上”。

每一层都有成本:权限收紧会降低 Agent 的活动能力,文档和记忆会占用上下文,子代理会消耗 token,Skill 可能让模型偏离本来正确的做法。前面那些研究反复说明的也是同一件事——更多结构不等于更好结果。对较弱的模型,计划能显著提升成功率;对较强的模型,过度计划反而可能降低准确率。

比较稳的顺序是:先出现真实问题,再补对应的那一层。Agent 误读了不该读的文件,就配权限;同一个项目约定解释了三遍,就写进 AGENTS.md;某个流程反复出错,再考虑 Skill;任务确实需要独立上下文,才派子代理。配完要验证——读一个文件、问一条规则、跑一组对照,比相信配置已经生效更可靠。

云朵君自己的判断是,harness 的价值不在于“搭得多完整”,而在于每一层都能回答一个问题:它解决了哪个已经发生的问题。回答不出来的那一层,先别加。

工具会持续更新,今天能用的命令和字段,过几个月可能就变了。配置清单会过时,稳定的只有这套判断顺序:先看问题,再选机制,最后验证。这比背住任何一套模板都管用。


Image