编写学术技能 (Writing Academic Skills)

概述

编写技能就是应用于流程文档的论证驱动写作 (ADW)。

你编写验证场景（带有子智能体的压力场景），观察它们失败（基线行为），编写技能（文档），观察验证通过（智能体遵守），然后完善（堵塞漏洞）。

核心原则： 如果你没有看到智能体在没有技能的情况下失败，你就不知道技能是否教授了正确的东西。

所需背景： 在使用此技能之前，你必须了解 superpowers:sa-writing (ADW)。该技能定义了基本的“主张-证据-完善”循环。本技能将 ADW 改编为文档编写。

什么是技能？

技能是经过验证的技术、模式或工具的参考指南。技能帮助未来的智能体实例找到并应用有效的方法。

技能是： 可重用的技术、模式、工具、参考指南 技能不是： 关于你曾经如何解决问题的叙述

技能的 ADW 映射

整个技能创建过程遵循 主张-证据-完善 (Claim-Evidence-Refine)。

何时创建技能

创建当：

• 技术对你来说不是直观显而易见的
• 你会在不同项目中再次参考这个
• 模式广泛适用（不是项目特定的）
• 他人会受益

不要创建用于：

• 一次性解决方案
• 其他地方已有良好记录的标准做法
• 项目特定的惯例（放在 CLAUDE.md 中）
• 机械约束（如果可以用 regex/validation 强制执行，自动化它——将文档留给判断调用）

技能类型

技术 (Technique)

具体的遵循步骤（condition-based-waiting, root-cause-tracing）

模式 (Pattern)

思考问题的方式（flatten-with-flags, test-invariants）

参考 (Reference)

API 文档，语法指南，工具文档

目录结构

skills/
  skill-name/
    SKILL_zh.md           # 主要参考（必需）
    supporting-file.*     # 仅在需要时

扁平命名空间 - 所有技能在一个可搜索的命名空间中

单独文件用于：

1. 重型参考 (100+ 行) - API 文档，综合语法
2. 可重用工具 - 脚本，实用程序，模板

保持内联：

• 原则和概念
• 代码模式 (< 50 行)
• 其他所有内容

SKILL_zh.md 结构

Frontmatter (YAML):

• 仅支持两个字段：name 和 description
• name: 仅使用字母、数字和连字符
• description: 第三人称，仅描述何时使用（不是它做什么）

- 以“当...时使用”开始，专注于触发条件 - 包括具体的症状、情况和背景 - 绝不总结技能的流程或工作流 - 尽可能保持在 500 个字符以内

---
name: Skill-Name-With-Hyphens
description: 当 [具体的触发条件和症状] 时使用
---

# 技能名称

## 概述
这是什么？用 1-2 句话概括核心原则。

## 何时使用
[如果决定不明显，使用小型内联流程图]

带有症状和用例的要点列表
何时**不**使用

## 核心模式 (用于技术/模式)
代码/逻辑的 前/后 对比

## 快速参考
用于浏览常见操作的表格或要点

## 实施
简单模式的内联代码
链接到重型参考或可重用工具的文件

## 常见错误
什么会出错 + 修正

## 现实世界影响 (可选)
具体结果

智能体搜索优化 (ASO)

发现的关键： 未来的智能体需要找到你的技能

1. 丰富的描述字段

目的： 智能体阅读描述以决定为给定任务加载哪些技能。让它回答：“我现在应该阅读这个技能吗？”

格式： 以“当...时使用”开始，专注于触发条件

关键：描述 = 何时使用，而不是技能做什么

描述应仅描述触发条件。不要在描述中总结技能的流程或工作流。

陷阱： 总结工作流的描述会创建一个智能体采取的捷径。技能正文变成智能体跳过的文档。

2. 关键词覆盖

使用智能体可能会搜索的词：

• 错误消息
• 症状：“不连贯”、“逻辑跳跃”、“引用缺失”
• 同义词
• 工具：实际命令，库名称

3. 描述性命名

使用主动语态，动词优先：

• ✅ creating-skills 而不是 skill-creation
• ✅ writing 而不是 writing-method

4. Token 效率 (关键)

目标字数：

• 入门工作流：每个 <150 字
• 频繁加载的技能：总共 <200 字
• 其他技能：<500 字（仍然要简洁）

流程图使用

仅在以下情况使用流程图：

• 非明显的决策点
• 你可能会过早停止的流程循环
• “何时使用 A vs B”的决策

绝不用于：

• 参考材料 → 表格，列表
• 代码示例 → Markdown 块
• 线性指令 → 编号列表

代码示例

一个优秀的示例胜过许多平庸的示例

选择最相关的语言/格式。

好的示例：

• 完整且可运行
• 解释了“为什么”的良好注释
• 来自真实场景
• 清晰展示模式

铁律 (同 ADW)

没有先行的验证失败，就没有技能
(NO SKILL WITHOUT A FAILING TEST FIRST)

这适用于新技能和对现有技能的编辑。

在测试之前编写技能？删除它。重新开始。

测试所有技能类型

纪律执行类技能 (规则/要求)

示例： ADW, submission_check

测试方法：

• 学术问题：他们理解规则吗？
• 压力场景：他们在压力下遵守吗？
• 识别借口并添加明确的反制措施

技术类技能 (操作指南)

示例： condition-based-waiting, root-cause-tracing

测试方法：

• 应用场景：他们能正确应用技术吗？
• 变体场景：他们能处理边缘情况吗？

模式类技能 (思维模型)

测试方法：

• 识别场景：他们能识别模式何时适用吗？
• 反例：他们知道何时不应用吗？

参考类技能 (文档)

测试方法：

• 检索场景：他们能找到正确的信息吗？
• 应用场景：他们能正确使用找到的信息吗？

防止借口

执行纪律的技能需要抵制合理化。智能体很聪明，会在压力下寻找漏洞。

明确关闭每个漏洞

不要只陈述规则——禁止具体的变通方法：

<Good>

在提出主张之前写正文？删除它。重新开始。

**无例外：**
- 不要保留它作为“参考”
- 不要在寻找证据时“调整”它
- 不要看它
- 删除意味着删除

</Good>

解决“精神 vs 字面”的争论

尽早添加基本原则：

**违反规则的字面意思就是违反规则的精神。**

ADW 循环用于技能

主张：基线测试 (看它失败)

在没有技能的情况下运行压力场景。记录确切行为：

• 他们做了什么选择？
• 他们使用了什么借口（逐字记录）？

证据：编写最简技能

编写解决那些特定借口的技能。不要为假设情况添加额外内容。

在有技能的情况下运行相同的场景。智能体现在应该遵守。

完善：堵塞漏洞

智能体找到了新借口？添加明确的反制措施。重新测试直到无懈可击。

技能创建清单 (ADW 改编)

主张阶段 - 编写验证失败：

• 创建压力场景
• 在没有技能的情况下运行场景 - 逐字记录基线行为
• 识别借口/失败的模式

证据阶段 - 编写最简技能：

• 命名规范
• Frontmatter 仅包含 name 和 description
• 描述以“当...时使用”开始
• 描述使用第三人称
• 关键词覆盖
• 清晰的概述和核心原则
• 解决在主张阶段识别的具体失败
• 一个优秀的示例
• 在有技能的情况下运行场景 - 验证智能体遵守

完善阶段 - 堵塞漏洞：

• 识别测试中的新借口
• 添加明确的反制措施
• 建立借口表
• 创建危险信号列表
• 重新测试直到无懈可击

质量检查：

• 仅在决策不明显时使用流程图
• 快速参考表
• 常见错误部分
• 无叙事性讲故事

底线

创建技能就是用于流程文档的 ADW。

同样的铁律：没有先行的失败验证就没有技能。 同样的循环：主张（基线）→ 证据（编写技能）→ 完善（堵塞漏洞）。 同样的好处：更好的质量，更少的意外，无懈可击的结果。