技能创建与优化指南

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

工具清单

加载：全部为核心工具，始终可用，无需 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 格式

---
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 工具写文件。路径按作用域严格区分：

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

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

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

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

第五步：验证与迭代

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

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

常见问题排查

改进已有技能

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

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

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

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

铁律

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