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.85	深圳匠厂科技有限公司	openclaw slug platform_kit_min_version emoji category developer_ids your-skill-slug 1.2.11 📦 通用 10032 12428	bash

技能开发模板（skill-template）

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

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

AI + RPA 定位

• Agent 是入口与编排者：理解用户意图、补齐参数、判断风险、选择 Action，并用业务语言解释结果。
• RPA 是确定性执行器：只按已验证步骤操作授权范围内的浏览器、桌面软件或手机；不得破解、逆向、调用未授权私有协议或绕过验证码、安全验证和平台限制。
• 遇到验证码、人脸、U盾、频控、账号风险或权限不足时，转人工或安全停止，禁止自动硬闯、换号或无限重试。
• 开发者与 AI 编程工具先读 development/AI_RPA.md；三端界面代码必须先读 development/RPA_ELEMENT_LOCATING.md 并完成真实拾取与 element map，再按浏览器/桌面/手机选读 RPA_BROWSER.md / RPA_DESKTOP.md / RPA_MOBILE.md；浏览器账号、Profile、多账号和租约另读 development/ACCOUNT_MANAGER.md。

架构铁律（先读）

• 宿主产品入口平级：对话任务 / 数据管理 / 定时任务是同一技能能力的不同触发场景，同等重要；挂哪些由本技能 UX 定义（入口定位表），详见 development/PRODUCT_SURFACES.md。以后宿主若增加新入口，仍是「新触发场景 + 同一内核」。
• 单业务内核、多入口：数据管理 / 定时任务 / Agent / 技能详情 / 直接 CLI 必须复用同一 domain service；禁止按入口复制业务逻辑，禁止按 source 分叉业务行为。
• 数据管理：既是 UI 执行面（点按钮走与对话相同的闭环），也是数据与过程可见；不是「只读库」。
• placements：只决定 Action 出现在哪里（toolbar / row / batch / cron / agent / skill-detail）。其中 row 表示行级入口（宿主可呈现为操作列、行右键、行内「⋯」等；技能配什么就显示什么，无独立菜单 DSL）。数据管理技能按钮顺序见 actions 数组相对顺序（详见 references/ACTIONS.md），无独立 sortOrder。
• bind.tables：只决定数据管理出现在哪些表；含 toolbar 时必须显式非空绑定。
• executionProfile：只决定执行方式——sync 当场返回结果，async 进任务中心。与 placements / 入口无关。心智上多数为 sync，仅长任务 / RPA 标 async；宿主省略该字段时按 sync。每个 Action 仍必须显式写 sync 或 async。
• policy（可选）：需要按用户/角色控制数据管理按钮或行列时，在 actions.json 顶层启用 Data Policy，由技能 policy CLI 输出 Snapshot；未启用 = 与今日一致（L0）。详见 references/POLICY.md。用户/角色数据源（飞书/库/API）属技能内部，宿主不托管。
• cellPresentation（可选）：需要数据管理「某格特殊标色/强调」时启用；技能按当前数据写入呈现（语义 tone），宿主映射主题样式；未启用 = P0 无标色。用途不限（超时、预警、驳回等）。详见 references/CELL_PRESENTATION.md。
• 同步数据写技能本地库、不生成导出文件；导出当前表由宿主数据管理负责；文件型特殊报告才另做 export-*（落 output/）；HTML 整页报告写 html/ 并用固定 Action id render-html（见 references/ACTIONS.md）。
• 准备 vs 执行（适用则拆）：若技能存在「先写入/准备本地数据」与「再对外产生副作用」两段，Agent 必须能分开触发；禁止默认绑成不可拆的一步。一键无准备态的技能可跳过本条。

如何触发（能力类型）

你要做什么	Agent 怎么做	进任务中心？
短查询 / 只读 / 秒级（health / version / stats / list / get 等）	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；逐步操作再读 TUTORIAL.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. 入口按定位表挂载：复制业务技能后须在 development/REQUIREMENTS.md 填写入口定位表（见 development/PRODUCT_SURFACES.md）。定位需要数据管理 / 定时 / Agent 结构化调用时，必须提供 actions.json 并声明对应 placements；定位确认无需任何宿主结构化入口时可不提供。有长任务 / 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、按需 references/POLICY.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.11（包名路径 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 平台读取的技能入口，不是用户市场说明。
• 根目录市场材料面向普通用户（见下方「文档分工」），不是 Agent 调用契约。

当用户询问以下问题时，必须优先读取根目录 README.md（能力说明）与 TUTORIAL.md（逐步用法），并用用户能理解的业务语言回答：

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

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

1. 「能做什么 / 场景 / FAQ」以 README.md 为主；「第一次怎么用完」以 TUTORIAL.md 为主。
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 不必默认打开。
• 若市场材料与 SKILL.md / references 表述冲突：对用户展示以 README.md / TUTORIAL.md 为准；对执行契约以 SKILL.md / references 为准。
• 用户未问技术实现时，不要讨论 slug 命名规则；开发者问命名或 slug 时，读取 development/NAMING.md。

文档分工

文档	读者	用途
根目录 README.md	普通用户	市场 说明 Tab（readme_md）
根目录 TUTORIAL.md	普通用户	市场 教程 Tab（tutorial_md）
根目录 DEMO.md	普通用户	市场 演示 Tab（demo_video_url + demo_md）
根目录 CHANGELOG.md	普通用户	市场 更新日志 Tab（按版本小节 → changelog）
SKILL.md（本文）	LLM / OpenClaw 平台	技能入口、触发与运行契约摘要
references/	Agent 编排 / 调用	CLI、Action、schema 契约（Agent 主读）
development/	开发者 / AI 编程代理	需求、开发教程、测试、深度技术规范；产品入口见 development/PRODUCT_SURFACES.md

目录约定

复制后建议保留：

• 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 完成开发与文档定制；开发前先读 development/PRODUCT_SURFACES.md 并填写入口定位表。
5. 用户市场四 Tab 材料写入根 README.md / TUTORIAL.md / DEMO.md / CHANGELOG.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 列表（ID 来自匠厂宿主「设置 → 用户信息」）。
• 开发期技能常为不公开：不加本人 ID，开发者自己也无法在市场安装自测。取 ID 与写入步骤见 development/DEVELOPMENT.md §6。
• 当 access_scope = 0（不公开）时，平台会把 developer_ids 中的用户自动补写到 skill_user_access。
• developer_ids 建议写为正整数数组；第一个 ID 会作为主开发者同步到 skills.developer_id。