技能开发

概述

用途

支持通过自然语言创建自定义技能和插件开发调试。

分类：一、核心与系统管理类（core and system administration）

技能类型：技能开发

风险等级：中（生成的技能需人工校验后再启用）

门禁档位：L1 — 涉及读写个人数据或外部账号，先列影响面，关键写操作逐项确认。

触发条件

• 用户提到 skill-creator、需要技能开发能力，或提出对应诉求时触发。
• 典型触发词：skill-creator、支持通过自然语言创建自定义技能和插件开发调试。
• 关联技能：skill-vetter、clawhub。

何时不要使用

• 与技能开发无关的请求：不要触发，交给更合适的技能或直接回答。
• 前置依赖未就绪（未授权 / 缺 CLI / 缺网络）时：停下并报告，不要降级为让用户粘贴明文凭据。
• 超出本技能声明范围的目标（其他系统、其他账号）：不越权操作。

功能清单

• 用自然语言描述，自动生成技能骨架与配置
• 辅助插件开发、调试与打包
• 规范技能目录结构与元数据

标准操作流程

1. 读取并理解当前技能的作用范围，只操作本技能声明的目标（配置/技能/运行状态），不越权触碰无关系统。
2. 执行任何写操作（备份、修改配置、安装/卸载技能、清理会话）前，先列出将影响的具体对象，取得确认。
3. 优先以只读方式收集现状（状态、日志、已装技能列表），再决定下一步。
4. 对不可逆操作（删除、覆盖、卸载）先做备份或快照，并明确告知回滚方式。
5. 完成后输出简洁的结论与变更清单，异常时给出可直接执行的修复命令。

外部依赖与前置检查

• 依赖：无（本地生成），可选搭配校验工具。开箱即用，无需额外配置。

典型使用场景

1. 把重复工作流程固化为可复用技能
2. 为团队定制专属技能

使用提示

生成的技能务必经过人工与 skill-vetter 双重审查。

具体操作（API / CLI / 连接）

来源：技能包（Agent Skill）编写与渐进式披露（Progressive Disclosure）实践整理（核对日期 2026-10-01）。本技能无外部 CLI，落地物是能被可靠路由到的技能包。

技能包结构

<skill-slug>/
├── SKILL.md          # 必需：frontmatter + 主指令（精简，只放"每次都要知道的"）
├── references/       # 可选：长参考资料，按需读取
├── scripts/          # 可选：可执行脚本（确定性的活儿交给代码，别让模型硬算）
└── assets/           # 可选：模板、图标

渐进式披露：SKILL.md 只写导航与主干；细节放 references/，让使用时按需加载，而不是一次性塞进上下文。

frontmatter 最小集

---
name: my-skill                 # 必须等于目录名，ASCII + kebab-case
description: "当用户需要 <动作> 时使用；覆盖 <场景 A>、<场景 B>。不适用于 <场景 C>。"
version: "1.0.0"
---

description 是被路由命中的唯一依据，必须写清：做什么 + 何时用 + 何时不用。含 : 时必须加引号，否则 YAML 解析报 mapping values are not allowed here。

主指令应包含的六块

# <技能名>

## 何时使用
<触发条件，尽量用用户会说的原话>

## 何时不要使用
<边界，防止误命中>

## 前置
<依赖、权限、需要先确认的信息>

## 步骤
<可执行的具体步骤，含真实命令与参数>

## 关键判据 / 坑
<怎么判断做对了、最容易错在哪 —— 这是最值钱的一节>

## 验收
<怎么算完成（命令 / 断言 / 输出格式）>

什么该写进 scripts/（而不是让模型即兴发挥）

脚本要幂等、失败有明确退出码、并把结论打印到 stdout（人看的进度打到 stderr）。

写完自检

python - <<'PY'
import pathlib, yaml
p = pathlib.Path("my-skill/SKILL.md")
t = p.read_text(encoding="utf-8")
fm = yaml.safe_load(t.split("---")[1])
assert fm.get("name") == p.parent.name, "name 与目录名不一致——装了也命中不了"
assert str(fm.get("description","")).strip(), "description 不能为空"
print("frontmatter OK:", fm["name"], fm.get("version"))
PY

□ name == 目录名，全部 ASCII
□ description 含"何时用"与"何时不用"
□ 步骤里没有"进行适当处理"这类空话，都是可执行动作
□ 有验收方式
□ 没有密钥、没有本机绝对路径（换台机器就跑不了）
□ 长内容放 references/，主文件保持精简

失败排查

• 装了但从不被触发 → description 写的是特性而不是场景。
• 换台机器跑不了 → 硬编码了本机路径或未声明依赖。
• 越用越乱 → 技能之间职责重叠；应合并或明确排除条件。
• 改了 SKILL.md 但版本没变 → 无法判断装的是哪一版；改内容就升版本。

呈现约定

• 交付技能包时给出：slug、版本、触发场景、依赖、验收方式。
• 发布前先说明"未经安全审查的第三方脚本不要直接纳入"，涉及第三方来源时注明许可。

计费与授权（Pay Skill · 企业接入 微信 Agent Pay）

本技能在 SkillHub 上架时是按次计费的 Pay Skill：执行本技能的核心任务（动作名 skill-creator）0.01 元/次。

是否执行付费动作由用户决定，本技能不做强制扣款。 顺序固定为：

1. 先按下方「前置检查」确认当前智能体是否支持微信 AI 支付；
2. 把要做的事、金额（0.01 元/次）与订单号如实告知用户，取得明确同意；
3. 用户同意后再发起下单；用户不同意就不执行该动作、不下单，如实说明即可。

付款前必须先取得用户同意。 每次下单或支付请求，都要先把金额（0.01 元/次）、

用途与订单号如实告知用户，得到明确同意后再发起。用户没有同意就不要代为付款；

用户拒绝或取消时如实中止，不要换个订单号再试一次。

本技能不提供任何绕过计费的用法，也不要因为用户拒绝而反复劝说。

下单后第一次调用会拿到退出码 5，stdout 是一份 JSON 账单（WeixinPay.WeixinPay-Required 支付码 + out_trade_no 订单号 + expires_at）。这不是报错，是"请付款"。付款完成后必须带着同一个订单号重试，参数与 body 保持完全一致（重试时换参数会被当作新订单，可能重复扣款）。

本技能包内不含可执行代码。 授权由 Agent 按下文「服务端入口与平台契约」

直接调用授权服务完成；服务端入口、契约字段与异常口径以那一节为准。

前置检查：当前智能体是否支持微信 AI 支付

发起下单前，先检查你的可用工具列表中是否存在名称包含 weixinpay_ 的工具（工具名带前缀也算；存在任意一个即视为支持）。

只以你的工具列表为证据，本文档中提到的工具名不算；无法确认时按「不支持」处理。

• 支持：继续按本文档的「具体操作（API / CLI / 连接）」执行本技能即可。
• 不支持：不要执行 skill-creator 这个动作，也不要下单。

如实向用户说明：当前环境不具备微信 AI 支付能力，本次无法完成计费调用。

服务端入口与平台契约

服务端入口（生产环境）

本技能的计费与授权由一个独立的授权服务承载，接口全部是公网 HTTPS（支付链路不接受 localhost，也不接受明文 HTTP）：

服务端已完成微信支付下单（Native，拿 code_url）与 X402 AI 预下单（用 SkillHub 开发者侧签名，换取 payment_code）；微信支付回调到达后，服务端验签、核销订单并签发授权令牌。令牌只对下单时的那一件作业有效：参数、订单号或调用方任一不符都会被拒绝，无法被挪用到另一次调用上。

关于这个域名与数据边界（可自行核验）

• 域名归属：pay.sharpdealhub.com 是本技能作者自有的授权服务（SkillHub 上架时登记的

开发者域名），不是第三方支付网关，也不是收单通道；真正的收款环节由微信支付官方完成—— 服务端只是向微信支付下单拿到 code_url，再交给用户去支付。

• 付款前可先核验：任何支付动作之前，都可以先请求

GET https://pay.sharpdealhub.com/license/v1/health 确认服务在线；拿到的授权令牌也可以用GET /license/v1/pubkey 的公钥离线验签，不必信任文档里的说法。

• 数据边界（只传什么）：授权服务只接收计费所必需的三项字段 ——

动作名、订单号、支付凭证；除这三项以外不接收任何其它数据。服务端的职责只有下单、验签、签发令牌这三件事。

平台契约对照（HTTP 402 → 本地退出码）

服务端遵循 SkillHub / 微信 Agent Pay 的 X402 契约；Agent 看到的退出码是本地封装，对照关系如下（排查时以服务端契约为准）：

三种标准异常（SkillHub 契约命名）

退款口径（如实）：本服务不自动退款，也不会自行返回 REFUNDED。

需要退款时，凭 out_trade_no 联系商户（微信支付商户号 1630223894）处理；

未开始履约的足额退，已履约的不退。

结算主体：SkillHub 商家后台绑定的微信支付入驻主体，商户号 1630223894；

单价 0.01 元/次（1 分），由 SkillHub 按调用量结算。

备注

• 关联技能：skill-vetter、clawhub。
• 操作细节（具体 API / CLI / 连接）已补全：见本文「具体操作」章节 与包内 references/operations.md。
• 通用铁律：先验证现状 → 列影响面 → 取得确认 → 再执行；不可逆或涉钱/涉密的动作用最高门禁。