skill-author：写技能 / 审技能的路由器

平台技能开发规范（skill-author v1.1.0），面向写技能、审技能的开发者。使用说明见帮助文档。

先定类型，再只读对应的 reference；交叉关注点按需加载。每个 reference 开头写了「什么时候读」。

回答「有哪些 reference」之前先实际 ls references/（不能列目录就按名字直接读），别凭下表数数—— 下表是向导不是清单。当前共 20 份，见文末全清单。

两种任务：

• 写新技能 / 改技能 → 从「第一步」开始。
• 审查现有技能 → 先跑 python3 scripts/check_skill.py <skill_dir>，再读 references/review.md 出报告。

第一步：定技能类型

要做的事	skill_type	入口	读这份
跑代码、调 API、碰数据库	handler（Python 进程内）	handler.py 里 async def execute(input_data, runtime_context)	references/type-handler-python.md
跑现成脚本 / 别的语言 / 需要 argparse	handler（子进程）	脚本，读 SKILL_INPUT / SKILL_CONTEXT 环境变量	references/type-handler-subprocess.md
只转发一个 HTTP 请求	handler（HTTP）	*.toml	references/type-handler-http.md
不写代码，让子代理照文档操作	skill_md	无	references/type-skill-md.md
包一组第三方 HTTP API，让子代理按端点清单选调	skill_md（API 型）	openapi.yaml 或 endpoints_whitelist.yaml	references/type-skill-md.md §API 型
纯资料，只供检索不进工具清单	knowledge	无	references/type-knowledge.md

要做控制面板 → 读 references/ui-panel.md。面板不是独立 skill_type：本地面板必须挂在进程内 handler 上， 页面动作走 /skills/invoke 网关，网关只按 schema 的 action.enum 挡未知动作，不再校验 x-actions—— 写/删类动作的鉴权要 handler 自己做。只想整嵌外部网页用外部面板（ui: 写 URL）。

判断规则（按顺序停在第一条命中）：

1. 要读写库 → 必须是 Python 进程内 async。直连从 db_factory 自开短会话、不用 ctx["db"]。
2. 要调别的技能（call_skill）→ 同上。
3. 已有现成 CLI / Node / Shell 脚本 → 子进程型：无 db、60 秒超时、日志只能走 stderr。
4. 逻辑能用自然语言写清、不需要确定性 → skill_md。
5. 其余 → 进程内 Python。

第二步：按需加载交叉关注点

写到哪一步，再读哪一份。不要一上来全读。

碰到	读
设计 schema.json、子命令、文件参数、action 分发、下拉选项	references/input-schema.md
技能要带面板，或整嵌外部网页	references/ui-panel.md
需要知道「谁在调、从哪来、有什么权限」	references/runtime-context.md
需要 API key / token 等配置	references/config-secrets.md
写返回值、报错、表格直显、产出文件	references/output-envelope.md
自己读写库（不走 datatable）	references/code-facts.md §3.7
建表 / 查询 / 写入 / 删除数据表	references/datatable.md
技能内调别的技能、发通知、发消息	references/call-skill.md
技能内要调用大模型	references/llm-call.md
串成技能链、或写会被放进链里的技能	references/chain.md
耗时很长的生成任务	references/output-envelope.md §7
写完准备交付	先跑 scripts/check_skill.py，再 references/checklist.md 逐条打勾
审查别人写的技能	references/review.md
某条规则在源码哪里（文件、函数、默认值）	references/code-facts.md
某条规则为什么这样定（历次核对与定案记录）	references/pending-issues.md
核对完整规范	references/spec-revised.md——唯一现行规范，已按源码订正，与代码一致；spec-full.md 只是最初原文存档，不作依据

第三步：从模板起步

• templates/SKILL.md.tmpl — frontmatter 字段全，注释说明每项
• templates/handler_async.py — 进程内骨架：action 归一、_db() 现开现还、信封返回
• templates/handler_cli.py — 子进程 CLI 骨架
• templates/schema.json — 合法 JSON Schema 示例
• templates/panel/ — 本地面板骨架

不读 reference 也必须记住的七条

1. 入口一律写成 async def execute(input_data, runtime_context)，参数名照抄、不给默认值。 create_skill / edit_skill 的安装预检对「找不到 execute / 参数名不是 input_data、runtime_context / 不是 async」 直接拒装；executor 认的 run/handler/main/handle 只为兼容老技能。模块里没有入口函数时平台静默降级为文档型。
2. 工号读 ctx["actor_emp_no"]。身份一律取 ctx，input_data 里的同名字段视为伪造。
3. 参数名/常量名避开 key token secret password credential auth 子串，平台按子串当凭证摘除。
4. 失败必须给 error；可自纠的标 error_type: recoverable（或给 need_param）——这类不计失败预算； non_retriable 只给部署级问题，否则技能被本轮拉黑。
5. 自己读写库：收进单一 _db()，每次从 ctx["db_factory"] 现开短会话、用完即还，不用 ctx["db"]； 写必须 commit。结构化操作走 call_skill("datatable", …)；org_id 为空直接拒绝，不补伪 org。
6. SKILL.md 正文 < 8000 字符，细节放 references/，正文写明何时读。
7. 工作区用 ctx["workspace_dir"]：executor.execute 统一注入（= $AGENT_WORKSPACE_DIR/<role_id>/<session_id 或 shared>）。 写 ctx.get("workspace_dir") 并按同式兜底（code-facts §4 _workspace(ctx)）；子进程读 SKILL_CONTEXT 同名键或 SKILL_WORKSPACE。

frontmatter 写法： 平台从顶层读 category / cost-tier / async / env 等（loader 不读 metadata 下的同名键）。 只有 metadata.openclaw.*（primaryEnv / requires / skillClass / requiresContainer…）在 metadata 下读。 要发主流市场才考虑把平台字段挪进 metadata（需改 loader，见 spec §2.2.1）。

工作方式

• 先问清：触发场景、输入/输出形状、要不要碰数据表、要不要调别的技能、要不要带面板。对话里已有的不再问。
• 写完对照 references/checklist.md 逐条核，把未满足的列给用户，不要说「已按规范」。
• 交付物是完整目录（SKILL.md + handler.py + schema.json + references/），不是代码片段。 安装途径决定能带哪些文件：zip 上传 / 控制台安装带整个目录；对话里的 create_skill 只写 SKILL.md、handler.py、skill.toml——schema.json、references/、面板文件要随后用 edit_skill 的 full_files 补上。
• 改现有技能时保留原 name（name 须 ^[a-z0-9][a-z0-9_-]*$ 且与目录名一致）。
• 没有 shell 的环境下跳过脚本，直接按 references/checklist.md 人工核。
• 文档型的 SKILL.md 写给执行它的子代理看，用祈使句；handler 型写给选工具的模型看，description 说清「什么时候该调我」。

附：references 全清单（共 20 份）

• 类型判定：type-handler-python.md、type-handler-subprocess.md、type-handler-http.md、type-skill-md.md、type-knowledge.md
• 交叉关注点：input-schema.md、ui-panel.md、runtime-context.md、config-secrets.md、output-envelope.md、datatable.md、call-skill.md、llm-call.md、chain.md
• 交付 / 审查：checklist.md、review.md
• 规范与出处：spec-revised.md（现行规范）、code-facts.md（源码出处）、pending-issues.md（定案记录）、spec-full.md（原文存档）

直连库的权威规则在 code-facts.md §3.7 与 spec-revised.md §7A。不存在 数据库.md 这份文件。