# Skill Creator Skill

> 当用户想要创建、编辑、改进或调试 OpenLoaf 自定义技能（Skill）时触发。典型说法："帮我创建一个技能"、"做一个新 skill"、"把刚才的操作封装成技能"、"写一个能自动 XX 的技能"、"改一下这个 skill"、"这个 skill 为什么不触发"、"编辑我的自定义技能"、"加个全局技能"、"给当前项目加个技能"。任何涉及 `.openloaf/skills/` 目录下 `SKILL.md` 的创建 / 修改 / 调优请求都应加载本技能。也适用于用户想理解技能格式、排查触发问题、或把对话里的工作流固化成可复用能力的场景。不用于：内置技能（如 file-ops、email-ops 等）的修改——那些是平台随版本发布的只读能力。

- Skill: `openloaf/skill-creator-skill` (Agent Skill)
- Install (CLI): `npx skillmds@latest add openloaf/skill-creator-skill`
- Raw SKILL.md: https://api.skillmd.com/api/skills/openloaf/skill-creator-skill/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: openloaf (https://skillmd.com/u/openloaf)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/openloaf/skill-creator-skill

---


# 技能创建与优化指南

本技能指导你为 OpenLoaf 创建、编辑和改进自定义 Skill。Skill 是一段 Markdown 指令，当用户的请求匹配 `description` 时会被自动加载进对话，让 AI 按照里面的方法执行任务。

## 工具清单

| 工具 | 职责 | 只读 |
|------|------|------|
| `Read` / `Glob` / `Grep` | 读取现有 skill 与定位锚点（常驻工具） | 是 |
| `Write` | 创建新的 `SKILL.md` / `openloaf.json` / 辅助脚本（常驻工具） | 否 |
| `Edit` | 修改已有 skill 内容（常驻工具） | 否 |

> **加载**：全部为核心工具，始终可用，无需 `ToolSearch` 激活。本 skill 没有专有 deferred 工具 — 它是指导型 skill，教 AI 如何组织自定义 skill 文件。

## 作用域：全局技能 vs 项目技能

用户自定义技能分两种作用域，**先搞清楚该放哪里再动手**。优先级由低到高：`builtin < global < project`，同名时项目技能覆盖全局技能。

### 全局技能（Global Skill）

- **路径**：`~/.openloaf/skills/<skill-name>/SKILL.md`
- **可见范围**：所有项目的所有对话
- **适用**：跨项目通用的能力 / 个人工作习惯 / 通用文档生成 / 默认的输出风格
- **典型例子**："我写日报的固定模板"、"提交代码前先跑 lint"、"翻译时的术语表"

### 项目技能（Project Skill）

- **路径**：`{projectRoot}/.openloaf/skills/<skill-name>/SKILL.md`
- **可见范围**：仅当前项目的对话
- **适用**：项目特有的知识 / 代码约定 / 业务流程 / 只在这个仓库里有意义的工作流
- **典型例子**："这个仓库的模块约定"、"本项目的 API 鉴权流程"、"该怎么跑 E2E 测试"

### 怎么选

```
能力只在当前项目有意义（文件路径、业务术语、仓库约定）？
  └─ 是 → 项目技能（默认首选）
  └─ 否 → 跨项目复用（个人习惯、通用模板）？
        └─ 是 → 全局技能
        └─ 不确定 → 先建项目技能，将来发现多项目用得上再提升为全局
```

**铁律**：项目特有的业务知识**不要**放进全局技能——会污染其他项目。反过来，通用能力放进项目技能会错过复用机会。**拿不准时先问用户**："这个能力只有这个项目用得上，还是你其他项目也想用？"

## 第一步：理解需求

在动手写文件前，先明确四件事（对话上下文可能已经包含答案，不要重复问）：

1. **这个技能让 AI 做什么？** — 核心能力描述
2. **什么情况下应该触发？** — 用户会怎么说、在什么场景下用到
3. **预期输出是什么？** — 文件、数据、操作结果，还是对话回复
4. **属于全局还是项目作用域？** — 按上面决策树判断

如果用户说"把刚才的操作封装成技能"，回顾对话历史提取实际使用的工具序列、决策逻辑和用户修正过的地方——那些才是技能真正要固化的知识。

## 第二步：编写 SKILL.md

每个技能是一个文件夹，核心只有一个文件：`SKILL.md`。

### 文件结构

```
<skill-name>/
├── SKILL.md          # 必需 — 技能指令（YAML frontmatter + Markdown 正文）
├── openloaf.json     # 可选 — UI 展示元数据（icon、颜色、中文名）
└── scripts/          # 可选 — 辅助脚本（python/bash 等）
```

### SKILL.md 格式

```markdown
---
name: my-skill-name        # kebab-case，与文件夹名一致
description: >             # 决定 AI 何时加载这个技能——写好这一行至关重要
  当用户...时触发。典型说法："..."。不用于：...
---

# 技能标题

正文内容...
```

### description 写法要点

`description` 是技能触发的**唯一入口**，触发得准不准几乎全看它：

- **同时说清"做什么"和"何时用"** — 缺一不可
- **列举典型说法**，用引号包住用户可能说的原话 — AI 做触发判断时会直接比对这些例子
- **适度激进，宁宽勿窄** — 漏触发的危害远大于偶尔多触发。与其写"如何生成日报"，不如写"当用户提到日报、周报、工作汇总、工时记录、或想把今天做的事整理成任何形式的汇报时触发"
- **用'不用于'划清边界** — 避免误触发。例："不用于：Office 文档（→ docx/xlsx/pptx-skill）"
- **包含同义词和口语表达** — 用户不会总用标准术语，要覆盖"给我来一份"、"整一个"、"搞个"之类的口语

### 正文写法要点

- **告诉 AI 为什么**，而不是堆叠 MUST/NEVER — 用因果解释代替强制命令，模型能推理出边界情况
- **用决策树**替代长篇说明 — 用 `├─ 是 → ...` 格式清晰表达分支逻辑
- **给出具体示例** — JSON 参数、命令调用、对话片段，比抽象描述有用十倍
- **保持精简** — 理想长度 < 500 行；超长时拆分到 `scripts/` 或分层引用
- **使用祈使语气** — 写"用 Write 创建文件"而不是"你应该用 Write"

### 正文推荐结构

```markdown
# 技能标题

一段话概述本技能覆盖什么。

## 触发条件
列举哪些用户说法 / 场景应触发本技能。

## 工作流程
按步骤描述 AI 应该怎么做。用编号步骤 + 决策树。

## 工具使用
列出本技能依赖的工具及用法要点。

## 示例
1-2 个端到端完整示例。

## 常见陷阱
容易犯的错误和注意事项。

## 铁律
3-5 条不可违反的核心规则。
```

## 第三步：创建 openloaf.json（可选但推荐）

`openloaf.json` 提供 UI 展示信息，和 `SKILL.md` 同目录：

```json
{
  "name": "技能中文名",
  "description": "一句话中文描述",
  "icon": "🔧",
  "version": "0.1.0",
  "sourceLanguage": "zh-CN",
  "targetLanguage": "zh-CN",
  "colorIndex": 0
}
```

**colorIndex 配色**：0=青 1=紫 2=琥珀 3=天蓝 4=玫瑰 5=祖母绿 6=靛蓝 7=酸橙

**icon**：选一个最能代表技能功能的 emoji。

## 第四步：保存到磁盘

用 `Write` 工具写文件。路径按作用域严格区分：

| 作用域 | 写入路径 |
|--------|---------|
| 全局技能 | `~/.openloaf/skills/<skill-name>/SKILL.md` |
| 项目技能 | `{projectRoot}/.openloaf/skills/<skill-name>/SKILL.md` |

**创建前先检查同名冲突**，避免意外覆盖：

```
Glob: ~/.openloaf/skills/<skill-name>/SKILL.md        # 查全局
Glob: {projectRoot}/.openloaf/skills/<skill-name>/SKILL.md  # 查项目
```

冲突时询问用户：覆盖 / 换名 / 取消。

**创建完成后务必告知用户**：技能列表在对话初始化时加载，当前对话**看不到**新建技能，需要开启新对话才会生效。

## 第五步：验证与迭代

技能创建后，建议用户测试：

1. 开启新对话
2. 用触发说法让 AI 加载技能（观察是否出现技能加载提示）
3. 检查 AI 是否按照技能指令执行
4. 有问题回来修改 SKILL.md，再开新对话重试

### 常见问题排查

| 症状 | 原因 | 修复 |
|------|------|------|
| 技能不触发 | description 太窄 | 加更多典型说法，覆盖口语和同义词 |
| 技能误触发 | description 太宽 | 加"不用于"限定，划清与其他技能的边界 |
| AI 不遵守指令 | 正文太长或太模糊 | 缩短、加决策树、加具体示例 |
| 工具调用出错 | 没说明工具用法 | 加参数示例和调用顺序 |
| 其他项目误用到 | 误放到了全局 | 移到项目作用域（`{projectRoot}/.openloaf/skills/`） |

## 改进已有技能

用户要求改进已有技能时：

1. `Read` 现有 SKILL.md 理解当前内容
2. 与用户确认改进方向（触发准确度 / 输出质量 / 覆盖范围）
3. **只改有问题的部分**，不要重写整个文件——保持用户已验证过的部分稳定
4. 保存后让用户新开对话验证

**description 优化专项**：如果用户反馈"该触发时没触发"，聚焦优化 description：

- 问用户"你当时说的原话是什么？"，把原话加进典型说法
- 补充同义词、口语表达、中英文变体
- 检查"不用于"是否写得过于激进把正例排除了

## 铁律

1. **先问清楚再动手** — 做什么 / 何时触发 / 输出什么 / 全局还是项目，四个问题没搞清楚前不写文件
2. **作用域不要选错** — 项目特有的业务知识不进全局；通用能力别埋在单项目里
3. **description 宁宽勿窄** — 漏触发的危害远大于偶尔多触发
4. **正文讲为什么而不是堆命令** — 用因果解释代替 MUST/NEVER
5. **创建前 Glob 查冲突，创建后提示用户新对话测试** — 技能列表在对话初始化时加载