Herdr Plugin Builder 是面向 Herdr 终端的插件开发技能，用于构建、校验与发布 Herdr 插件。
【用途与定位】 一个 Herdr 插件是一个目录，其中包含 herdr-plugin.toml 清单，以及 Herdr 可通过 argv 直接启动的可执行命令（Bash、Node、Python、Lua、Rust 二进制等，只要用户机器上可用）。Herdr 拥有安装、清单校验、键绑定、窗格、事件与套接字；插件拥有自己的语言、依赖、文件与持久状态。资料说明：没有插件 SDK，也没有受限命令集，整个 herdr CLI 就是插件 API。
技能同时强调区分三类扩展面：插件（herdr plugin ...，可共享的工作流包）、集成（herdr integration install <agent>，面向已知编码 agent 的状态上报，属另一功能）以及 agent/窗格控制（herdr agent|pane|workspace ...，插件回调的运行时面）。
【主要能力与流程】
- 先确定版本与权威来源：运行 herdr status 记录客户端与服务端版本；以已安装二进制为命令语法与清单校验的权威（资料中的契约基于 Herdr 0.9.5、协议 22）。herdr plugin 在 0.9.5 上存在，但顶层 herdr --help 未列出，可用 herdr plugin 查看该组；不要裸跑 herdr，以免启动或附着 TUI。
- 编写清单：从 assets/plugin-template.toml 起步，设置 id、name、version 与 min_herdr_version（均为必填，后者为 semver 且不得超过已安装版本）。
- 离线预检：运行 python3 <skill-dir>/scripts/check_plugin.py <plugin-dir>，在接触真实服务器前排查 id 字符集、平台、命令、事件名、重复 id、弹窗尺寸等问题。
- 本地链接：herdr plugin link <dir> 注册插件且不执行 [[build]] 命令；注册对用户全局可见，完成后用 herdr plugin unlink <id> 解除。
- 验证真实行为：herdr plugin action list --plugin <id>、herdr plugin action invoke <id>.<action-id>，再用 herdr plugin log list --plugin <id> 查看 stdout/stderr、退出码与状态。资料明确：invoke 成功只代表已受理，不等于执行成功，需读日志再下结论。
- 运行时环境：命令以插件目录为工作目录执行，并接收 HERDR_BIN_PATH、HERDR_PLUGIN_* 与上下文变量；回调 Herdr 应通过 HERDR_BIN_PATH，而非硬编码套接字路径或裸 herdr。
- 发布：使用带 herdr-plugin 主题的 GitHub 仓库，清单位于根目录或默认分支的子目录；需要可复现时提示用户固定 --ref。
【重要限制】
- command 值是 argv 数组，Herdr 不经过 shell，除非命令自身启动 shell，否则无展开、管道或重定向。
- 插件代码以用户身份运行且拥有完整 CLI 能力；安装第三方插件前应审阅，[[startup]] 命令会在服务器启动时自动运行并出现在安装预览中。
- 通过 GitHub 安装的插件根目录是受管理的检出，切勿在其中存放凭据或持久状态，应使用 HERDR_PLUGIN_CONFIG_DIR 与 HERDR_PLUGIN_STATE_DIR。
- 插件必须在命令或窗格退出前停止分离的后台进程。
- 不可承诺插件自带键绑定、运行时动作注册、Herdr 管理存储 API 或原生非终端插件 UI，这些在插件 v1 中均不存在；键绑定通过用户 config.toml 绑定到插件动作。
- 不得为让 link 成功而降低 min_herdr_version，版本过高会返回 plugin_requires_newer_herdr 错误。
【适用场景】 适合需要为 Herdr 终端编写或修复插件清单、接入运行时回调、声明窗格/弹窗/链接处理器、以及安装、更新、卸载或发布插件的开发者。
【交付物】 插件目录；通过离线预检与真实 link 的清单；带日志证据的动作、事件或窗格行为验证；安装或发布说明；以及关于未测试项或版本相关事项的明确说明。若某行为无法针对已安装二进制验证，应如实说明而非依据文档泛化。