API Asset Skill Creator

使用 Skill Market 的内部接口，把用户选中的 API 资产端点生成一个新的 Skill 目录。

前置条件

所有查询都必须从环境变量 AGENT_ID 读取 agentId，禁止向用户索要 agentId
默认使用 SKILL_MARKET_BASE_URL 访问 Skill Market；未设置时回退到 https://skill.netease.im
所有脚本都通过 Node.js 执行；若 node 不可用，直接告知当前环境不满足前置条件
生成目录默认写到当前工作目录下的 ./{skill-name}；若目录已存在，必须先向用户确认是否覆盖

内置脚本

scripts/list-visible-assets.mjs 用途：查询当前 agent 可见资产，并在本地按关键词 / 分类过滤
scripts/list-asset-endpoints.mjs 用途：查询某个资产最高已发布版本的端点列表
scripts/build-skill-references.mjs 用途：根据用户选择裁剪 OpenAPI，并生成 references/asset-metadata.yaml、references/request-templates.json 与各资产的 references/*.yaml
scripts/build-skill-md.mjs 用途：根据生成好的 YAML 引用文件输出最终 SKILL.md
scripts/preview-skill-description.mjs 用途：在正式生成 SKILL.md 前，根据已选资产和接口产出描述草案，供用户确认或提出优化意见
scripts/package-skill.mjs 用途：把生成好的 Skill 目录打包成可直接发送/交付的 zip 文件
scripts/send-popo-file.mjs 用途：在当前环境已配置 POPO 渠道时，把 zip 文件作为附件发回给用户

执行步骤

Step 0：检查环境

先执行：

node -v
printf 'AGENT_ID=%s\n' "${AGENT_ID:-}"
printf 'SKILL_MARKET_BASE_URL=%s\n' "${SKILL_MARKET_BASE_URL:-http://127.0.0.1:3001}"

若 AGENT_ID 缺失或不是正整数，必须停止并明确报错。

Step 1：用户查询某功能 API 资产

让用户描述要封装的功能，如“审批”“天气”“员工查询”
用该关键词执行：

node scripts/list-visible-assets.mjs --keyword "<关键词>"

只向用户展示候选资产摘要：
- 资产名称
- id
- slug
- categoryName
- description
- endpointCount
若没有结果，直接告知“当前 agent 无匹配资产”，不要继续后续步骤

Step 2：根据用户选中的 API 资产输出 API 接口

对用户选中的每个 assetId 分别执行：

node scripts/list-asset-endpoints.mjs --asset-id "<assetId>"

向用户展示每个资产下的端点列表，至少包含：

端点序号
endpointId
method
path
alias
description

Step 3：用户选择 API 接口

让用户明确选择规则：

某个资产下全部端点
某个资产下部分端点
多个资产混合选择

内部保存时，端点的最终筛选主键必须使用：

assetId + method + path

不要只依赖 endpointId，因为 OpenAPI 裁剪阶段只能稳定匹配 method + path。

Step 4：Skill 命名

要求用户明确输入 Skill 名称
名称只允许：小写字母、数字、连字符
目录默认输出到 ./{skill-name}
若目录已存在，先询问用户是否覆盖；仅在用户明确同意后使用 --overwrite

Step 5：生成引用文件与请求模板

先把用户最终确认的选择结果写入一个临时 JSON 文件，例如 /tmp/api-asset-skill-selection.json，结构如下：

{
  "skillName": "oa-approval-assistant",
  "selections": [
    {
      "assetId": "asset-1",
      "endpoints": [
        {
          "endpointId": "endpoint-1",
          "method": "GET",
          "path": "/approval/{id}",
          "alias": "getApprovalDetail",
          "description": "查询审批详情"
        }
      ]
    }
  ]
}

然后依次执行：

node scripts/build-skill-references.mjs \
  --input /tmp/api-asset-skill-selection.json \
  --output-dir "./<skill-name>"

脚本执行成功后，生成结果中必须至少包含：

references/asset-metadata.yaml
references/request-templates.json
每个资产对应的 references/*.yaml

Step 6：描述预览并强制确认

在正式生成 SKILL.md 之前，必须先执行：

node scripts/preview-skill-description.mjs \
  --skill-name "<skill-name>" \
  --output-dir "./<skill-name>"

执行后必须做以下动作，这一步不能跳过：

把脚本输出的 description 草案整理后展示给用户
明确告诉用户：这是根据已选 API 资产和接口生成的 Skill 描述草案
明确询问用户是否需要优化、改写、补充或删减
只有在用户明确回复“可以”“确认”“不用改”等同义确认后，才能继续下一步
如果用户要求优化，必须先根据用户意见调整 description，再次给用户确认；确认前禁止继续生成 SKILL.md

Step 7：正式生成 Skill

当且仅当用户已明确确认 description 后，才能执行：

node scripts/build-skill-md.mjs \
  --skill-name "<skill-name>" \
  --output-dir "./<skill-name>"

node scripts/package-skill.mjs \
  --skill-name "<skill-name>" \
  --input-dir "./<skill-name>" \
  --output "./<skill-name>.zip"

如果用户已确认覆盖，则 build-skill-references.mjs、build-skill-md.mjs、package-skill.mjs 都追加 --overwrite。

Step 8：按渠道回传生成结果

默认必须返回 zip 文件路径，不能只返回目录路径
若当前用户明确处于 POPO 渠道，且当前会话上下文中可以确定该用户的 POPO 接收标识（优先邮箱），则继续执行：

node scripts/send-popo-file.mjs \
  --file "./<skill-name>.zip" \
  --receiver "<当前用户邮箱>"

若无法确定当前用户的 POPO 接收标识，则不要猜测；改为向用户确认邮箱，或仅返回 zip 文件路径
若当前用户不是 POPO 渠道，则只返回本地 zip 路径和生成摘要，不执行发送

输出要求

生成完成后，只向用户汇总以下结果：

生成目录
zip 文件路径
SKILL.md 路径
references/asset-metadata.yaml 路径
references/request-templates.json 路径
各个 references/*.yaml 路径
本次纳入的资产数量与端点数量
若已通过 POPO 发送，还要明确说明发送结果

注意事项

AGENT_ID 必须从环境变量读取，禁止询问用户
listVisible 只返回资产信息，不返回端点；端点必须走 list-asset-endpoints.mjs
用户最终可能只选某个资产的部分端点，生成时必须通过 build-skill-references.mjs 裁剪 OpenAPI
生成的 description 必须优先使用各 API 资产自身的描述信息；若某资产只选了部分端点，需尽量从描述中移除未纳入端点对应的说明，避免把未选接口写进生成结果
当资产和接口已经确定后，在真正生成 SKILL.md 前，必须把整理后的 description 草案输出给用户确认，并强制询问“是否需要优化”；用户未明确确认前，禁止继续生成
生成出来的 Skill 要尽量贴近 xiaosusearch 风格：概述 / 最高优先级规则 / 阶段一 / 阶段二 / 阶段三 / 输出格式 / 注意事项
生成出来的引用文件要尽量贴近 xiaosusearch 风格：统一 references/asset-metadata.yaml、references/request-templates.json + 每个资产一个 references/<asset>.yaml
不能手写或臆造接口定义；必须以 exportOpenApi 的真实返回为基础裁剪并转成 YAML
生成出来的 Skill 运行时必须优先读取 references/request-templates.json 作为 clawhive_api_tool 入参模板，再补用户参数，不能让模型从零手拼完整请求头
若任一资产在导出 OpenAPI 时失败，整个 Skill 生成流程应失败，避免产出半成品

api-asset-skill-creator