tomevault-io 编写学术技能 (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 文档，语法指南，工具文档
目录结构
skills/
skill-name/
SKILL_zh.md # 主要参考（必需）
supporting-file.* # 仅在需要时
扁平命名空间 - 所有技能在一个可搜索的命名空间中
单独文件用于：
- 重型参考 (100+ 行) - API 文档，综合语法
- 可重用工具 - 脚本，实用程序，模板
保持内联：
- 原则和概念
- 代码模式 (< 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>
### 解决“精神 vs 字面”的争论
尽早添加基本原则：
```markdown
**违反规则的字面意思就是违反规则的精神。**
ADW 循环用于技能
主张：基线测试 (看它失败)
在没有技能的情况下运行压力场景。记录确切行为：
- 他们做了什么选择？
- 他们使用了什么借口（逐字记录）？
证据：编写最简技能
编写解决那些特定借口的技能。不要为假设情况添加额外内容。
在有技能的情况下运行相同的场景。智能体现在应该遵守。
完善：堵塞漏洞
智能体找到了新借口？添加明确的反制措施。重新测试直到无懈可击。
技能创建清单 (ADW 改编)
主张阶段 - 编写验证失败：
- 创建压力场景
- 在没有技能的情况下运行场景 - 逐字记录基线行为
- 识别借口/失败的模式
证据阶段 - 编写最简技能：
- 命名规范
- Frontmatter 仅包含 name 和 description
- 描述以“当...时使用”开始
- 描述使用第三人称
- 关键词覆盖
- 清晰的概述和核心原则
- 解决在主张阶段识别的具体失败
- 一个优秀的示例
- 在有技能的情况下运行场景 - 验证智能体遵守
完善阶段 - 堵塞漏洞：
- 识别测试中的新借口
- 添加明确的反制措施
- 建立借口表
- 创建危险信号列表
- 重新测试直到无懈可击
质量检查：
- 仅在决策不明显时使用流程图
- 快速参考表
- 常见错误部分
- 无叙事性讲故事
底线
创建技能就是用于流程文档的 ADW。
同样的铁律：没有先行的失败验证就没有技能。 同样的循环：主张（基线）→ 证据（编写技能）→ 完善（堵塞漏洞）。 同样的好处：更好的质量，更少的意外，无懈可击的结果。
Converted and distributed by TomeVault — claim your Tome and manage your conversions.