Skill Title

Overview

One-two sentences explaining what this skill does and why it matters.

When to Use

• Bullet list of triggering conditions (symptoms, task types)
• When NOT to use (exclusions)

[Core Process / The Workflow / Steps]

The main workflow, broken into numbered steps or phases. Include code examples where they help. Use flowcharts (ASCII) where decision points exist.

[Specific Techniques / Patterns]

Detailed guidance for specific scenarios. Code examples, templates, configuration.

Common Rationalizations

Rationalization	Reality
Excuse agents use to skip steps	Why the excuse is wrong

Red Flags

• Behavioral patterns indicating the skill is being violated
• Things to watch for during review

Verification

After completing the skill's process, confirm:

• [ ] Checklist of exit criteria
• [ ] Evidence requirements

值得注意的是，校验器实际强制的正文章节是这五个：`## Overview`、`## When to Use`、`## Common Rationalizations`、`## Red Flags`、`## Verification`（见 [scripts/lib/skill-lint.js](https://gitcode.com/GitHub_Trending/agentskill/agent-skills/blob/020ec10a788f5703108d093a4bd3d9a7c3847d36/scripts/lib/skill-lint.js?utm_source=gitcode_repo_files#L45-L51) 的 `REQUIRED_SECTIONS`）。校验时还会先剥离围栏代码块，避免模板示例里的标题"骗过"检查。

### 各章节的设计意图

**Overview**：技能的"电梯陈述"，回答两个问题——这个技能做什么？智能体为什么应该遵循它？

**When to Use**：帮助智能体和人类判断技能是否适用于当前任务。要同时写正向触发（"Use when X"）和负向排除（"NOT for Y"）。例如 [skills/constraint-driven-development/SKILL.md](https://gitcode.com/GitHub_Trending/agentskill/agent-skills/blob/020ec10a788f5703108d093a4bd3d9a7c3847d36/skills/constraint-driven-development/SKILL.md?utm_source=gitcode_repo_files) 除了列出六个适用场景，还专门写了 "When NOT to use" 一节，把"项目已有 CONSTRAINTS.md 应直接遵循""一次性脚本"等排除项明确列出。

**Core Process**：技能的心脏，智能体遵循的逐步工作流。必须具体、可执行，不能是含糊建议。文档中给出的对照示例：

- **好**："Run `npm test` and verify all tests pass"
- **差**："Make sure the tests work"

这一点在 [skills/test-driven-development/SKILL.md](https://gitcode.com/GitHub_Trending/agentskill/agent-skills/blob/020ec10a788f5703108d093a4bd3d9a7c3847d36/skills/test-driven-development/SKILL.md?utm_source=gitcode_repo_files) 中有充分体现：它给出了 RED/GREEN/REFACTOR 的 ASCII 流程图、每个阶段的可运行 TypeScript 示例，甚至专门有一节 "Discover the Stack First" 告诫不要假设默认命令 `npm test`，而要先探测本仓库实际使用的测试工具（`package.json`、`pyproject.toml`、`./gradlew` 等）。

**Common Rationalizations**：这是精心打磨的技能最独特的特征——列出智能体用来跳过关键步骤的借口，并逐条配上反驳。它防止智能体"合理化"地绕过流程。文档原话：想想智能体每次说 "I'll add tests later" 或 "This is simple enough to skip the spec" 的时刻，把它们连同事实性的反论一起写进这张表。真实的例子见 TDD 技能的 Rationalizations 表："I'll write tests after the code works" → "You won't. And tests written after the fact test implementation, not behavior."；"Let me run the tests again just to be extra sure" → 干净跑完后重复同一条命令不会增加任何信心，除非代码已变更。

**Red Flags**：技能正在被违反的可观察信号，用于代码评审和自检。如 TDD 技能列出的 "Bug fixes without reproduction tests""Tests that pass on the first run"。

**Verification**：出口标准（exit criteria），智能体用它确认流程已完成。每一个勾选项都必须能用证据验证（测试输出、构建结果、截图等），而不是主观感觉。

## 支撑文件：何时拆分、何时内联

创建支撑文件（supporting files）的判据只有三条：

1. 参考资料超过 100 行（保持主 SKILL.md 聚焦）；
2. 需要代码工具或脚本；
3. 清单（checklist）长到足以独立成文件。

反过来，**50 行以内的模式和原则应内联在主文件中**。还有一条易被忽略的告诫：如果技能不需要可运行辅助，**不要为了对齐其他技能而创建空的 `scripts/` 目录**——空目录只增加噪音，不改变技能行为。

## 共享引用：仓库根 `references/` 的设计权衡

被多个技能共用的清单——测试、安全、性能、可访问性、definition-of-done——存放在**仓库根目录**的 `references/`，刻意不放在任何技能目录内。当前仓库对应文件为 [references/testing-patterns.md](https://gitcode.com/GitHub_Trending/agentskill/agent-skills/blob/020ec10a788f5703108d093a4bd3d9a7c3847d36/references/testing-patterns.md?utm_source=gitcode_repo_files)、[references/security-checklist.md](https://gitcode.com/GitHub_Trending/agentskill/agent-skills/blob/020ec10a788f5703108d093a4bd3d9a7c3847d36/references/security-checklist.md?utm_source=gitcode_repo_files)、[references/performance-checklist.md](https://gitcode.com/GitHub_Trending/agentskill/agent-skills/blob/020ec10a788f5703108d093a4bd3d9a7c3847d36/references/performance-checklist.md?utm_source=gitcode_repo_files)、[references/accessibility-checklist.md](https://gitcode.com/GitHub_Trending/agentskill/agent-skills/blob/020ec10a788f5703108d093a4bd3d9a7c3847d36/references/accessibility-checklist.md?utm_source=gitcode_repo_files)、[references/definition-of-done.md](https://gitcode.com/GitHub_Trending/agentskill/agent-skills/blob/020ec10a788f5703108d093a4bd3d9a7c3847d36/references/definition-of-done.md?utm_source=gitcode_repo_files) 等。

这是一个包级别（pack-level）的设计选择，规范原文给出了完整的推理链：Agent Skills 规范将技能描述为自包含目录，但本仓库多个技能指向同一份清单，就地放置只有两条路——把清单复制到每个使用它的技能，或指定某个技能"拥有"清单、其他技能跨目录引用。两种方式都会随时间漂移，而根目录的单一副本保持为唯一事实来源。

代价是**可移植性**：整仓安装（如 Claude Code marketplace 插件）会连 `references/` 一起带上，但只复制 `skills/<name>/` 的单技能安装会把这个兄弟目录留在后面，相关链接就解析为空。这个缺口在仓库中被追踪（上游 issue #361）。

由此得出的现行惯例是：**恰好被一个技能使用的材料，作为支撑文件放在该技能目录内；跨技能共享的材料，放根 `references/`。** 仓库实际代码印证了这套引用方式，例如 [skills/security-and-hardening/SKILL.md](https://gitcode.com/GitHub_Trending/agentskill/agent-skills/blob/020ec10a788f5703108d093a4bd3d9a7c3847d36/skills/security-and-hardening/SKILL.md?utm_source=gitcode_repo_files)、[skills/code-review-and-quality/SKILL.md](https://gitcode.com/GitHub_Trending/agentskill/agent-skills/blob/020ec10a788f5703108d093a4bd3d9a7c3847d36/skills/code-review-and-quality/SKILL.md?utm_source=gitcode_repo_files) 都以 `../../references/security-checklist.md` 之类的相对路径指向根清单。

## 上下文效率：技能按需加载的成本模型

技能是**按需加载**的：启动时只有技能名和 description 在上下文中，完整的 SKILL.md 只在智能体判定技能相关时才加载。为了控制这次加载的成本，规范给出五条准则：

- **SKILL.md 控制在 500 行以内**，详细参考资料移入支撑文件；
- **写精确的 description**，帮助智能体在正确时机激活、其余时候跳过；
- **使用渐进式披露（progressive disclosure）**：引用的支撑文件只在工作流推进到对应环节时才被读取；
- **优先用脚本替代内联代码**：执行脚本不消耗上下文，只有它的输出消耗；内联代码块则每次加载都要"付费"；
- **文件引用保持一层深**：从 SKILL.md 直接链接到支撑文件，不要通过中间文档链式跳转。

## 脚本规范：`scripts/` 目录的约定

当技能附带可运行辅助脚本时，每个脚本须遵循以下约定：

- 使用 `#!/bin/bash` shebang；
- 使用 `set -e` 实现快速失败（fail-fast）；
- 状态消息写 stderr：`echo "Message" >&2`；
- 机器可读输出（JSON）写 stdout；
- 为临时文件包含清理 trap；
- 以仓库相对路径 `skills/<skill-name>/scripts/<script>.sh` 引用脚本。

仓库中的 [skills/idea-refine/scripts/idea-refine.sh](https://gitcode.com/GitHub_Trending/agentskill/agent-skills/blob/020ec10a788f5703108d093a4bd3d9a7c3847d36/skills/idea-refine/scripts/idea-refine.sh?utm_source=gitcode_repo_files) 是这条约定的标准样本，全文仅 15 行：

```bash
#!/bin/bash
set -e

# This script helps initialize the ideas directory for the idea-refine skill.

IDEAS_DIR="docs/ideas"

if [ ! -d "$IDEAS_DIR" ]; then
  mkdir -p "$IDEAS_DIR"
  echo "Created directory: $IDEAS_DIR" >&2
else
  echo "Directory already exists: $IDEAS_DIR" >&2
fi

echo "{\"status\": \"ready\", \"directory\": \"$IDEAS_DIR\"}"

可以看到：shebang、set -e、状态消息走 stderr（>&2）、JSON 结果走 stdout——与规范逐条对应。而调用它的方式则呼应了"上下文效率"原则：skills/idea-refine/SKILL.md 中仅以一行 bash skills/idea-refine/scripts/idea-refine.sh 引用，脚本内容本身不占用加载成本。

写作六原则

规范用六句话总结了技能文件的写作哲学，可以视为整套结构的浓缩：

1. 流程优先于知识（Process over knowledge）：技能是工作流，不是参考文档。写步骤，不写事实。
2. 具体优先于笼统（Specific over general）："Run npm test" 胜过 "verify the tests"。
3. 证据优先于假设（Evidence over assumption）：每个验证勾选项都要求证据。
4. 反合理化（Anti-rationalization）：每一个值得跳过的步骤，都必须在 Rationalizations 表里有一条反论。
5. 渐进式披露（Progressive disclosure）：主 SKILL.md 是入口，支撑文件只在需要时加载。
6. Token 敏感（Token-conscious）：每个章节都必须为其存在辩护——如果删掉它不改变智能体行为，就删掉它。

命名约定

• 技能目录：lowercase-hyphen-separated（小写连字符）；
• 技能文件：SKILL.md（恒为大写）；
• 支撑文件：lowercase-hyphen-separated.md；
• 共享引用：存放在根 references/ 目录，不放进技能目录（原因见"共享引用"一节）；
• 技能专属引用：单个支撑文档可以作为松散文件放在技能目录内；当多个相关文档随技能一起分发时，正在形成的惯例是把它们分组到技能目录内部的 references/ 子目录，让技能自带支撑文档——skills/constraint-driven-development/references/floor-guard.md 就是这种组织的现成例子。

跨技能引用：引用而非复制

引用其他技能时用名字直称，标准句式如：

Follow the `test-driven-development` skill for writing tests.
If the build breaks, use the `debugging-and-error-recovery` skill.