zk-data-agent/skills/product-data/knowledge/portable_skill_contract.md

Portable Skill Contract

本约定用于让 skill 能在不同 Agent 平台之间迁移。

核心原则

能力归 skill，运行适配归平台。

• 脚本必须能独立执行。
• 平台工具注册只做薄封装，不承载业务逻辑。
• 没有工具注册能力的 Agent，可以阅读 SKILL.md 并直接执行脚本。
• 脚本输入输出都使用 JSON，避免自然语言解析。

脚本输入

脚本必须支持：

python scripts/<name>.py --input input.json

也必须支持从 stdin 读取 JSON：

cat input.json | python scripts/<name>.py

脚本输出

stdout 只输出一个 JSON 对象。

成功：

{
  "ok": true,
  "result": {}
}

失败：

{
  "ok": false,
  "error": "错误原因"
}

输出路径

默认写入当前会话 output/，或调用方明确传入的输出目录。

脚本不得写项目源码目录、随机临时目录或用户未确认的外部路径。

平台注册

tools.yaml 是平台适配层：

• name 是平台注册后的工具名。
• script 指向真正执行能力。
• input_schema / output_schema 供平台生成工具 schema。
• fallback 告诉无注册环境如何手动调用。

如果平台不支持 tools.yaml，不影响脚本独立使用。