编写学术技能 (Writing Academic Skills)

概述

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

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

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

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

什么是技能？

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

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

技能的 ADW 映射

ADW 概念	技能创建
待证主张	压力场景下的预期行为
正文/证据	技能文档 (SKILL_zh.md)
验证失败	智能体在没有技能的情况下违反规则（基线）
验证通过	智能体在有技能的情况下遵守规则
完善	在保持合规的同时堵塞漏洞
先提出主张	在编写技能之前运行基线场景
看它失败	记录智能体使用的确切借口
最简证据	编写针对那些特定违规行为的技能
看它通过	验证智能体现在遵守了
完善循环	发现新借口 → 堵塞 → 重新验证

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

何时创建技能

创建当：

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

不要创建用于：

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

技能类型

技术 (Technique)

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

模式 (Pattern)

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

参考 (Reference)

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

目录结构

code

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

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

单独文件用于：

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

保持内联：

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

SKILL_zh.md 结构

Frontmatter (YAML):

•仅支持两个字段：name 和 description
•name: 仅使用字母、数字和连字符
•
description: 第三人称，仅描述何时使用（不是它做什么）
- •以“当...时使用”开始，专注于触发条件
- •包括具体的症状、情况和背景
- •绝不总结技能的流程或工作流
- •尽可能保持在 500 个字符以内

markdown

---
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)

code

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

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

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

测试所有技能类型

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

示例： ADW, submission_check

测试方法：

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

技术类技能 (操作指南)

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

测试方法：

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

模式类技能 (思维模型)

测试方法：

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

参考类技能 (文档)

测试方法：

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

防止借口

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

明确关闭每个漏洞

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

<Good> ```markdown 在提出主张之前写正文？删除它。重新开始。

无例外：

•不要保留它作为“参考”
•不要在寻找证据时“调整”它
•不要看它
•删除意味着删除

code

</Good>

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

尽早添加基本原则：

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

ADW 循环用于技能

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

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

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

证据：编写最简技能

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

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

完善：堵塞漏洞

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

技能创建清单 (ADW 改编)

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

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

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

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

完善阶段 - 堵塞漏洞：

质量检查：

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

底线

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

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