Pan-Wisdom Creator（泛智技能创建指南）

🚀 触发词与使用场景 (Trigger Phrases & Use Cases)

| 场景 (Scenario) | 触发词 (Trigger Phrase) | |----------------|------------------------| | 创建新 Skill | "写一个新 Skill"、"创建技能"、"create a skill"、"write skill for X" | | 改进现有 Skill | "改进这个 Skill"、"优化技能"、"improve this skill"、"refine" | | 整理/审计 Skill | "检查这个 Skill"、"review skill"、"audit skill"、"整理技能" | | 打包发布 | "发布到 ClawHub"、"publish skill"、"clawhub publish" | | 学习设计模式 | "Skill 设计模式"、"design patterns"、"Tool Wrapper"、"Pipeline" |

完整示例 → references/examples.md 设计模式详解 → references/design-patterns.md 六步流程细节 → references/workflow-details.md

本文编写原则：基于中文基础字符词汇，充分利用中文信息压缩比。关键英文术语保留并附中文解释。

一、什么是 Skill

Skill（技能）是一份 说明书，教 AI 完成某类专门任务。

好比"入职手册"——AI 本来什么都会点，有了 Skill 就知道"这活具体怎么做、用什么、注意什么"。

Skill 能做什么

| 能做什么 | 举例 | |---------|------| | 专业化流程 | 多步骤操作：查日历 → 发会议邀请 → 写会议记录 | | 工具整合 | 教 AI 怎么用某个 API 或文件格式 | | 领域知识 | 公司内部的数据结构、业务逻辑 | | 打包资源 | 附上脚本、模板、参考资料 |

二、核心原则

原则1：短而无歧义为妙

上下文窗口是公共资源。AI 已经够聪明了——只加它不知道的。每段自问：

"AI 需要我解释这个吗？"
"这段值它的 token 成本吗？"

宁用简洁的示例，不写长篇文字。但光短不够——必须无歧义。

原则2：控自由度

AI 选择太多易出错。给出具体的步骤和判断标准。

| 差的写法 | 好的写法 | |---------|---------| | "用户输入路径，处理后保存" | "路径必须是 /data/ 下的 .csv 文件，输出到 /out/" | | "可能的话做点验证" | "逐项检查：文件存在→格式正确→非空" |

原则3：渐进加载

不要求 AI 一次读完。按层组织，让 AI 读到哪用到哪：

层0：一句话摘要           ← AI 扫一眼就知道要不要读
层1-2：核心流程            ← 最少步骤完成工作
层3-4：参数/配置细节        ← 第4层开始用 "> 详细见 references/xxx.md"
层5-6：故障排查/高级话题     ← 只在需要时读

原则4：示例 > 定义

AI 通过示例理解比通过定义快得多。宁给一个完整示例，不写三段抽象描述。

原则5：轻依赖

优先用内置能力（exec、文件读写、标准库）。引入外部 API 时，必须写清楚前提条件和出错怎么办。

原则6：先做再写

先跑通脚本 → 再写 SKILL.md

运行不了的 Skill 等于废纸。

三、六步创建 Skill（概览）

| 步骤 | 做什么 | 参考 | |------|--------|------| | 1 | 搞清楚需求（6个问题） | workflow-details.md | | 2 | 规划资源（scripts / references / assets） | 同上 | | 3 | 生成骨架 | clawhub init-skill 或手动 | | 4 | 写正文 + 补资源 | 参考下方"正文怎么写" | | 5 | 打包 | clawhub publish | | 6 | 迭代改进 | workflow-details.md |

正文怎么写

---
name: my-skill
description: "一句话说清做什么，触发词是关键。"    # ⭐ 最重要！
metadata:
  version: "1.0"
  updated: "2026-05-12"
  owner: "Ronie"
---

完整六步流程见 references/workflow-details.md

5 种设计模式速查

| 场景 | 模式 | 参考 | |------|------|------| | 知识注入 / 信息查询 | Tool Wrapper | 设计模式详解 | | 稳定输出 / 批量生产 | Generator | 同上 | | 质量门禁 / 安全检查 | Reviewer | 同上 | | 需求模糊 / 边界不确定 | Inversion | 同上 | | 多步骤 + 检查点 | Pipeline | 同上 |

四、进阶技巧

长时间操作处理

超出上下文窗口长度的任务：

sessions_spawn({ task: "后台任务描述", runTimeoutSeconds: 300 })
// 主会话重启后，后台任务继续跑

需要 taskflow 或 sessions_spawn 功能支持。

命名规范

kebab-case：tool-wrapper.js，code-reviewer.md
全小写 + 连字符：my-awesome-skill

不要放什么

❌ API 密钥、密码、Token（用环境变量或 .env）
❌ 永久不变的配置路径（写 <skill-dir>/config.json）
❌ 版本要求以外的依赖说明

五、许可证

MIT License

Copyright (c) 2026 Pan-Wisdom Ecosystem Contributors

作者：泛智生态 | Ronie & 泛智小龙虾 🦞

参考来源：

OpenClaw skill-creator 原版
《从 Anthropic 到 Google：Agent Skills 正在进入'设计模式'阶段》— 架构师，2026-05-05
Google Cloud Tech：《5 Agent Skill design patterns every ADK developer should know》

v1.2.3 | 2026-05-15 | Pan-Wisdom Creator