用途：这是一份在创建或改进编码智能体扩展之前应阅读的设计指南，核心是先确定交互形态，再进入实现。
主要能力与主张：从用户期望的体验出发，而不是从扩展机制出发。实现前需识别谁发起工作流、发生频率、现有 harness 或 CLI 已提供什么、工作流真正需要哪种接口。在直接使用 CLI、脚本、skill、用户触发的斜杠命令、人类 UI、智能体工具或扩展集成之间做选择，并与用户确认形态后再写代码。优先选最小的缺失组件：若 CLI 已具备能力但难以在 harness 中使用，应薄封装而非重建；只有当 UI、状态、钩子、事件或工具注册等集成需求出现时，才值得写自定义扩展行为。不要仅因扩展能注册智能体工具就注册：常驻工具必须能通过重复自然使用或提供智能体无法触达的能力来证明其模型成本合理；罕见或显式请求的工作流，优先用户触发命令、脚本或 CLI，仅在智能体需要调用指引时才用 skill。
适配真实 harness：围绕用户实际环境与约定设计，复用其导航、设置、命令和工具模式，只为当前工作流实际存在的风险与需求添加工程机制，不因测试、权限、重试、兼容层或可配置性听起来合理而把个人便利变成企业级子系统。把人类界面与智能体工具包当作两个独立产品，默认不必互相镜像：用户操作界面和斜杠命令；智能体使用工具或可发现的 CLI。若存在设置、持久状态或多个用户操作，偏好单一可快速浏览的管理界面；配置文件是存储，不是常规界面。共享底层实现时，分别给两类受众合适的词汇与结果。面向智能体的结果应说明发生了什么，并提供下一步自然需要的状态、证据、路径、句柄、恢复方式或确切续接。新增或修改面向智能体的工具前，先加载适用的工具设计 skill。
界面与文档：README 应说明结果、安装、首个动作和材料边界；设置与操作属于产品本身。若日常使用需要读手册或背命令族，应先重设计界面而非打磨文档。
模型成本与测试：在模型、提示、上下文和 harness 版本固定的情况下，测量使用和不使用扩展的等价首轮。检查 schema、描述、注入指令、启动消息和工具结果，移除模型已知事实、宿主可推断的选择及智能体很少使用的接口。先优化任务成功，再优化 token 数；紧凑但不清晰的界面不是改进。先在隔离环境中运行本地候选，再改实时设置；tmux 或 Herdr 中可见的兄弟窗格便于用户与主会话对比，可查阅 harness 帮助和 herdr --skill。对 Pi 可用一次性的 PI_CODING_AGENT_DIR 配合 pi -nc -ns -ne -e <candidate> 起步。让人操作并评判人类界面，智能体无法从代码、截图或自动检查中自证 UX；用自然请求和一处不应被使用的邻近请求，在新可见会话中单独测试智能体界面。每次有意义运行后停下供用户检查，保留测试窗格直到用户许可清理。隔离形态令用户满意后，再以完整设置启用，只检查相关集成风险（冲突、被替换的能力、启动开销、提示缓存、移除行为），让用户按正常流程判断扩展是改善还是只增加管理负担。移除仅因听起来有用而留存的命令、设置、模式、集成和文档。
适用场景与限制：适用于为编码智能体（如 Pi 等 harness）设计扩展、skill、工具或命令的决策与评审。局限：资料未提供具体安装命令、版本要求、平台支持、收费或效果数据，也未给出可直接复制的完整代码示例。