skill-creator-plus

创建符合 ClawHub 规范的 OpenClaw 技能。按以下规则执行，不要跳过章节，不要发明规范中未列出的约定。

未提供技能名和用途时，先询问用户。

---

关于 Skills

Skills 是模块化、自包含的包，通过提供专业化的工作流程、工具和知识来扩展 OpenClaw 的能力。可以把 Skill 看作特定领域或任务的"入职指南"——它们将 OpenClaw 从通用 agent 转变为具备专门处理流程的 specialized agent，而这是任何模型都无法完全拥有的能力。

Skills 能提供什么

1. 1. 专业化工作流程 — 特定领域的多步骤流程
2. 工具集成 — 操作特定文件格式或 API 的指引
3. 领域专业知识 — 公司专属知识、Schema、业务逻辑
4. 打包资源 — 复杂重复任务的脚本、参考资料和资产文件

---

核心原则

简洁是关键

context window 是公共资源。Skills 与 OpenClaw 所需的其他内容共享 context window：system prompt、对话历史、其他 Skills 的元数据，以及实际的用户请求。

默认假设：OpenClaw 已经非常聪明。 只添加 OpenClaw 还没有的内容。每一条信息都要质疑："OpenClaw 真的需要这个解释吗？"以及"这个段落的 token 消耗值得吗？"

用简洁的例子替代冗长的解释。

设定适当的自由度

根据任务的脆弱性和可变性匹配具体的约束程度：

高自由度（基于文本的指令）：当多种方法都可行、决策依赖上下文或启发式方法引导方案时使用。

中自由度（伪代码或带参数的脚本）：当存在优选模式、可接受一定变化或配置影响行为时使用。

低自由度（特定脚本，参数少）：当操作脆弱易错、一致性至关重要或必须遵循特定顺序时使用。

可以把 OpenClaw 想象成在探索一条路径：狭窄的悬崖桥需要具体的护栏（低自由度），而开阔的场地允许多条路线（高自由度）。

---

文件结构

只生成两个文件——无 README.md、无 CHANGELOG.md、无辅助文档：

CODEBLOCK0

技能的结构

每个技能由一个必需的 SKILL.md 文件和可选的打包资源组成：

CODEBLOCK1

SKILL.md（必需）

每个 SKILL.md 包含：

• - Frontmatter（YAML）：包含 name 和 description 字段。这是 OpenClaw 判断技能何时被使用的唯一依据。
• Body（Markdown）：技能使用说明。仅在技能触发后加载（如果需要的话）。

打包资源（可选）

Scripts（scripts/）：可执行代码，用于需要确定性可靠性或被反复重写的任务。优势：token 高效、确定性、可不加载到 context 中执行。

References（references/）：文档和参考资料，按需加载。优势：保持 SKILL.md 精简，仅在 OpenClaw 判定需要时加载。

Assets（assets/）：不打算加载到 context 中的文件，而是用于 OpenClaw 生成的输出中（模板、图片、样板代码等）。

什么不应该包含

技能应只包含直接支持其功能的必要文件。不要创建：README.md、INSTALLATIONGUIDE.md、QUICKREFERENCE.md、CHANGELOG.md 等。

---

渐进式披露设计原则

Skills 使用三级加载系统来高效管理 context：

1. 1. 元数据（name + description） — 始终在 context 中（约100词）
2. SKILL.md 正文 — 技能触发时（<5000词）
3. 打包资源 — OpenClaw 按需加载（无限量）

保持 SKILL.md 正文简洁且在500行以内以减少 context 膨胀。内容接近此限制时分拆到单独文件。

核心原则：当技能支持多种变体、框架或选项时，只在 SKILL.md 中保留核心工作流和选择指引。将变体特有细节移到单独的 reference 文件。

---

理解 ClawHub Scanner

在写任何内容之前，先理解 scanner 的工作方式：

1. description 摘要是 scanner 唯一信任的信息。
_meta.json 字段（requiredConfigPaths、primaryCredential、requires）被存储但不会在 registry API 中显示。scanner 需要验证的一切必须在 description 中——而且是前 ~160 字符内（registry 截断点）。

2. scanner 是迭代的——每次修复暴露下一个问题。
每个 rejected 版本都计入技能历史。在 checklist 通过之前不要发布。

3. scanner 无法验证嵌套内容。
嵌入在 here-string 或其他代码块内的脚本会被标记为截断和无法验证。所有 scanner 需要读取的内容必须是扁平的、独立的。

4. scanner 是语义化的，不是关键词匹配。
它理解 logged vs transmitted、always:true vs always:false、handle vs userId、required vs optional credentials 的区别。

5. scanner 默认保守。
它阻止和警告而不是批准。

---

OpenClaw Parser Gotchas（导致技能静默消失）

这些会静默破坏技能检测——无报错，技能直接从 openclaw skills list 消失：

• - Frontmatter 缺少闭合 ---：OpenClaw 会完全静默解析失败。始终验证闭合分隔符存在。
• openclaw 在 metadata.openclaw.requires.bins 中：OpenClaw 不识别自身为要检查的 bin，会静默隐藏技能。永远不要把 openclaw 放入 bins。
• ~/.openclaw/skills/ 中的技能默认自动加载：managedSkillsDir = ~/.openclaw/skills/ 是 OpenClaw 默认始终加载的路径，无需 extraDirs 配置。
• INLINECODE15 仅用于加载非标准路径的技能（如 ~/.config/my-skills/）。
• 编码：始终用 UTF-8 no-BOM 编码写入 SKILL.md。BOM 会静默破坏 YAML 解析。

---

ClawHub Scanner Criteria

逐项明确处理——先在 description 中处理，再在正文中处理。

1. Purpose & Capability

• - 精确说明调用哪些 API/服务（如 "feishu.open.feishu.cn only"）
• 说明技能不做什么（如 "no data forwarded to third parties"）
• 后台进程：精确说明什么是 READ、什么是 TRANSMITTED、什么是 LOGGED
• 长生命周期 token：说明 rotation 指引 + 主机入侵时立即 rotation
• 一次性 setup secrets：明确说明"delete afterward"

2. Instruction Scope

• - Required binaries 和 credentials 在 description 开头（fits in ~160-char summary）
• Required CLIs 在两处都声明：

- metadata.openclaw.requires.anyBins（SKILL.md frontmatter） - _meta.json requires.anyBinaries（registry 元数据）

• - SKILL.md 正文和 _meta.json 必须一致
• OS 限制在 description 中说明
• 最小权限：声明 "grant token minimal permissions only"

3. Install Mechanism

• - 运行时无外部脚本下载——所有 worker 代码内联在 SKILL.md 中
• Worker 脚本从 SKILL.md 运行时提取，不是从字符串字面值构造

4. Credentials

• - 所有 credential 要求在 description 中命名（文件路径 + 字段名）
• 区分 required vs optional 字段
• 任何脚本中无 token 字面值——运行时从磁盘读取
• 所有运行时文件权限限制（icacls/chmod 600）
• 长期 token：包含 rotation 指引和入侵时立即 rotation 说明

5. Persistence & Privilege

• - always:true 在社区技能中禁止
• 后台进程仅 opt-in——永不自主启动
• 在 _meta.json 中声明 persistence
• Description 必须说明：什么被 READ、被 TRANSMITTED、被 LOGGED，去向

---

技能创建流程

技能创建包含以下步骤：

1. 1. 用具体示例理解技能
2. 规划可复用的技能内容（scripts、references、assets）
3. 初始化技能（运行 initskill.py，如需要）
4. 编辑技能（实现资源并编写 SKILL.md）
5. 打包技能（运行 packageskill.py，如需要）
6. 基于实际使用迭代

Step 1：用具体示例理解技能

只有当技能的用法已经充分理解时才跳过此步。即使在处理现有技能时，这一步仍然有价值。

要创建一个有效的技能，需要清晰理解技能使用的具体示例。例如，构建 image-editor 技能时：

• - "image-editor 技能应该支持什么功能？编辑、旋转、还是其他？"
• "能给一些技能使用方式的示例吗？"

从最重要的问题开始，当对技能应支持的功能有了清晰认识时结束此步。

Step 2：规划可复用的技能内容

将具体示例转化为有效技能：

1. 1. 考虑如何从零开始执行这个示例
2. 确定执行这些工作流时，哪些 scripts、references 和 assets 会很有帮助

Step 3：初始化技能

从零创建新技能时，运行 init_skill.py 脚本：

CODEBLOCK2

Step 4：编辑技能

编辑技能时，记住技能是为另一个 OpenClaw 实例创建的。包括对另一个 OpenClaw 实例执行这些任务有益且非显而易见的 info。

Step 5：打包技能

技能开发完成后，打包成分发的 .skill 文件：

CODEBLOCK3

打包脚本会自动验证 YAML frontmatter、命名规范、description 质量、文件组织。

Step 6：迭代

测试技能后，用户可能会要求改进：

1. 1. 用技能处理真实任务
2. 注意到困难或低效之处
3. 确定 SKILL.md 或打包资源应如何更新
4. 实现更改并再次测试

---

文件格式规范

SKILL.md Frontmatter

CODEBLOCK4

规则：

• - Description 是一个带引号的单行字符串
• 首先写亮点说明——用清晰、动作导向语言（如 "Facebook Page manager: post, schedule, reply & get insights"）。这是用户在 ClawHub 搜索时首先读到的。不要以"AI"开头。不要以"Requires:"开头。
• 技术要求跟在亮点说明后面
• 亮点说明 + 技术要求合并后在 ~160 字符内
• 永远不要把 openclaw 放入 bins 或 anyBins
• 不要使用 always:true
• 不要添加其他 frontmatter 字段
• Frontmatter 必须以闭合的 --- 行结束

好的 description 示例：
CODEBLOCK5

_meta.json

CODEBLOCK6

关键规则：

• - ownerId 必须是 registry userId，不是 handle（从 clawhub inspect <slug> --json 输出中获取 owner.userId）
• 如果有凭证：_meta.json 需要 requiredConfigPaths、INLINECODE27
• 如果有后台进程：_meta.json 需要 persistence 块
• 永远不要在 requires.binaries 中包含 INLINECODE31

---

SKILL.md 内容结构

STEP 1 — 凭证加载（如需要）

如果缺失，显示完整 setup 流程：

1. 1. 检测可用资源
2. 要求用户提供所需值
3. 保存配置文件
4. 立即限制所有运行时文件权限

STEP 2 — 核心功能

• - 支持操作表（方法、端点、参数）
• 每种请求类型的可复用调用模式
• 所有代码内联——无外部脚本下载
• 所有 API 调用包装在 try/catch 中

STEP 3 — 错误处理

• - 每个 API 调用的 try/catch
• 错误代码表，包含精确修复方法
• 告诉用户每个错误具体要做什么

Agent Rules（始终包含）

• - 先加载凭证；如缺失，引导 setup
• 永不将 tokens 作为字面值嵌入——运行时从磁盘读取
• 立即限制所有运行时文件的权限
• 日志只含 metadata——无 secrets，无 message 内容
• 后台进程 opt-in——无明确用户请求不启动
• 任何错误：解析错误代码，对照表格，告诉用户具体要做什么
• 对于 setup-only secrets：提醒用户使用后删除
• 对于长期 tokens：提醒定期 rotation，主机入侵时立即 rotation

---

发布后

CODEBLOCK7

---

安全规则（不可协商）

• - 永不硬编码用户 ID、channel ID、tokens 或个人标识符
• 所有 secrets 在用户拥有的配置文件中
• Worker 运行时从磁盘读取凭证
• icacls/chmod 600 on ALL 运行时文件
• 日志：仅 metadata——无 secrets，无 message 内容
• 长期 tokens：rotation 指引；入侵时立即 rotation
• Setup-only secrets：使用后删除说明
• 后台进程 opt-in 且在 _meta.json 中声明
• always:true 禁止
• ownerId 必须是 registry userId
• 最小权限：明确声明 "grant token minimal permissions only"

---

Validation Checklist（发布到 ClawHub 之前必须逐项确认）

DESCRIPTION / SUMMARY（scanner 只读 ~160 字符）

• - [ ] 用清晰明了的亮点说明开头（做什么，动作导向，不以"AI"开头）
• [ ] 亮点说明后面跟着："Requires: [binaries]. Reads [credentials file] ([fields])."
• [ ] 亮点说明 + 技术要求合并在 ~160 字符内
• [ ] 前 ~160 字符内包含必需 binaries
• [ ] 前 ~160 字符内包含凭证文件路径和字段名
• [ ] 明确命名 API/服务
• [ ] 声明 "No data forwarded to third parties; all calls go to [domain] only"
• [ ] 后台进程：TRANSMITTED / LOGGED 分解在 description 中
• [ ] Setup-only secrets：声明 "delete afterward"
• [ ] Long-lived tokens：声明 rotation + 入侵时立即 rotation
• [ ] 最小权限：声明 "grant token minimal permissions only"

FRONTMATTER（parser gotchas——静默失败）

• - [ ] frontmatter 块必须以 --- 正确闭合（不能缺少结尾分隔符）
• [ ] 只有 name 和 description（加 metadata 行）——无其他 frontmatter 字段
• [ ] metadata.openclaw.requires 使用 anyBins——不是 INLINECODE35
• [ ] 任何地方都没有 openclaw 在 bins 或 anyBins 中
• [ ] 无 always:true
• [ ] 文件以 UTF-8 no-BOM 编码写入

_meta.json

• - [ ] ownerId 是 registry userId（不是 handle）
• [ ] requiredConfigPaths 列出所有凭证文件
• [ ] primaryCredential.fields 列出所有字段；required/optional 分离
• [ ] 有后台进程时有 persistence 块
• [ ] requires.anyBinaries 已声明（不是 binaries: ["openclaw"]）

一般规则

• - [ ] 无 README.md 或辅助文档
• [ ] 无硬编码个人 ID、tokens、channel 名称
• [ ] 发布前 openclaw skills list 确认技能为 ✓ ready

发布后

• - [ ] GitHub repo About description 已设置
• [ ] GitHub repo homepage 已设置为 ClawHub URL
• [ ] openclaw skills list 确认技能为 ready
• [ ] clawhub inspect [slug] summary 以亮点说明开头

---

常见错误案例

错误1：description 以技术要求开头

"Requires: powershell/pwsh. Reads ~/.config/fb-page/credentials.json..."

用户在 ClawHub 搜索时跳过干巴巴的技术信息——他们先看亮点说明。

错误2：版本号不一致

SKILL.md frontmatter、_meta.json、ClawHub 三端版本必须完全一致。

错误3：scripts 文件名不匹配

SKILL.md 中写的脚本文件名必须与实际文件名完全一致。

错误4：缺少 frontmatter 闭合 ---

OpenClaw 完全静默解析失败，技能从列表消失。

错误5：把 openclaw 放入 anyBins

openclaw runtime 永远不满足自己，技能被静默隐藏。

---

发布命令

CODEBLOCK9

版本号规则（semver）：

• - 首次发布：1.0.0
• 小改（错别字、描述优化）：patch +0.0.1
• 功能增加/改进：minor +0.1.0
• 破坏性变更：major +1.0.0