# Sa Meta Skills

> 当创建新技能、编辑现有技能或在部署前验证技能工作时使用 Use when this capability is needed.

- Skill: `tomevault-io/sa-meta-skills` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/sa-meta-skills`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/sa-meta-skills/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/sa-meta-skills

---


# 编写学术技能 (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.*     # 仅在需要时
```

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

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

**保持内联：**
- 原则和概念
- 代码模式 (< 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)

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

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

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

## 测试所有技能类型

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

**示例：** ADW, submission_check

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

### 技术类技能 (操作指南)

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

**测试方法：**
- 应用场景：他们能正确应用技术吗？
- 变体场景：他们能处理边缘情况吗？

### 模式类技能 (思维模型)

**测试方法：**
- 识别场景：他们能识别模式何时适用吗？
- 反例：他们知道何时**不**应用吗？

### 参考类技能 (文档)

**测试方法：**
- 检索场景：他们能找到正确的信息吗？
- 应用场景：他们能正确使用找到的信息吗？

## 防止借口

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

### 明确关闭每个漏洞

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

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

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

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

尽早添加基本原则：

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

## ADW 循环用于技能

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

在没有技能的情况下运行压力场景。记录确切行为：
- 他们做了什么选择？
- 他们使用了什么借口（逐字记录）？

### 证据：编写最简技能

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

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

### 完善：堵塞漏洞

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

## 技能创建清单 (ADW 改编)

**主张阶段 - 编写验证失败：**
- [ ] 创建压力场景
- [ ] 在没有技能的情况下运行场景 - 逐字记录基线行为
- [ ] 识别借口/失败的模式

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

**完善阶段 - 堵塞漏洞：**
- [ ] 识别测试中的新借口
- [ ] 添加明确的反制措施
- [ ] 建立借口表
- [ ] 创建危险信号列表
- [ ] 重新测试直到无懈可击

**质量检查：**
- [ ] 仅在决策不明显时使用流程图
- [ ] 快速参考表
- [ ] 常见错误部分
- [ ] 无叙事性讲故事

## 底线

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

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

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/kun4ai) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-11 -->