Skill: ronie-shi/skill-panwisdom-creator (version 3.1.3)

--- name: skill-panwisdom-creator description: 中文技能创作指南 — 教 AI 创建、编辑、审查、发布高质量技能。六步工作流+五种设计模式+渐进加载。Chinese-first, bilingual triggers. 创建技能/write skill、改技能/edit skill 直接激活。审查技能/review skill、发布技能/publish skill 仅在用户明确指出"审查/发布[具体技能名]"时询问确认，不自动执行，不响应泛化的"review一下""发布一下"。 metadata: version: "3.1.3" updated: "2026-05-25" owner: "泛智生态 / Ronie & 泛智小龙虾" --- <!-- fz:skill:{hash8}:wsl_lobster:{ts36} --> # Pan-Wisdom Creator（泛智技能创建指南 v3.1.3） > **编写原则**：中文优先，利用 2.35x 信息密度优势；同时保持国际化简明英文可读。英文术语保留于代码/路径/命令中，关键术语附中文解释。 > 详细协议 -> `references/` 按需加载。 ## 一、Skill 基础 Skill = 教 AI 完成专门任务的"说明书"。标准结构：`SKILL.md`（核心，<300行）+ 可选 `scripts/` `references/` `assets/`。 ## 二、核心原则 ### 原则1：简短无歧义为妙 **上下文窗口是公共资源**。AI 已经够聪明了——只加它不知道的。每段自问："AI 需要我解释这个吗？""这段值它的 token 成本吗？" ### 原则2：控自由度 越具体越不会错： | 自由度 | 适合 | 写法 | | ------ | ---- | ---- | | **高**（给方向） | 多种做法都行 | 文字描述 | | **中**（定模式） | 有通用做法 | 伪代码/参数脚本 | | **低**（定死） | 易出错、顺序不能乱 | 写死的脚本 | 过独木桥要围栏（低），过草原随意走（高）。 ### 原则3：渐进加载 三层加载，正文只写核心流程，细节放参考文件： ``` 第1层（常驻）-> name + description（~100字） 第2层（触发后）-> SKILL.md 正文（<300行） 第3层（按需）-> references/、scripts/（不占常驻上下文） ``` 用好链接——"详见 xxx.md"，AI 需要时会去读。 ### 原则4：示例 > 定义 AI 通过示例理解比通过定义快得多。宁给一个完整示例，不写三段抽象描述。 ### 原则5：轻依赖 优先用内置能力（exec、文件读写、标准库）。引入外部 API 时必须写清楚前提条件和出错怎么办。 ### 原则6：先做再写 ``` 先跑通脚本 -> 再写 SKILL.md ``` 运行不了的 Skill 等于废纸。技能中引用的每一个 `scripts/` 文件都必须是**已实际跑通验证过的**。 ### 中文补充原则 中文香农熵 9.65 bits/字（英文 4.1）→ 中文天然压缩率更高： | 原则 | 做法 | 反模式 | |------|------|--------| | **术语基向量化** | session->会话、inbox->收件箱、cron->定时任务 | ❌ 中英混杂 | | **句式压缩** | 利用中文高信息密度缩短句子 | ❌ 长句套从句 | | **结构就近** | 相关信息就近放，减少跨层跳跃 | ❌ "何时用"和"怎么用"分两处写 | ## 三、设计模式 — 先选模式再动笔 > 来源：Google Cloud Tech 5 Agent Skill Design Patterns **先判断任务形态 → 选模式 → 写正文**。Skill 应**聚焦一种模式**（常见错误：一个 Skill 同时当手册+模板+审查器）。 | 任务类型 | 推荐模式 | 别选错 | |---------|---------|--------| | AI 不懂某个框架/库 | **Tool Wrapper** | ❌ 不要把规范全文塞进 SKILL.md | | 需要固定格式输出 | **Generator** | ❌ 不要把模板和风格指南混在一起 | | 需要检查/评分 | **Reviewer** | ❌ 不要把标准全堆在正文里 | | 需求模糊、高风险 | **Inversion** | ❌ 不要省略门控，AI 会跳过提问 | | 多步骤复杂流程 | **Pipeline** | ❌ 不要省略检查点 | > 五种模式详解 + 反模式清单 -> `references/design-patterns.md` > 本 Skill 自身模式：Pipeline（创建流程）+ Tool Wrapper（脚本工具）。"改进""治理"为 Pipeline 的审查环节，不是独立 Reviewer 模式。 ## 四、创建流程 ### 第1步：搞清楚需求（6 问） 1. **什么时候触发？** description = 路由契约，不是简介。写具体场景，不写模糊概括。太宽->乱用；太窄->该用不用。 2. **属于哪种模式？** 对照第三节选型表确定。 3. **哪些拆出去？** 长规范->`references/`，固定模板->`assets/`，重复动作->`scripts/`。SKILL.md 只留路由+流程+边界。 4. **哪里要停下来？** 需求没问完->不生成方案；测试没过->不宣称完成；没确认->不执行。 5. **失败怎么走？** 怎么识别？哪些自动重试？哪些问人？ 6. **版本和审查？** 每个 Skill 有 owner，改走 review，高风险 Skill 有测试样例。 ### 第2步：规划资源 - 哪些可做成脚本？**写完必须实际跑通**（见原则6） - 哪些放参考资料？数据库结构、API 文档等 - 哪些放模板？输出时直接用的文件 ### 第3步：生成骨架 ```bash scripts/init_skill.py 技能名称 --path 输出目录 scripts/init_skill.py my-skill --path skills/public --resources scripts,references ``` > OpenClaw/ClawHub 用户也可用 `clawhub init-skill`。 > ⚠️ 首次使用前，先审查 `scripts/` 下的脚本内容。脚本具有执行权限，按可执行代码对待。 ### 第4步：写 SKILL.md #### 头部 ```yaml --- name: 技能名称 description: 功能+触发场景 # star: AI 靠它决定是否触发 --- ``` | OK 好 | NO 差 | | ----- | ---- | | `处理 docx：创建、编辑、审阅。当用户操作 .docx 时使用` | `文档处理`（太模糊） | **关键**：所有触发信息都放 description。正文只有触发后才加载。 #### 正文写法 - OK 用 **"做什么"** 的语气（不是"你可以做..."，而是"创建文档：调用 xyz 命令"） - OK 核心流程放正文，细节放参考文件——同一份信息不出现两次 - OK 参考文件只放一层（不要 SKILL.md -> a.md -> b.md） - OK 长参考文件（>100行）顶部加目录 - OK 用**示例模式**展示输入->输出（比文字描述更省 token） - ⛔ Skill 文件中**不要**包含：API 密钥、密码、Token、个人身份信息、内部 IP/端口 > 渐进加载的三种组织方式 -> `references/workflow-details.md` ### 第5步：打包 ```bash scripts/package_skill.py skills/你的技能名称 scripts/package_skill.py skills/你的技能名称 ./输出目录 ``` > OpenClaw/ClawHub 生态可走 `clawhub publish`。 > 打包脚本自动：检查 YAML 格式、命名规范、描述完整性、文件结构 -> 通过后生成 `.skill` 文件（zip 包）。验证失败则修好错误后重试。 ### 第5.5步：溯源标记（泛智生态自有 Skill 专属） > **触发**：创建或迭代属于泛智生态自有的 Skill 时。非泛智 Skill 跳过此步。 在 YAML frontmatter 之后、正文标题之前，插入单行 ContentID： ```markdown <!-- fz:{asset_class}:{hash8}:{node_id}:{ts36} --> ``` ContentID 格式： ``` fz:{asset_class}:{hash_prefix}:{node_id}:{ts36} ``` | 段 | 说明 | 示例 | |----|------|------| | `asset_class` | `skill` / `code` / `proj` / `media` | `skill` | | `hash_prefix` | SHA-256 内容指纹前 8 位 | `ddfad288` | | `node_id` | 生成节点 ID | `wsl_lobster` / `mac_xia` | | `ts36` | 36 进制时间戳 | `mpbf5euq` | 代码文件（`.py`/`.sh`/`.ps1`）顶部加一行： ```python # fz:skill:{hash8}:{node_id}:{ts36} ``` **标记边界**： - 泛智创作的文件 -> 标记 - 第三方代码 -> 不标记 - 泛智修改过的第三方代码 -> 标记 + 注明"基于 XXX 修改" **不做什么**：不改第三方 Skill 的文件头、不包含数据文件（.db/.csv）、不影响功能逻辑。 > 数字签名方案待商业化需求明确后设计。预留字段：`provenance_chain.signature`。 > ContentID 为纯文本注释，可被删除，其价值在于时间戳优先级证据链，非防篡改 DRM。 > 完整溯源体系 -> `references/workflow-details.md` ### 第6步：测试与迭代 **这是技能创建的核心循环**——写->测->看->改->再测。 > 完整流程见 `references/testing-evaluation.md` > 核心步骤：准备用例 -> 并行运行(with+baseline) -> 起草断言 -> 评分+基准+查看器 -> 读反馈 -> 改进 -> 重复 ## 五、改进技能 1. **从反馈中泛化。** 技能面向大规模复用——不是只针对 2-3 个测试用例。别过拟合。 2. **保持提示词精瘦。** 读对话记录，不只读最终输出。删掉导致无效忙碌的部分。 3. **解释为什么。** 当前模型理论心智好。解释推理，不用全大写 ALWAYS/NEVER。 4. **打包重复工作。** 如果所有测试用例都独立写了同一个辅助脚本，写一次放进 `scripts/`。 ``` 改进技能 -> 重跑全部测试 -> 启动查看器 -> 用户评审 -> 读反馈 -> 再改进 ``` **停止条件**：用户满意 / 反馈全空 / 无实质进展。 ## 六、描述优化 SKILL.md 头部的 `description` 决定 AI 是否触发技能。 > 完整流程见 `references/description-optimization.md` > 核心步骤：生成 20 条触发测试集 -> 用户审核 -> run_loop.py 5 轮优化 -> best_description -> 更新头部 ## 七、治理规范 | 要求 | 说明 | |------|------| | **owner** | 每个 Skill 有明确维护人 | | **review** | 每次修改走审核（人审或交叉审） | | **测试** | 带脚本/发请求/改文件的高风险 Skill 有测试样例 | | **失败处理** | 明确：哪些自动重试？哪些降级？哪些问人？ | | **清理** | 定期清理废弃规则 | ### 不同来源的信任策略 | 来源 | 策略 | |------|------| | 官方内置 Skill | 较高信任，但仍看版本 | | 团队自写 Skill | 走 review + 测试 + 变更记录 | | AI 自动生成 Skill | 默认草稿，需人确认 | | 社区第三方 Skill | 默认不信任，先安全审查 | | 带脚本的 Skill | 按可执行代码对待 | ### 更新已有技能 - **保留原名**：目录名和 `name` 字段不变 - **部署即生效**：技能内容会影响所有部署位置的 AI 行为，修改前确认后果 - **编辑前复制**：已安装技能路径可能只读，先复制到 `/tmp/技能名/`，编辑后打包 ## 八、平台适配 > 详细指南 -> `references/platform-adaptation.md`。涵盖 Claude.ai（无子任务）、Cowork（无浏览器）、Claude Code（全能力）、OpenClaw（ACP/NAS Relay）四平台差异。 ## 九、快速参考卡片 ``` 创建技能六步： 1. 搞清需求（模式选型 -> 6 问切边界） 2. 规划资源（脚本/参考/模板，脚本必须先跑通） 3. init_skill.py 生成骨架 4. 写正文 + 测试脚本 5. package_skill.py 打包 5.5 溯源标记（泛智自有 Skill 专属） 6. 测试评估循环 -> 迭代改进 -> 治理 核心原则：短->控自由度->渐进加载->示例>定义->轻依赖->先做再写 设计模式（选一种，聚焦）： 知识注入-> Tool Wrapper / 稳定输出-> Generator 质量门禁-> Reviewer / 模糊需求-> Inversion / 多步骤-> Pipeline 测试评估 -> references/testing-evaluation.md 描述优化 -> references/description-optimization.md ``` --- **作者**：泛智生态 | Ronie & 泛智小龙虾 **参考来源**：Anthropic skill-creator / OpenClaw skill-creator v1.3.0 / Google Cloud Tech 5 Agent Skill Design Patterns *v3.1.3 泛智统一版 | 2026-05-25 | SkillSpector 7项修复（analyzer双角色门控+examples触发词收窄+sync脚本安全加固） | MIT-0* ## 归因 (Provenance) | 来源 | 内容 | |------|------| | [RONIE决策] | 三版整合为 skill-panwisdom-creator v3.1.0（原地升级，非改名），以 v3.0 为内容基底吸收 v1.3.0 溯源体系 | | [RONIE决策] | 溯源标记原意为隐性 IP 保护（非显性归因），ContentID 降为一行哈希 | | [RONIE决策] | 先整合再深究 IP 策略 | | Win-ClaudeCode | v3.0 基底方案 + 三版对比分析 + 合并执行 | | WSL-OpenClaw | 独立审查：Step 5.5 可选化、Git 权威源、A+ 隐性方案、KG 表事实纠正、遗漏层补充 | | [共识] | v3.0 + v1.3.0 溯源 + WSL Q1-Q4 判断 -> v3.1.0 | | Win-ClaudeCode | v3.1.3 SkillSpector 7项修复：analyzer.md 双角色激活门控（F1&F2）、examples.md Example 1-4 触发词 Inversion 收窄（F3-F6）、sync-skill.sh dry-run+路径验证+确认门控（F7） |


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal:  | SkillSpector: clean (LOW)