上下文窗口是公共资源：Harness技能写作的3个省Token自检问题-开发者社区

上下文窗口是公共资源：Harness技能写作的3个省Token自检问题

【免费下载链接】harnessA meta-skill that designs domain-specific agent teams, defines specialized agents, and generates the skills they use.项目地址: https://gitcode.com/GitHub_Trending/harness/harness

Harness 是一款为 Claude Code 设计智能体团队、生成配套技能的开源元技能插件。它的官方技能写作指南把"上下文窗口"比作公共资源——你写进 SKILL.md 的每一句话都在消耗模型的注意力预算。本文带你用3个省Token自检问题精简 Harness 技能文本：删掉模型已知内容、只留不写就会犯错的规则、用例子替代冗长解释，让你的技能文件更短、更稳、更省钱。

Harness是什么：给AI团队写"说明书"的元技能

Harness 的定位是"团队架构工厂"：你只需说"为这个项目构建一个 harness"，它就会自动分析你的领域，从 6 种预设架构模式（流水线、扇出/扇入、专家池、生产者-审查者、监督者、层级委派）中选型，然后生成一整套智能体定义（.claude/agents/）和技能文件（.claude/skills/）。

生成的技能不是随意堆的文档，而是有严格结构的"说明书"。问题在于：说明书越厚，智能体每次加载时烧掉的Token越多，回答也越容易被无关信息带偏。这正是 Harness 写作指南反复强调的那句话——

上下文窗口是公共资源。每一句话都必须值得它的Token成本。 —— skills/harness/references/skill-writing-guide.md

那么，怎么写才"值得"？官方指南给出了3个自检问题。

自检问题1：这句话模型本身知道吗？

"这是模型已经知道的内容吗？" → 是，就删掉。

模型早就知道"Python 是编程语言""HTTP 是无状态协议"这类常识。把它们写进技能文件，等于花Token说废话，还会稀释真正重要规则的权重。

✅该保留的：项目特有约定——特殊字段名、输出格式、边界情况坑点。例如 skills/harness/references/skill-writing-guide.md 中规定评测结果文件必须使用text/passed/evidence三个字段名、禁止变体——这种"不写就猜错"的细节，Token花得值。

❌该删掉的：通用知识、面向用户的说明书、技能生成过程的历史记录（这些在 skill-writing-guide.md 中被明确列为"不要放进技能"的内容）。

自检问题2：删掉它模型会犯错吗？

"如果没有这句解释，模型会犯错吗？" → 会，才保留。

这是反向验证：对每一段文字问"删了会出什么事"。答案若是"什么也不发生"，这段文字就是纯成本。

Harness 自己的主技能文件就是榜样：skills/harness/SKILL.md 明确规定正文以500 行以内为目标，"不担重量"的内容要么删除，要么移进 references/。它把大量细节（架构模式详解、测试方法、QA 指南）拆成了 6 个参考文件，正文只留决策流程。

自检问题3：一个例子能否顶三段说明？

"一个具体例子是否比长篇解释更有效？" → 是，就用例子。

大模型对"对照示例"的吸收能力远强于抽象规则描述。官方写作指南中大量使用"坏例 vs 好例"的对比模式，比如描述技能触发词：

坏例："一个处理PDF的技能"——模糊，模型不知道何时触发
好例："执行PDF读取、表格提取、合并、OCR等全部PDF操作。只要提到.pdf文件或要求PDF产出，必须使用此技能。"——具体动作 + 明确触发场景

一段对比例子通常比三段解释更短、更准。如果你的技能里出现"必须""严禁"这类强硬指令，不妨顺手追问一句：为什么？skill-writing-guide.md 的 Why-First 原则指出，模型理解了原因，才能在没写过的边界情况里自己做出正确判断——这也比罗列十条禁令更省Token。

进阶技巧：渐进式披露，按需加载才省Token

三个自检问题管的是"每一句话"，渐进式披露（Progressive Disclosure）管的是"每一层文件"。Harness 把技能设计成 3 级加载结构，像洋葱一样分层消耗上下文（详见 skills/harness/SKILL.md）：

层级	加载时机	大小目标
元数据（name + description）	始终在上下文中	约100词
SKILL.md 正文	技能被触发时	500行以内
references/ 参考文件	需要时才读	无限制

举个官方给出的例子：一个云部署技能把细节拆成aws.md、gcp.md、azure.md三个参考文件，正文只留"选择哪个云就只读哪个文件"的指针——用 AWS 的用户永远不会为 Azure 的文档付Token。skills/harness/references/ 目录本身就是这个模式的活教材：6 份参考文档各管一摊，正文按需引用。

📌配套检查：写完技能别忘了用测试验证省Token是否以质量为代价。skills/harness/references/skill-testing-guide.md 提供了"带技能 vs 不带技能"对照测试的方法论，还能记录total_tokens实测数据，量化你的精简成果。