Pan-Wisdom Creator（泛智技能创建指南）
本文编写原则：基于中文基础字符词汇，充分利用中文信息压缩比。 关键英文术语保留并附中文解释。
完整示例见 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 | 2026-05-12 | Pan-Wisdom Creator