Skill 设计指南

在设计、编写或修改 OpenCode Skill 时，严格遵循以下准则。本指南面向所有 Skill 作者，不绑定特定技术领域。

1. Skill 是什么

Skill 是一份注入给 LLM 的领域指令。当 LLM 执行特定任务时，Skill 通过上下文注入使其"临时掌握"该领域的规范、约定和最佳实践。

Skill 是：

• 可执行的行为准则（"怎么做"和"不该做什么"）
• 具体、可验证的规则集合
• 面向 LLM 的上下文补丁

Skill 不是：

• 给人类看的教程或入门文档
• API 参考手册（那是代码注释的职责）
• 项目 README 或架构设计文档
• 泛泛而谈的"最佳实践"合集（LLM 需要的是确定性指令，不是灵感启发）

核心检验标准：LLM 读完 Skill 后，能否在不查询外部资料的情况下，独立、正确、一致地执行该领域的任务？ 如果答案是"否"，说明 Skill 还不够具体。

2. 领域与边界

2.1 单一职责

一个 Skill 只覆盖一个领域。如果 Skill 名包含"与"字（如"编码与注释规范"），说明它应该拆成两个。

2.2 拆分 vs 合并的决策表

2.3 边界声明

Skill 开头应明确声明适用范围。反例和正例：

❌ 坏边界声明："本规范适用于嵌入式开发。"（太宽泛）

✅ 好边界声明："适用于 ESP32、STM32 等嵌入式 C 项目。"或仅写一句"不绑定任何具体 HAL 设计"。

边界声明只需要一句话，放在标题下方、第一条规则之前。

3. 触发条件设计

3.1 description 字段

description 是 LLM 判断"是否加载此 Skill"的唯一依据。必须同时包含：

1. 触发场景：什么任务应该加载此 Skill（用动词短语描述，如"写 C 代码"、"提交代码"）
2. 作用域：覆盖哪些具体操作
3. 排除信号（可选）：不应该加载的场景

格式：一句话，中文。用 —— 分隔场景与范围。

3.2 触发词策略

description 中的动词决定匹配精度。优先使用精确动词，避免模糊动词。

3.3 metadata 字段

YAML 头部必须包含 metadata 字段，用于机器可读的分类标签。

格式：

---
name: your-skill-name
description: ...
license: MIT
metadata:
  tags: tag1, tag2, tag3
---

规则：

• metadata.tags 必须包含 3-5 个分类标签
• 标签用小写英文，空格分隔
• 标签应涵盖 Skill 的领域（如 writing）、核心概念（如 de-formula）、适用范围（如 scriptwriting）

示例：

metadata:
  tags: writing, de-formula, negation, abstract-description

metadata 不用于 LLM 的触发判断（那是 description 的职责），但用于工具链的索引、搜索和分类。

4. 内容组织结构

4.1 标准骨架

每个 Skill 按以下骨架组织，不可跳过层级：

## 1. 领域概述 / 为什么需要
## 2. 核心规则 1
## 3. 核心规则 2
  ### 3.1 子规则
  ### 3.2 子规则
...
## N. 快速参考（表格汇总，可选）
## N+1. 禁止事项（可选）
## N+2. 自检要求

4.2 为什么放在前面

在进入具体规则之前，用 1-2 句话说明为什么要遵守这些规则。LLM 理解动机后，能更准确地执行意图，也能在边缘情况下做出正确判断。

例如：

"这些准则偏向谨慎而非速度。对于简单任务，请自行判断。" —— 从 karpathy-guidelines

4.3 规则的组织方式

每条核心规则遵循"三段式"：

1. 断言（1 句加粗）：规则本身
2. 展开（2-4 句）：为什么、何时适用
3. 示例（正例 + 反例）：代码块或引用块

例如：

### 3.1 ISR 约束

ISR 中**绝对禁止**使用 printf、malloc、阻塞等待。

理由：ISR 必须极速返回。printf 会阻塞 UART、malloc 不可重入、阻塞等待会死锁。

**正确**：
```c
static bool IRAM_ATTR timer_callback(...) {
    vTaskNotifyGiveFromISR(task_handle, &mustYield);
    return (mustYield == pdTRUE);
}
```

**错误**：
```c
static bool IRAM_ATTR timer_callback(...) {
    printf("tick\n");  // ISR 中禁止打印
    return false;
}
```

4.4 表格的使用

以下场景优先使用表格而非段落：

• 命名约定（类型 → 格式 → 示例）
• 类型选择决策（场景 → 类型 → 说明）
• 框架选型（平台 → 推荐方案）
• 禁止/允许行为的对照

表格必须有加粗表头和 |------| 分隔行。

4.5 禁止事项

如果 Skill 包含大量禁止行为，可单独列为"禁止事项"章节，用列表呈现，每条以"禁止"开头。例如 c-coding-guidelines 第 13 节。

5. 规则设计原则

5.1 可验证性

每条规则必须可被验证。LLM 读完能回答"我有没有违反这条规则？"

5.2 禁止模糊词

Skill 中不得出现以下模糊限定词：

禁止词清单：尽量、建议、最好、一般来说、视情况而定、通常、可以（作为弱建议时）、酌情

替代方案：将弱建议升级为明确规则，或通过"权衡取舍"说明例外条件（见 5.3）。

5.3 规则的例外处理

如果规则确实有例外，必须在规则处立即说明例外条件，而不是留到末尾或指望 LLM 自行推断。

例如：

"禁止在 ISR 中使用浮点运算 —— 但 STM32 Cortex-M4/M7 带 FPU 可放宽"（见 c-coding-guidelines 第 10.1 节）

格式：规则 —— 但 例外条件

5.4 规则密度

每个 Skill 的理想规则条数：

规则数量超出上限 → 拆分为多个 Skill。

5.5 示例通用性

Skill 中的示例必须使用领域无关的通用场景，禁止引用具体项目名、库名或业务术语。

理由：Skill 会被不同项目、不同会话的 LLM 加载。如果示例包含项目专属名词（如"本项目的 foc_tick()"），陌生上下文中的 LLM 无法理解示例意图，只能跳过。

检验标准：把示例中的专有名词替换为 Foo、Bar、X、Y 等占位符后，规则逻辑是否仍然成立？如果是，说明原示例已经是通用的。

正确——通用示例：

- **配置**：启动脚本为 `start.sh`，在安装后执行一次即可。

任何项目都能类比理解。

错误——绑定具体项目：

- **配置**：本插件的 `install.mjs` 脚本会在 OpenCode 中运行。

只有该项目维护者能理解，其他 LLM 不加载此 Skill。

这也意味着：写 Skill 规则时，不能用"当前项目的经历"作为示例来源。如果规则是从一次具体事故中总结的，必须剥掉业务外壳、只保留通用逻辑后再写入。

6. 写作风格与排版

6.1 语言与称呼

• 面向中文开发者的 Skill 用中文撰写
• 面向通用场景的 Skill 用英文
• Skill 内的称呼：统一使用"你"指代 LLM，不混用"你/您/我们"
• 不使用拟人化口吻（"你应该……"比"让我们……"更精确）

6.2 排版规范

遵循 doc-writing-guidelines 的排版规则。关键项：

• 中文与英文/数字之间加空格：ESP32 的 MCPWM，频率为 20 kHz
• 中文与行内代码之间加空格：调用 `foc_tick()` 函数
• 中文标点全角（。、，），英文标点半角（.、,）
• 章节编号：## N. 章节名，子章节 ### N.M 子章节，不跳级
• 代码块：必须标注语言（```c），前后各空一行
• 表格：表头加粗，前后各空一行
• 引用块：用 > 标记重要约束、例外说明、权衡取舍

6.3 写作视角：对 AI 说话，而非教人类

Skill 是写给 LLM 看的行为指令，不是写给人类看的教程。 这意味着：

❌ 教人类怎么写（教程视角）：
"请在你的 prompt 中写'引用来源'，让 LLM 标注每条信息的出处。"

✅ 告诉 AI 怎么做（行为指令视角）：
"在给出事实性陈述时，主动标注每条陈述的信息来源，便于用户核查。"

两种视角的关键区别：

⚠️ 最容易犯的错误：用"正确/错误"对比框架教人类写 prompt。比如写"正确：请在 prompt 中写'请引用来源'"+ "错误：只写'请回答'"——这看起来是在教人类。应该改成"你应该在回答中按 [来源] 格式标注每条陈述的出处，不能只写'据研究显示'。"

检验标准：把 Skill 中的"你"替换成"本 AI"后，读起来是否仍然通顺、像 AI 的行为指南？如果不是，说明视角有问题。

6.4 代码示例

代码示例必须：

• 标注语言
• 简练（不超过 25 行）
• 正例和反例必须成对出现，用加粗标签区分（**正确**：、**错误**：）
• 反例必须用单行注释标注错误原因

示例中的代码逻辑保持正确、可编译——不能为了演示错误而刻意让代码有语法错误，反例展示的是不合规范而非无法编译。

7. 示例模板

以下是新 Skill 的骨架模板，可直接复制后填入内容：

---
name: your-skill-name
description: 你的 Skill 描述——触发场景、覆盖范围、排除信号。确保 LLM 能准确判断何时加载此 Skill。
license: MIT
---

# Skill 标题

简要说明本 Skill 的目的和适用范围（1-2 句话）。

## 1. 背景 / 为什么需要

说明为什么需要这些规则，不遵守的后果是什么。让 LLM 理解动机，而非死记规则。

## 2. 核心规则 1

**核心断言（1 句加粗）。**

展开说明：适用范围、为什么、何时需特别注意。

**正确**：

```lang
// 正例代码
```

**错误**：

```lang
// 反例代码 —— 用注释标注错在哪
```

### 2.1 子规则

……

## 3. 核心规则 2

……

## 4. 快速参考（可选）

| 规则 | 摘要 | 适用场景 |
|------|------|---------|
| ...  | ...  | ...     |

## 5. 禁止事项（可选）

- 禁止……
- 禁止……

## 6. 自检要求

输出前请自检，如出现违反以上规则的输出，重新输出。

8. 自检清单

Skill 设计完成后，逐项核查：

• description 字段是否明确触发场景和覆盖范围？（见第 3 章）
• Skill 是否只覆盖一个领域？（见第 2.1 节）
• 开篇是否有"为什么需要"的动机说明？（见第 4.2 节）
• 每条规则是否可以验证？（见第 5.1 节）
• 是否避免了"尽量"、"建议"等模糊词？（见第 5.2 节）
• 整篇 Skill 使用的是"告诉 AI 怎么做"的视角，而非"教人类怎么写"？（见第 6.3 节）
• 正例和反例是否成对出现？（见第 6.4 节）
• 需要快速查阅的内容是否用了表格？（见第 4.4 节）
• 章节编号是否连续、不跳级？（见第 4.1 节）
• 是否有禁止事项需要单独列出？（见第 4.5 节）
• 末尾是否包含"自检要求"？（见第 4.1 节）
• 核心规则数是否在合理范围（编码规范 ≤15，工作流规范 ≤8）？（见第 5.4 节）
• 示例是否剥离了项目专属名词、使用领域无关的通用场景？（见第 5.5 节）

9. 自检要求

输出前请自检，如出现违反以上规则的输出，重新输出。