代理最佳实践技能
一套供应商中立的 Agent Skill，用于设计、审计和重构代理执行框架。
证据显示：README 和 SKILL.md 强调最小权限原则，如窄类型工具、权限检查在模型外部、风险分级（读、草稿、写、外部通信等）。用户确认通过审批门和草稿/提交分离实现。数据流透明度通过事件追踪和结构化观察体现。敏感数据处理通过信任边界标签和上下文构建原则体现。依赖安全方面，安装方式使用 npx 和 git clone，未提及依赖锁定或漏洞扫描，因此扣分。外部影响通过审批门和风险分级控制。回滚方面，未明确提及回滚机制，仅提到审计日志，因此扣分。来源归属通过 source-links.md 和引用官方文档体现。
证据显示：文档内部一致，哲学原则与参考文档一致。依赖可用性方面，依赖外部服务（如 npx skills）和未固定版本，存在不确定性，因此扣分。失败消息方面，文档强调工具调用结果（包括拒绝、超时、格式错误）作为观察，但未提供具体错误消息模板，因此扣分。
证据显示：目标受众明确（构建代理系统的开发者），场景覆盖 MVP 蓝图、审计、工具设计等。能力边界通过“What this is not”明确。触发精度通过 SKILL.md 中的触发规则（但未提供具体内容，因此扣分）。环境适配通过支持 Codex、Claude Code 和其他兼容运行时，但未提供具体配置细节，因此扣分。
证据显示：信息架构清晰，有 README、SKILL.md、references/ 目录。安装说明详细，提供多种安装方式。命名稳定性方面，未提及版本控制或命名约定，因此扣分。示例和 FAQ 通过用例和常见问题提供。已知限制通过“What this is not”和哲学部分体现。许可证为 MIT，明确。版本变更日志缺失，因此扣分。维护责任方面，作者未验证，但提供了联系方式（GitHub），因此扣分。
证据显示：输出可用性通过提供具体蓝图、清单和参考文档体现。边际价值通过提供跨提供商的通用最佳实践，避免重复造轮子。成本效益通过强调预算和成本遥测，但未提供具体成本数据，因此扣分。
证据显示：声明可追溯，通过 source-links.md 引用官方文档。跨来源佐证方面，仅依赖官方文档，未提供独立验证，因此扣分。事实与推断分离方面，文档区分了推荐做法和来源，但未明确标注哪些是事实哪些是推断，因此扣分。
- 依赖未固定版本，安装方式可能引入供应链风险。
- 未提供回滚机制，审计日志不足以支持恢复。
- 未提供版本变更日志，难以追踪更新。
- 发布者身份未验证，维护责任不明确。
这个 Agent 能做什么，适合哪些场景？
agents-best-practices 是一个以 SKILL.md 为入口的 Agent Skill，提供关于代理运行时设计的综合参考资料。它涵盖模型-工具-观察循环、类型化工具、权限检查、规划模式、工作流编排、上下文记忆与压缩、提示缓存、可观测性、评估和发布检查清单。该仓库包含一个主 SKILL.md 文件和一个 references/ 目录，其中包含针对 MVP 蓝图、编码代理、安全、评估等主题的专门指南。它被设计为与 Codex 和 Claude Code 兼容，并且可以手动安装或通过 npx skills 安装。
安装后，该技能会在对话涉及代理架构时激活。它提供了用于生成最小可行产品（MVP）代理蓝图的参考指南（references/mvp-agent-blueprint.md），用于审计和修复现有实现（references/agentic-loop.md 等），用于设计工具和权限（references/tools-and-permissions.md），以及用于实现规划模式、工作流、上下文压缩、提示缓存、评估和启动检查清单。它通过指导用户使用特定的参考文件来响应诸如“构建一个代理...”或“审计这个代理...”之类的提示。
- 希望为特定领域（如账户续约风险）生成最小可行代理蓝图的产品经理，需要批准门控的工作流程。
- 拥有脆弱代理（如研究代理）的工程师，希望审计运行时失败（如无限制的工具执行、压缩后丢失状态）并应用修复。
- 开发运维代理的工程师，需要为 Slack、Linear 和内部 API 设计工具和权限，确保风险分类。
- 希望实现规划模式而不使代理被动的开发者，或寻求分解大型任务的开发者。
- 致力于在长期运行代理中优化提示缓存和成本的开发者。
- 准备代理投入生产的团队，需要启动检查清单和评估策略。
这个 Agent 有哪些优点和局限？
- 供应商中立：兼容 Codex 和 Claude Code，并遵循可移植的 SKILL.md 规范。
- 基于文件的参考资料，无需额外服务或 API 密钥。
- 涵盖运行时纪律，而不仅仅是提示：包括工具权限、预算、压缩和评估。
- 强调窄类型工具和安全检查，降低意外副作用的风险。
- 需要手动安装（克隆到特定目录），不属于官方市场，需要用户操作。
- 作为参考实施，需要适配到具体的代码库和运行环境。
- 依赖 Agent Skills 生态系统，可能限制非兼容代理的支持。
- 文档是参考，而非自动执行；使用者需自行应用建议。
如何安装或部署这个 Agent？
安装方式：
A. 使用 npx skills（需要 Node.js）：
npx skills add DenisSergeevitch/agents-best-practices -gB. 或者将以下提示粘贴给您的 AI 代理：
Install the agents-best-practices skill for me:
1. Clone https://github.com/DenisSergeevitch/agents-best-practices into my user-level skills directory as `agents-best-practices/`. Use the skill directory my agent reads on this machine, for example:
- Codex: ~/.codex/skills/
- Claude Code: ~/.claude/skills/
2. Verify that SKILL.md, icon.jpeg, and the references/ directory are present.
3. Confirm the install path when done.C. 手动安装路径：
# Codex
mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
git clone https://github.com/DenisSergeevitch/agents-best-practices.git \
"${CODEX_HOME:-$HOME/.codex}/skills/agents-best-practices"
# Claude Code, 用户级
mkdir -p "$HOME/.claude/skills"
git clone https://github.com/DenisSergeevitch/agents-best-practices.git \
"$HOME/.claude/skills/agents-best-practices"
# Claude Code, 项目级
mkdir -p .claude/skills
git clone https://github.com/DenisSergeevitch/agents-best-practices.git \
.claude/skills/agents-best-practices如何使用这个 Agent？
安装后，技能会在对话触及代理架构时自动激活。对于 MVP 蓝图，请说“构建一个用于 [领域] 的代理”，技能将引导您遵循 references/mvp-agent-blueprint.md。若要审计现有代理，请描述其症状，技能将参考 references/agentic-loop.md 和 references/security-observability.md 等。若要设计工具和权限，请指定您的系统，技能将使用 references/tools-and-permissions.md。您还可以直接提出诸如“如何添加规划模式？”之类的问题，技能将指向相关参考。