# SkillX 编写约定 本页约定本插件能力条目的命名、职责、输入输出、执行程序和版本。字段及 SDK 定义见[DSH 执行契约](contract.md)。 ## 能力命名 - 名称使用 kebab-case，表达稳定业务能力，例如 `commit-local-changes`。 - `description` 使用简体中文，写清适用目标和必要前提，供模型发现能力。 - 同名能力通过优化发布新版本。同名 SkillX 在能力发现时优先于普通 Skill。 ## 能力边界 单个 SkillX 负责一个具有独立复用价值的操作。变化的路径、端口、分支、服务名等作为输入，职责和结果契约保持稳定。 Workflow 通过 `capabilities.run` 组合能力和必要判断，并声明精确的依赖版本。子工作流按独立职责拆分。 提取依据是已记录的目标、工具操作、结果和失败边界。稳定性、证据完整度和可验证性决定哪些职责适合发布。 ## 输入输出 - 输入使用对象根 Schema，必填字段表达执行所需的变量。 - 输入属性的 `title` 和 `description` 使用简体中文，供参数表单展示。 - 输出使用 DSH JSON Schema 子集，返回业务结果和必要证据摘要。 - 对外部状态的判断记录观察来源、时间范围和可信条件。 - Schema 支持范围与大小限制见[执行契约](contract.md#执行契约)。 ## 执行程序 `execution.program` 可以是 JavaScript async function body，或完整 Python JSON stdin/stdout 程序。按实际依赖选择一种语言，不复制业务实现。JS 通过 `processes.run` 的参数数组执行外部工具，使用 `resources.run` 直接执行内部脚本，避免 Bash 包装。执行阶段注释使用简体中文。 必要的辅助脚本随版本存入 `scripts/` 或 `assets/`，执行程序用 `resources.path` 内部定位，不要求调用方提供脚本路径。使用同一份实现，不能兼容的平台明确注明。未知环境变量、配置或工具位置须询问用户，不猜测或广泛搜索。 确定性操作由程序串联；失败时才由宿主启动内部恢复子 Agent，读取该 SkillX 自己的 docs 指引。程序检查工具状态、结果完整性和业务前提，返回符合输出 Schema 的 JSON。 `content` 说明能力目的和使用条件，`validationNotes` 记录证据引用、已检查行为和观察范围。内部步骤由执行程序承担，调用方通过输入输出契约使用能力。 ## 权限与副作用 对话内调用继承调用方当前会话、root call 和执行 token。工作台直接执行使用宿主进程权限，详见[执行入口与权限](../operation.md#执行入口与权限)。 文件、Git、网络、浏览器等操作通过 DSH 工具执行，遵循宿主策略。能力说明写清副作用和执行前提；权限、鉴权、审批或凭据问题作为外部阻塞返回。 ## 依赖与版本 - `dependencies` 声明被 `capabilities.run` 调用的精确名称和版本。 - 执行时加载依赖闭包，并校验版本一致性。 - 发布生成不可变修订，历史执行绑定对应版本。 - 依赖实现由插件运行时按版本加载，调用方通过当前能力的公开契约使用。 ## 提取和优化 提取使用冻结的会话记录，按职责选择相关完整证据，记录来源摘要和实际审查范围。多来源任务分别获取各来源的相关记录。 生成 Agent 使用证据读取、契约读取和候选提交工具。宿主仅检查静态结构并发布版本，不生成用例或执行业务验证。优化基于选中能力的当前版本和观察证据修订；可继续复用的实现保留原版本。 草稿续跑、请求上下文与局部修复见[提取草稿与预算](../operation.md#提取草稿与预算)。 ## 文档口径 项目说明使用“启用 skillx”表示模型可以发现并调用插件能力。实现说明使用执行程序、能力依赖和编排流程等具体名称。 测试 JSON 保留实验字段和原始数据，面向读者的说明交代实验条件、统计口径和证据位置。 ## 目录与说明 当前版本放在 `skillx//` 或 `workflow//`；平级 `revisions//` 保存不可变快照。每个目录保留 `SKILL.md` 简述用途与使用条件、`manifest.json` 记录机器契约、`entry.js` 或 `entry.py` 保存入口，`scripts/`、`assets/`、`docs/` 保存内部依赖与错误指引。JS 入口仍是宿主执行的函数体，不能直接当作独立 Node 文件运行。目录用于阅读，修改需通过发布生成新修订，执行始终绑定不可变版本。