agents-best-practices：为 agentic harness 设计提供的、与厂商无关的 skill

多数 agent skill 教模型如何写出更好的 prompt。DenisSergeevitch/agents-best-practices 反过来——它提醒你：模型只是运行时的一部分，更关键的是它周围的 harness。

为什么这个 Skill 重要

README 的中心句是："The model proposes actions; the harness validates, authorizes, executes, records, and returns observations."（模型提议动作，harness 校验、授权、执行、记录，再把观察结果返回。）一句话讲完了整个哲学。skill 的目标是辅助设计、生成 MVP 蓝图、审计、重构并解释 agentic harness——README 明确指出，它的适用范围不限于编程 agent（研究、客服、运营、销售、财务、数据分析、采购、法务、医疗、教育、工作流自动化同样适用）。

仓库在 GitHub 上有 2.2k star，MIT 许可。通过可移植的 SKILL.md 入口，Codex、Claude Code 以及其他支持 Agent Skill 的运行时都能用。

skill 提供 21 份参考文档，放在 references/，按"按需取用"组织：

• mvp-agent-blueprint.md——按领域定制的 MVP harness 蓝图
• coding-agents.md——面向仓库的编程 agent 叠加层
• architecture.md——组件模型与 harness 边界
• agentic-loop.md——循环不变量、重试、预算、停止
• tools-and-permissions.md——类型化工具、风险等级、审批
• environment-adaptive-tools.md——延迟绑定的发现、探针、绑定与漂移
• speculative-tool-execution.md——预启动、精确认领、浪费、取消
• planning-and-goals.md——规划模式与长期目标
• workflow-orchestration.md——分解工作流、数据包、校验
• self-refining-recursive-harnesses.md——可编程上下文、递归、迭代
• context-memory-compaction.md——上下文、记忆、检索、压缩
• prompt-caching-and-cost.md——稳定前缀与成本敏感的上下文
• skills-and-connectors.md——Agent Skills、MCP、连接器、工具检索
• system-prompts-instructions.md——指令层级与模板
• provider-api-patterns.md——OpenAI、Anthropic、兼容 API
• security-observability.md——护栏、追踪、上线门槛
• evals.md——评测策略、测试用例、追踪评分
• agent-legibility-feedback-loops.md——可信源交付件与清理
• checklists.md——实现与审计清单
• coverage-audit.md——主题覆盖率核验
• source-links.md——官方参考与延伸阅读

下面是九条哲学准则，按需取用：

1. Harness 才是行为主体，模型不是——模型提议，应用代码负责校验、授权、执行与记录。
2. 每次工具调用都必须有结果——拒绝、超时、参数畸形与中断也是观察结果。
3. 风险等级决定循环——读、草稿、写、对外通信、财务动作、破坏性动作与特权操作需要不同的权限路径。
4. 草稿与提交分离——高风险副作用要求在 prompt 之外留下审批记录。
5. 上下文是被构造的，不是被倾倒的——按需取量、标注信任边界、压缩后保留活跃状态。
6. 长跑任务需要预算——步数、时长、token、成本、工具调用次数都要纳入产品定义。
7. Skills 与连接器渐进披露——先暴露名字与简介，需要时再加载细节工作流。
8. 发现不授予权限——延迟绑定的能力仍需宿主校验、范围绑定与调用时的策略执行。
9. 反复出现的问题要变成 harness 的能力——校验器、工具、文档、评测或策略，比重复的 prompt 建议更有效。

安装

README 主推的安装路径是 npx skills CLI：

npx skills add DenisSergeevitch/agents-best-practices -g

-g 表示安装到 user 级（全局），所有项目都能发现。去掉它就是项目级。

如果没法用 skills CLI，README 也列了 Codex 与 Claude Code 的手动安装路径（user 级与项目级）。Claude Code user 级：

mkdir -p "$HOME/.claude/skills"
git clone https://github.com/DenisSergeevitch/agents-best-practices.git \
  "$HOME/.claude/skills/agents-best-practices"

实战：为真实业务生成 MVP 蓝图

有一个具体领域（举例：账户续约风险），需要一个最小且生产可用的 harness——而不是一份泛泛的最佳实践清单。

Step 1. 直接发起：

Build an agent for account renewal risk. It should read CRM, support tickets, and usage data, then draft renewal actions.

Step 2. skill 会引导 agent 从"审批守门的 Level 2 harness"起步，目标只有一个——产出续约风险简报，并给人类客户经理起草后续动作建议。skill 给出的 MVP 循环：

user/task -> context builder -> model call -> typed tool call
  -> schema validation -> permission check -> execution or pause
  -> structured observation -> next step or final brief

Step 3. skill 推荐的最小工具集：每个数据源一个读工具（read_account_profile、list_support_tickets、fetch_usage_summary），一个起草工具（draft_customer_email），以及一个审批门槛（request_approval）。不要裸露的 send_message 或 write_database——一切都要类型化、有范围、可审计。

Step 4. 上线前定义一个 launch gate：一个固定的样本集（例如 20 个账户）、trace 审核、未经审批的对外发送一律禁止、人工接受率要达标（示例门槛是 80%）。

Step 5. 实现时把 mvp-agent-blueprint.md 打开——蓝图里的每一步都来自这份参考。打开前先在脑里把 loop 默念一遍：上下文→模型→类型化工具→校验→授权→执行/暂停→结构化观察→下一步或最终简报，任何一步缺位都得在 MVP 里补齐。

实战：审计一个脆弱的现有 agent

已有的研究 agent 经常把工具跑到超时，context 压缩后又忘了自己为什么做那个决定。问题出在 harness，不是 prompt。

Step 1. 发起审计：

Our research agent sometimes runs tools forever and forgets why it made a decision after context compaction. Audit the harness.

Step 2. skill 把故障定位到运行时层，而不是 prompt 层：没有硬性的步数/工具/时长/成本预算；压缩保留散文却丢掉活跃审批；工具返回结果未做大小限制，并且把可信/不可信数据混在一起；模型输出→工具调用→观察这条链没有事件 trace。

Step 3. skill 给出的修复顺序：

1. 加上循环预算与终止原因。
2. 把计划、审批、待办、交付件存到 prompt 之外。
3. 压缩时重水化（rehydrate）活跃状态，而不是聊天历史。
4. 加上注入、工具结果缺失、超时、预算耗尽这几类评测。

Step 4. 每个修复都对应一份具体参考——agentic-loop.md、context-memory-compaction.md、security-observability.md、evals.md。动手前先把对应的参考读完，references 才是 how-to，README 是索引。每修一条就补一条 eval——注入、工具结果缺失、超时、预算耗尽是 README 点名的四类失效。

技巧

• 把这个 skill 当成索引来用——README 的使用案例决定了你该打开 21 份参考中的哪一份。
• 用"风险等级决定循环"这条原则为每个类型化工具的存在正名：归不进任何一个风险等级的工具，就不该以"宽泛工具"的形态存在。
• 审批记录要落在 prompt 之外——按请求键值存到持久化存储，而不是模型的聊天历史里。否则一旦上下文窗口滚动或被压缩，审批状态就丢了，模型会以为可以重新发起副作用。
• 压缩要重水化活跃状态（待办、计划、审批），不能为了保留聊天散文而丢状态。README 的 context-memory-compaction.md 是这块的深入参考——按它对齐你自家的压缩实现。
• 预算（步数、时长、token、成本、工具调用次数）是产品定义的一部分，不要事后补。README 的 "What this is" 小节把规划模式、审批守门的执行、工作流编排这些与预算直接相关的组件列为一等公民，而不是附加件。

何时不用这个 Skill

如果你的目标是找一个多 agent 编排框架，README 明确说"not a multi-agent framework by default"——先从单 agent MVP 起步。如果你想用纯 prompt 安全策略绕开运行时授权、沙箱或审计日志，README 也写明"not a replacement for runtime authorization, sandboxing, or audit logs"——应当从运行时层补齐。同一段还写明：它也不是暴露 execute_anything、send_message、write_database 这类宽泛工具的理由——动作应当包装成窄的类型化工具。如果只是想给单次任务写一段 prompt，这个 skill 比任务本身还重。

查看 排行榜 了解更多 skill。