TILs

高可靠的 Agent Skill 应采用“最小必需、按需扩展”的结构：仅保留必需的 SKILL.md，根据实际需要添加 scripts/ 和 references/，避免为形式完整而创建空目录。description 是唯一常驻系统提示的部分，必须同时说明技能做什么以及何时触发，但不应包含流程摘要，以免 Agent 跳过正文。 Skill 的正文应围绕可执行行为组织：用具体命令替代笼统要求，用反向排除条件辅助激活判断，用 Common Rationalizations 预先反驳 Agent 可能跳过步骤的借口，并通过 Red Flags 和 Verification 定义可观察的违规信号与基于证据的退出标准。 脚本应将结构化 JSON 输出到 stdout、状态信息输出到 stderr，并使用 set -e 快速失败。由于执行脚本本身不消耗上下文，只有输出会消耗上下文，因此应优先把重复或复杂逻辑放入脚本，并将 SKILL.md 控制在约 500 行以内、引用层级限制为一层。核心原则是：流程优于知识、具体优于笼统、证据优于假设、预防合理化、渐进披露和持续关注 Token 成本。

智能体平台的合理边界是：业务应用掌控界面、业务上下文、数据记录、权限与审批；Harness 负责会话状态、上下文延续、工具协调、沙箱执行、流式事件、失败恢复和人工授权；MCP 或业务工具负责访问内部数据与执行受控操作。核心原则不是把业务搬进 AI，而是把 AI 嵌入现有业务系统。 集成可按复杂度分为三种：codex exec 适合脚本、CI 和一次性后台任务；Codex SDK 适合在应用代码中启动、恢复和流式接收智能体任务；app-server 适合长期会话、事件处理、任务中断、工具暴露及审批交互。 对于会产生外部副作用的操作，仅有人工审批仍然不够。宿主应用还必须保存幂等操作号、外部系统回执和最终对账状态，以区分“操作尚未执行”“正在执行”和“已执行但响应丢失”，避免会话恢复或重试时重复执行。