writing-skills

编写技能

概述

编写技能就是将测试驱动开发应用于流程文档。

个人技能存放在 Agent 专属目录（$DOTFILE_REPO_ROOT/ai/files/skills）中。

项目技能存放在 .agents/skills/ 中。

编写测试用例（使用子 Agent 设计压力场景），观察测试失败（基线行为），编写技能（文档），观察测试通过（Agent 遵从），然后重构（堵住漏洞）。

核心原则： 如果你没观察过 Agent 在没有技能时失败，就不知道这个技能是否教会了正确的方法。

必备背景知识： 使用此技能前，必须了解 superpowers:test-driven-development。该技能定义了基本的 RED-GREEN-REFACTOR 循环。此技能将 TDD 应用于文档编写。

官方指南： 从 writing-skills 技能加载 anthropic-best-practices 资源。该文档提供了额外的模式和指南，可补充此技能以 TDD 为重点的方法。

什么是技能？

技能是关于成熟技术、模式或工具的参考指南。技能帮助未来的 Claude 实例找到并采用有效的方法。

技能包括： 可复用的技术、模式、工具和参考指南

技能不包括： 讲述你曾经如何解决某个问题的故事

首先：对技能类型进行分类

尽早完成此步骤，在撰写各部分之前。

参考类

查阅资料：API、语法、命令选项、兼容性说明。

工作流类

按步骤执行的流程（通常包含关卡／检查清单）。

风格指南类

标准和惯例：命名、格式、语气、结构。

角色类

交互风格、优先事项和边界方面的行为设定。

技术／模式类

用于解决重复出现的问题的方法或思维模型。

如果某项技能涵盖多种类型，请按以下决策流程处理：

1. 先询问意图： 询问用户是否有意让技能涵盖多种类型，还是希望将其拆分为多个重点明确的技能。
2. 如果不拆分： 继续编写一项技能。选定一个主要类型，在概述中明确说明，然后继续进行 RED/GREEN/REFACTOR 测试。
3. 如果要拆分： 分析该概念并提出多种拆分方案（例如按受众、生命周期阶段、问题类型或产物类型拆分）。
4. 协作确定方案： 与用户一起选定首选拆分方案。然后为不同会话分别生成临时提示词，每项新技能对应一个提示词，并明确要求该会话使用此 writing-skills 技能。

技能的 TDD 映射

如需了解详细的 TDD 映射表和概念，请从 writing-skills 技能加载 tdd-mapping 资源。

核心概念： 整个技能创建过程遵循 RED-GREEN-REFACTOR，将 TDD 的循环应用于文档编写。

何时创建技能

适合创建的情况：

• 这项技术对你来说并非直观易懂
• 你会在不同项目中再次参考它
• 该模式适用于广泛场景（而非特定项目）
• 其他人也能从中受益

不适合创建的情况：

• 一次性解决方案
• 其他地方已有充分文档记录的标准实践
• 项目专属惯例（请写入 CLAUDE.md）

目录结构

skills/
  skill-name/
    SKILL.md
    references/
      extra-file.md
    scripts/
      codified-helper.sh
      known-steps-cli.js
    assets/
      possibly-a-circle-mask.png
      maybe-a-logo.png

规则： 技能目录中只能包含 SKILL.md。

其他所有内容都放在按类别划分的同级文件夹中：

1. references/ 用于存放较长的文档、指南和表格
2. scripts/ 用于存放可执行的辅助工具和生成器
3. assets/ 用于存放图表、图片和静态文件

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

尽可能将以下内容直接写入 SKILL.md：

• 原则和概念
• 简短的代码模式（少于 50 行）
• 决策标准和反模式

SKILL.md 结构

Frontmatter（YAML）：

• 仅支持两个字段：name 和 description
• 总长度最多 1024 个字符
• name：只能使用字母、数字和连字符（不能使用括号或特殊字符）。必须与文件夹名称一致。
• description：使用第三人称，格式为：{它的功能}，{何时使用它}，{结果是什么}
  • 内容要具体且便于搜索（症状、场景、结果）
  • 避免模糊的措辞和夸张的宣传
  • 尽可能控制在 500 个字符以内

---
name: Skill-Name-With-Hyphens
description: [what it does], [when to use it], [what the result is]
---

# Skill Name

## Overview
What is this? Core principle in 1-2 sentences.

## When to Use
[Small inline flowchart IF decision non-obvious]

Bullet list with SYMPTOMS and use cases
When NOT to use

## Core Pattern (for techniques/patterns)
Before/after code comparison

## Quick Reference
Table or bullets for scanning common operations

## Implementation
Inline code for simple patterns
Link to file for heavy reference or reusable tools

## Common Mistakes
What goes wrong + fixes

## Real-World Impact (optional)
Concrete results

Claude 搜索优化（CSO）

如需全面了解 CSO 指南，包括描述格式、关键词覆盖范围和命名规范，请从 writing-skills 技能加载 cso-guide 资源。

核心原则：

• 描述格式： {它的功能}，{何时使用它}，{结果是什么}
• 使用第三人称，以便注入系统提示词
• 使用具体的触发条件、症状和结果
• 包含便于搜索的关键词：错误消息、症状、工具

流程图用法

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

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

以下情况绝不要使用流程图：

• 参考资料 → 表格、列表
• 代码示例 → Markdown 代码块
• 线性说明 → 编号列表

如需了解 Graphviz 样式规范，请从 writing-skills 技能加载 graphviz-conventions 资源。

为你的搭档直观呈现内容： 使用 scripts/writing-skills/ 中的 render-graphs.js，将流程图渲染为 SVG：

./scripts/writing-skills/render-graphs.js ./skills/some-skill           # Each diagram separately
./scripts/writing-skills/render-graphs.js ./skills/some-skill --combine # All diagrams in one SVG

代码示例

一个出色的示例胜过许多平庸的示例

选择最相关的语言：

• 测试技术 → TypeScript/JavaScript
• 系统调试 → Shell/Python
• 数据处理 → Python

优秀示例：

• 完整且可运行
• 注释完善，解释原因
• 基于真实场景
• 清晰展示模式
• 可直接改编（而非通用模板）

不要：

• 用 5 种或更多语言实现
• 创建填空式模板
• 编写牵强的示例

你擅长移植内容——一个出色的示例就足够了。

文件组织

自包含技能

skills/defense-in-depth/
  SKILL.md

适用情况：所有内容都能直接写在文档中。

带可复用工具的技能

skills/condition-based-waiting/
  SKILL.md
scripts/condition-based-waiting/
  example.ts

适用情况：工具是可复用代码。

带大量参考资料的技能

skills/pptx/
  SKILL.md
  references/
    pptxgenjs.md
    ooxml.md
  scripts/
    render-slides.js
  assets/
    diagrams/

适用情况：参考资料过多，无法直接写入文档。

铁律（与 TDD 相同）

NO SKILL WITHOUT A FAILING TEST FIRST

这适用于新建技能和修改现有技能。

先写技能再测试？删除它，重新开始。 修改技能却不测试？同样违规。

没有例外：

• 不适用于“简单的添加”
• 不适用于“只是添加一个章节”
• 不适用于“文档更新”
• 不要将未经测试的更改保留为“参考”
• 不要在运行测试时“顺便改编”
• 删除就是删除

必备背景知识： superpowers:test-driven-development 技能解释了这为何重要。相同原则也适用于文档。

测试所有技能类型

如需了解按技能类型划分的全面测试方法，请从 writing-skills 技能加载 testing-methodology 资源。

快速参考：

• 强制遵守纪律的技能： 在压力下测试（时间紧迫、已投入大量成本、精疲力竭）
• 技术类技能： 测试应用场景和边缘情况
• 模式类技能： 测试识别能力和反例
• 参考类技能： 测试检索能力和正确应用

关键原则： 部署前先测试。没有例外。

防止技能中的自我合理化

如需了解防止漏洞和应对强制纪律类技能中自我合理化的详细策略，请从 writing-skills 技能加载 rationalization-patterns 资源。

核心原则：

• 明确封堵所有漏洞——禁止具体的规避做法
• 用根本原则回应“重精神、轻字面”的论调
• 根据基准测试建立合理化论调对照表
• 创建自检警示清单
• 在描述中补充违规症状

技能的 RED-GREEN-REFACTOR 流程

遵循 TDD 循环：

1. RED：编写失败测试（基线）——在不使用该技能的情况下，让子 Agent 运行压力场景。记录确切行为、合理化说辞，以及哪些压力导致了违规。

2. GREEN：编写最小技能——编写技能，针对这些具体的合理化说辞进行应对。使用该技能运行相同场景。Agent 此时应能遵守要求。

3. REFACTOR：堵住漏洞——Agent 找到了新的合理化说辞？添加明确的反制措施。重新测试，直到无懈可击。

如需了解完整的测试方法，包括压力类型和元测试技巧，请加载 writing-skills 技能中的 testing-methodology 资源。

反模式

❌ 叙事式示例

“在 2025-10-03 的会话中，我们发现空的 projectDir 导致了……” **为什么不好：**过于具体，无法复用

❌ 多语言稀释

example-js.js、example-py.py、example-go.go **为什么不好：**质量平平，维护负担重

❌ 流程图中包含代码

step1 [label="import fs"];
step2 [label="read file"];

**为什么不好：**无法复制粘贴，难以阅读

❌ 通用标签

helper1、helper2、step3、pattern4 **为什么不好：**标签应具有语义

停止：继续下一个技能之前

编写任何技能后，都必须停下来完成部署流程。

不要：

• 批量创建多个技能，却不逐一测试
• 当前技能尚未验证就转到下一个技能
• 因为“批量处理更高效”而跳过测试

部署未经测试的技能，就等于部署未经测试的代码。

技能创建清单（TDD 改编版）

如需获取包含所有 RED-GREEN-REFACTOR 阶段和质量检查的完整清单，请加载 writing-skills 技能中的 skill-checklist 资源。

使用 TodoWrite 为清单中的每一项创建待办事项。

简要概述：

• **RED 阶段：**创建压力场景，在不使用技能的情况下运行基线测试
• **GREEN 阶段：**编写最小技能，使用该技能运行场景
• **REFACTOR 阶段：**堵住漏洞，重新测试，直到无懈可击
• **部署：**提交，并考虑为广泛适用的技能创建 PR

发现工作流

未来的 Claude 如何找到你的技能：

1. 遇到问题（“测试不稳定”）
2. 找到 SKILL（描述与问题匹配）
3. 浏览概述（是否相关？）
4. 阅读模式（快速参考表）
5. 加载示例（仅在实施时）

针对这一工作流进行优化——尽早并频繁加入便于搜索的术语。

核心要点

创建技能就是为流程文档实践 TDD。

同一条铁律：没有先通过失败测试，就不编写技能。
同一个循环：RED（基线）→ GREEN（编写技能）→ REFACTOR（堵住漏洞）。
同样的收益：质量更高、意外更少、结果坚如磐石。

如果你对代码使用 TDD，也要对技能使用 TDD。这是将同一种规范应用于文档。