skill-template/SKILL.md

name, description, version, author, metadata, allowed-tools

name	description	version	author	metadata	allowed-tools
技能开发模板（通用业务版）	OpenClaw 通用业务技能开发模板，供复制后定制新业务 skill。定制步骤见 development/DEVELOPMENT.md。	1.0.45	深圳匠厂科技有限公司	openclaw slug platform_kit_min_version emoji category developer_ids your-skill-slug 1.2.0 📦 通用 10032 12428	bash

技能开发模板（skill-template）

这是一个用于复制的新技能模板，不是业务 skill 本身。复制后请替换占位内容，实现你的真实业务逻辑。

Agent / 宿主编排（复制为业务技能后必改）

架构铁律（先读）

• 单业务内核、多入口：数据管理 / 定时任务 / Agent / 技能详情 / 直接 CLI 必须复用同一 domain service；禁止按入口复制业务逻辑，禁止按 source 分叉业务行为。
• placements：只决定 Action 出现在哪里（toolbar / cron / agent / skill-detail）。
• bind.tables：只决定数据管理出现在哪些表；含 toolbar 时必须显式非空绑定。
• executionProfile：只决定执行方式——sync 当场返回结果，async 进任务中心。与 placements / 入口无关；每个 Action 必须显式写 sync 或 async。
• 同步数据写技能本地库、不生成导出文件；导出当前表由宿主数据管理负责；特殊业务报告才另做 export-*。
• 准备 vs 执行（适用则拆）：若技能存在「先写入/准备本地数据」与「再对外产生副作用」两段，Agent 必须能分开触发；禁止默认绑成不可拆的一步。一键无准备态的技能可跳过本条。

如何触发（能力类型）

你要做什么	Agent 怎么做	进任务中心？
短查询 / 只读 / 秒级（health / version / stats / list / get / logs 等）	OpenClaw bash/exec + 共享 Python 跑 CLI（见下方「共享 Python」）	否（CLI 当场结束）
已在 actions.json 声明且 executionProfile: "sync" 的能力	可用 run_skill_action，或同等效果的短 CLI（同一内核）	否
长耗时 / RPA / 浏览器 / 需要进度或取消；或 executionProfile: "async"	必须 run_skill_action（先 list_skill_actions / get_skill_action）	是（仅因为该 Action 是 async）
用户只问用法 / 能做什么	读根目录 README.md；不要为答用法去列目录或默认打开 references/	—

用户意图路由表（业务技能复制后必改）

复制为业务技能后，必须用本技能真实意图改写下表（保留三列结构）。格子写清：短 CLI 子命令，或 run_skill_action → 具体 action id（及主要 input）。勿留模板占位语上线。

用户意图（本技能自填）	Agent 怎么做	进任务中心？
（例）查询 / 统计 / 列表	短 CLI：<your-read-commands>	否
（例）写入 / 导入 / 改本地状态	短 CLI：<your-prep-commands>	否
（例）长副作用 / RPA / 需进度	run_skill_action → <your-async-action-id>，input.…	是（因该 Action 为 async）

有长任务 / RPA 时：上表至少一行指向真实的 async action id，且该 id 须出现在 assets/actions.json；细节分流见 references/CLI.md。

硬规则：

1. 禁止对长任务使用 exec/bash 跑 …/scripts/main.py run（或等价业务命令）再 process poll 干等。
2. 禁止用 uv run python … 跑技能脚本（会建临时环境，缺 jiangchang_skill_core）。
3. 禁止 Agent 自行 pip install。
4. Action 可选：无数据管理 / 定时 / Agent 结构化调用需求时可不提供 actions.json；有长任务 / RPA 时必须提供至少一条 executionProfile: "async" 且 placements 含 agent 的 Action。
5. 一个业务能力一个 Action，用多个 placements 挂入口；底层仍是同一 scripts/main.py CLI。
6. 是否进任务中心只看该 Action 的 executionProfile，与数据管理 / 定时 / Agent 入口无关。

Agent 执行契约细节：references/CLI.md、references/ACTIONS.md、references/SCHEMA.md（不要把 development/ 当 Agent 主读路径）。

共享 Python（必读）

宿主共享 runtime 在 {JIANGCHANG_DATA_ROOT}/python-runtime/.venv，并已前置到 PATH（同时设 VIRTUAL_ENV）。短 CLI 一条命令直接跑：

python {baseDir}/scripts/main.py health
python {baseDir}/scripts/main.py version
python {baseDir}/scripts/main.py config-path
python {baseDir}/scripts/main.py init-db

• 公共库来自共享 venv 的 jiangchang-platform-kit>=1.2.0（包名路径 jiangchang_skill_core）；不要 vendor scripts/jiangchang_skill_core/。
• 根目录 requirements.txt 只声明技能特有依赖；不要写 jiangchang-platform-kit / playwright。
• metadata.openclaw.platform_kit_min_version 是宿主兼容声明，不是 pip 依赖。
• health 用 collect_runtime_diagnostics 做只读诊断。

配置：仓库 .env.example 为模板；用户 .env 在 {JIANGCHANG_DATA_ROOT}/{JIANGCHANG_USER_ID}/{slug}/.env。优先级：进程环境变量 > 用户 .env > .env.example。

面向用户问答（LLM 规则）

• 本文（SKILL.md）是 LLM / OpenClaw 平台读取的技能入口，不是用户市场说明。
• 根目录 README.md 是面向普通用户的说明。

当用户询问以下问题时，必须优先读取根目录 README.md，并用用户能理解的业务语言回答：

• 这个技能是做什么的
• 这个技能怎么用
• 适合什么场景
• 使用前要准备什么
• 执行后会得到什么
• 能不能帮我完成某个业务任务

回答「怎么用 / 能做什么」时的要求：

1. 以 README.md 的「能帮你做什么」「你可以这样告诉 Agent」「常见问题」等章节为主组织回答。
2. 禁止在回答中粘贴 python …/scripts/main.py … 或其它命令行（除非用户明确索要命令，或自称技术人员/开发者）。
3. 禁止为答用法而去 dir / ls / 列技能目录，或默认打开 references/、development/；仅当用户明确问命令、参数、集成或排错时再读 references/。
4. 不要向普通用户暴露 Playwright、DOM、Python、RPA、库表名、error_code 等实现细节，除非用户明确询问技术实现。

文档读取边界：

• 不要把 SKILL.md、references/、development/ 中的技术细节直接作为用户回答。
• 只有当用户明确询问命令、参数、输出结构、开发、调试、集成或排错时，才读取 references/；development/ 主要给开发者 / 编码助手，对话 Agent 不必默认打开。
• 若 README.md 与 SKILL.md / references 表述冲突：对用户展示与市场说明以 README.md 为准；对执行契约以 SKILL.md / references 为准。
• 用户未问技术实现时，不要讨论 slug 命名规则；开发者问命名或 slug 时，读取 development/NAMING.md。

文档分工

文档	读者	用途
根目录 README.md	普通用户	技能市场详情页说明（metadata.readme_md 主来源）
SKILL.md（本文）	LLM / OpenClaw 平台	技能入口、触发与运行契约摘要
references/	Agent 编排 / 调用	CLI、Action、schema 契约（Agent 主读）
development/	开发者 / AI 编程代理	需求、开发教程、测试、深度技术规范

目录约定

复制后建议保留：

• assets/、development/、evals/、references/、scripts/、tests/
• CLI 入口固定为 scripts/main.py
• 业务逻辑按 cli / db / service / util 分层

定制入口

1. 从本模板创建新业务技能时，不得保留模板 .git；优先使用 tools/scaffold_skill.ps1（见 tools/README.md）。
2. 业务技能仓库中不得存在 .openclaw-skill-template（仅 template 源仓库保留）。
3. 复制目录为你的新 skill 仓库，全局替换 your-skill-slug 等占位词。
4. 按 development/DEVELOPMENT.md 完成开发与文档定制。
5. 用户市场说明写入根 README.md；Agent 调用契约见 references/CLI.md、references/SCHEMA.md、references/ACTIONS.md。
6. 同步修改 scripts/util/constants.py 中的 SKILL_SLUG / SKILL_VERSION。
7. 本地 SQLite 的中文表名/字段名、标准时间字段与字段顺序规范见 references/SCHEMA.md。

技能命名与 slug

• 标准格式：{verb}-{noun-phrase}-{platform}（详见 development/NAMING.md）。
• slug / repo / 目录 / SKILL_SLUG / DB 文件名：英文 kebab-case；name、description、根 README.md：中文。
• 复制为新业务技能前必须阅读 development/NAMING.md。
• name（frontmatter）：用户可见的中文业务名称；description 是说明，不是名称。
• metadata.openclaw.slug：英文 kebab-case 机器标识；目录名、默认 {slug}.db 使用 slug，不使用中文。
• 复制后全局替换 your-skill-slug 与 your_skill_slug（脚手架会自动处理）；正式技能不得保留英文占位 name 或 slug。

平台元数据

• metadata.openclaw.developer_ids：技能发布后的默认开发者可见用户 ID 列表。
• 当 access_scope = 0（不公开）时，平台会把 developer_ids 中的用户自动补写到 skill_user_access。
• developer_ids 建议写为正整数数组；第一个 ID 会作为主开发者同步到 skills.developer_id。