openloaf 技能创建与优化指南
本技能指导你为 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 测试"
怎么选
能力只在当前项目有意义（文件路径、业务术语、仓库约定）？
└─ 是 → 项目技能（默认首选）
└─ 否 → 跨项目复用（个人习惯、通用模板）？
└─ 是 → 全局技能
└─ 不确定 → 先建项目技能，将来发现多项目用得上再提升为全局
铁律：项目特有的业务知识不要放进全局技能——会污染其他项目。反过来，通用能力放进项目技能会错过复用机会。拿不准时先问用户："这个能力只有这个项目用得上，还是你其他项目也想用？"
第一步：理解需求
在动手写文件前，先明确四件事（对话上下文可能已经包含答案，不要重复问）：
- 这个技能让 AI 做什么？ — 核心能力描述
- 什么情况下应该触发？ — 用户会怎么说、在什么场景下用到
- 预期输出是什么？ — 文件、数据、操作结果，还是对话回复
- 属于全局还是项目作用域？ — 按上面决策树判断
如果用户说"把刚才的操作封装成技能"，回顾对话历史提取实际使用的工具序列、决策逻辑和用户修正过的地方——那些才是技能真正要固化的知识。
第二步：编写 SKILL.md
每个技能是一个文件夹，核心只有一个文件：SKILL.md。
文件结构
<skill-name>/
├── SKILL.md # 必需 — 技能指令（YAML frontmatter + Markdown 正文）
├── openloaf.json # 可选 — UI 展示元数据（icon、颜色、中文名）
└── scripts/ # 可选 — 辅助脚本（python/bash 等）
SKILL.md 格式
---
name: my-skill-name # kebab-case，与文件夹名一致
description: > # 决定 AI 何时加载这个技能——写好这一行至关重要
当用户...时触发。典型说法："..."。不用于：...
---
# 技能标题
正文内容...
description 写法要点
description 是技能触发的唯一入口，触发得准不准几乎全看它：
- 同时说清"做什么"和"何时用" — 缺一不可
- 列举典型说法，用引号包住用户可能说的原话 — AI 做触发判断时会直接比对这些例子
- 适度激进，宁宽勿窄 — 漏触发的危害远大于偶尔多触发。与其写"如何生成日报"，不如写"当用户提到日报、周报、工作汇总、工时记录、或想把今天做的事整理成任何形式的汇报时触发"
- 用'不用于'划清边界 — 避免误触发。例："不用于：Office 文档（→ docx/xlsx/pptx-skill）"
- 包含同义词和口语表达 — 用户不会总用标准术语，要覆盖"给我来一份"、"整一个"、"搞个"之类的口语
正文写法要点
- 告诉 AI 为什么，而不是堆叠 MUST/NEVER — 用因果解释代替强制命令，模型能推理出边界情况
- 用决策树替代长篇说明 — 用
├─ 是 → ...格式清晰表达分支逻辑 - 给出具体示例 — JSON 参数、命令调用、对话片段，比抽象描述有用十倍
- 保持精简 — 理想长度 < 500 行；超长时拆分到
scripts/或分层引用 - 使用祈使语气 — 写"用 Write 创建文件"而不是"你应该用 Write"
正文推荐结构
# 技能标题
一段话概述本技能覆盖什么。
## 触发条件
列举哪些用户说法 / 场景应触发本技能。
## 工作流程
按步骤描述 AI 应该怎么做。用编号步骤 + 决策树。
## 工具使用
列出本技能依赖的工具及用法要点。
## 示例
1-2 个端到端完整示例。
## 常见陷阱
容易犯的错误和注意事项。
## 铁律
3-5 条不可违反的核心规则。
第三步：创建 openloaf.json（可选但推荐）
openloaf.json 提供 UI 展示信息，和 SKILL.md 同目录：
{
"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 # 查项目
冲突时询问用户：覆盖 / 换名 / 取消。
创建完成后务必告知用户：技能列表在对话初始化时加载，当前对话看不到新建技能，需要开启新对话才会生效。
第五步：验证与迭代
技能创建后，建议用户测试：
- 开启新对话
- 用触发说法让 AI 加载技能（观察是否出现技能加载提示）
- 检查 AI 是否按照技能指令执行
- 有问题回来修改 SKILL.md，再开新对话重试
常见问题排查
| 症状 | 原因 | 修复 |
|---|---|---|
| 技能不触发 | description 太窄 | 加更多典型说法，覆盖口语和同义词 |
| 技能误触发 | description 太宽 | 加"不用于"限定，划清与其他技能的边界 |
| AI 不遵守指令 | 正文太长或太模糊 | 缩短、加决策树、加具体示例 |
| 工具调用出错 | 没说明工具用法 | 加参数示例和调用顺序 |
| 其他项目误用到 | 误放到了全局 | 移到项目作用域（{projectRoot}/.openloaf/skills/） |
改进已有技能
用户要求改进已有技能时：
Read现有 SKILL.md 理解当前内容- 与用户确认改进方向（触发准确度 / 输出质量 / 覆盖范围）
- 只改有问题的部分，不要重写整个文件——保持用户已验证过的部分稳定
- 保存后让用户新开对话验证
description 优化专项：如果用户反馈"该触发时没触发"，聚焦优化 description：
- 问用户"你当时说的原话是什么？"，把原话加进典型说法
- 补充同义词、口语表达、中英文变体
- 检查"不用于"是否写得过于激进把正例排除了
铁律
- 先问清楚再动手 — 做什么 / 何时触发 / 输出什么 / 全局还是项目，四个问题没搞清楚前不写文件
- 作用域不要选错 — 项目特有的业务知识不进全局；通用能力别埋在单项目里
- description 宁宽勿窄 — 漏触发的危害远大于偶尔多触发
- 正文讲为什么而不是堆命令 — 用因果解释代替 MUST/NEVER
- 创建前 Glob 查冲突，创建后提示用户新对话测试 — 技能列表在对话初始化时加载