skill-designer

name	skill-designer
description	Use when creating, refactoring, or evaluating any skill document — for Claude Code superpowers skills or OpenClaw agent skills.

Skill Designer

Layer 0 — 决策清单（扫一遍再动手）

问题	→ 答案决定什么
知识量 > 300 行？	是 → 移到外部文件，SKILL.md 只留接口
多平台有差异？	是 → templates/platforms/ 分文件
需要搜索/过滤？	是 → CSV + 脚本，不要 flat list
有分叉决策？	是 → 流程图；线性流程 → 编号列表
是否可复用？	否 → 不要建 skill，放 CLAUDE.md

不要打包进 skill： README.md、INSTALLATION_GUIDE.md、CHANGELOG.md、非必要文档、一次性脚本

---

Layer 1 — 标准流程

1. 创建流程

理解  →  收集具体使用场景（至少 2-3 个真实例子）
规划  →  识别可复用的 scripts / references / assets
编写  →  实现资源文件 + 写 SKILL.md
测试  →  subagent 红绿测试（见第 6 节）

资源类型三选：

• scripts/ — 确定性、可重复执行的代码（每次都需要重写的逻辑）
• references/ — 按需加载的文档/schema（保持 SKILL.md 精简）
• assets/ — 输出用的模板/样板（不加载到上下文，只用于生成交付物）

2. 分类

简单 skill    →  SKILL.md 单文件（< 200 词）
中等 skill    →  SKILL.md + 1-2 个支撑文件
复杂 skill    →  三层架构（见 Layer 2）

2. Frontmatter 规则

---
name: verb-first-with-hyphens      # 动词开头，只用字母数字和连字符
description: Use when [触发条件]   # 只写 WHEN，不写 HOW（否则 Agent 跳过正文）
---

description 反模式（会导致 Agent 不读正文）：

# ❌ 描述了流程
description: Use when saving recipes — calls XHS API, extracts structure, writes to Obsidian

# ✅ 只写触发条件
description: Use when the user shares a Xiaohongshu link and asks to save a recipe

3. SKILL.md 内部结构（渐进式披露）

## Layer 0 — 快速参考（表格/清单，可在 10 秒内扫完）
## Layer 1 — 标准流程（编号步骤，覆盖 80% 场景）
## Layer 2 — 深度参考（链接到外部文件，复杂场景按需读取）

4. Token 预算

类型	上限
常驻 skill（每次对话都加载）	200 词
按需 skill	500 词
外部参考文件	不限（按需加载）

5. 命名规范

全部 kebab-case，长度 15-25 字符为佳。按 skill 类型选模式：

类型	模式	示例
流程/动作	动名词 -ing	brainstorming, writing-skills
工具/格式/平台	纯名词	pdf, bilibili, obsidian-write
专业角色	名词+限定符	code-reviewer, api-designer
构建类	动词+名词	skill-creator, mcp-builder

详见 patterns.md 命名统计数据。

6. 测试要求

写完 skill 必须用 subagent 测试：
给一个没有 skill 的 agent 同样的任务 → 观察失败 → skill 修正 → 验证通过。
未经测试的 skill 不可投入使用。

---

Layer 2 — 深度参考

见 patterns.md：完整模板、三层架构样例、反模式列表、BM25 检索实现参考。