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

技能开发模板（skill-template）

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

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

• 长耗时 / RPA / 浏览器任务：必须通过宿主 Skill Action（run_skill_action）调用已声明在 assets/actions.json 中的 action；executionProfile 须为 "async"，进度见任务中心 / Skill Run Card。
• 禁止对长任务使用 exec python …/scripts/main.py run 或 process poll 干等 CLI 返回。
• 只读查询（health / stats 等）可用 executionProfile: "sync"，立即返回结果。
• 批量处理用参数化 pickCount / --pick N 顺序消费队列，不要并发同一 Profile；契约见 development/SKILL_ACTION_RUNTIME.md、references/ACTIONS.md。
• 模板源仓库本身仅示范 health / version / config-path（sync）；定制 RPA 技能后须自行增加 async action。

面向用户问答（LLM 规则）

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

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

• 这个技能是做什么的

• 这个技能怎么用

• 适合什么场景

• 使用前要准备什么

• 执行后会得到什么

• 能不能帮我完成某个业务任务

• 不要把 SKILL.md、references/、development/ 中的技术细节直接作为用户回答。

• 只有当用户明确询问命令、参数、输出结构、开发、调试、集成或排错时，才读取 references/ 或 development/。

• 若 README.md 与 SKILL.md / references 表述冲突：对用户展示与市场说明以 README.md 为准；对执行契约、CLI、schema、运行约束以 SKILL.md / references 为准。

• 回答用户时不要暴露 Playwright、DOM、Python、RPA 等实现细节，除非用户明确询问技术实现。

• 用户未问技术实现时，不要讨论 slug 命名规则；开发者问命名或 slug 时，读取 development/NAMING.md。

文档分工

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

目录约定

复制后建议保留：

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

最小命令

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

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

运行依赖

• Python 运行环境由匠厂宿主注入共享 runtime：{JIANGCHANG_DATA_ROOT}/python-runtime/.venv。
• 公共能力来自共享 runtime 安装的 jiangchang-platform-kit>=1.2.0（jiangchang_skill_core 包）；不要 vendor scripts/jiangchang_skill_core/，新技能不得在仓库内保留该目录副本。
• config、logging、runtime_env、rpa、media-assets、video_session、runtime_diagnostics 等均从共享 venv 的 jiangchang_skill_core import，而非技能目录副本。
• 根目录 requirements.txt 只声明技能特有 Python 三方依赖；jiangchang-platform-kit、playwright 等公共能力由宿主共享 runtime 提供，不要写入技能 requirements。
• metadata.openclaw.platform_kit_min_version（当前 1.2.0）是运行契约/兼容性声明，供宿主安装与启用时校验，不是技能 pip 依赖声明。
• Skill 代码不要自行 pip install；系统级依赖（如 VC++ Runtime）仅在 health / preflight 中提示用户安装。
• health 使用 collect_runtime_diagnostics 输出统一 runtime 诊断（只读，不下载/修复 media-assets）。

定制入口

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；长任务 / 任务中心见 development/SKILL_ACTION_RUNTIME.md。
6. 同步修改 scripts/util/constants.py 中的 SKILL_SLUG / SKILL_VERSION。
7. 本地 SQLite 的中文表名/字段名、标准时间字段与字段顺序规范见 references/SCHEMA.md（元数据表 _jiangchang_* + CREATE TABLE 物理顺序）。

技能命名与 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。