Skill Panwisdom Creator

中文：创建、编辑、改进、升级、审查、迭代、重构 Skill 技能。当用户需要写新技能、改现有技能、或整理技能时使用。

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 & 泛智小龙虾 🦞

参考来源：

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

v1.2 | 2026-05-12 | Pan-Wisdom Creator