| 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 [触发条件]
---
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 检索实现参考。
