skill-authoring

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill Authoring Guide

技能创作指南

Overview

概述

Writing effective Claude Code skills requires Test-Driven Development (TDD) and persuasion principles from compliance research. We treat skill writing as process documentation that needs empirical validation rather than just theoretical instruction. Skills are behavioral interventions designed to change model behavior in measurable ways.

By using TDD, we ensure skills address actual failure modes identified through testing. Optimized descriptions improve discovery, while a modular structure supports progressive disclosure to manage token usage. This framework also includes anti-rationalization patterns to prevent the assistant from bypassing requirements.

编写高效的Claude Code技能需要结合测试驱动开发（TDD）与合规研究中的说服原则。我们将技能撰写视为需要实证验证的流程文档，而非单纯的理论指导。技能是旨在以可衡量方式改变模型行为的行为干预手段。

通过使用TDD，我们确保技能能够解决测试中发现的实际失效模式。经过优化的描述可提升技能的可发现性，而模块化结构支持渐进式披露，以管理Token使用量。该框架还包含反合理化模式，防止助手绕过要求。

The Iron Law

铁律

NO SKILL WITHOUT A FAILING TEST FIRST

Every skill must begin with documented evidence of Claude failing without it. This validates that you are solving a real problem. No implementation should proceed without a failing test, and no completion claim should be accepted without evidence. Detailed enforcement patterns for adversarial verification and coverage gates are available in

imbue:proof-of-work

无失败测试，不写技能

每项技能都必须以Claude在无该技能时失效的书面证据作为开端。这能验证你正在解决一个真实问题。在没有失败测试的情况下，不得进行任何实现工作；没有相关证据，不得接受完成声明。关于对抗性验证和覆盖门限的详细实施模式，请参考

imbue:proof-of-work

。

Skill Types

技能类型

We categorize skills into three types: Technique skills for specific methods, Pattern skills for recurring solutions, and Reference skills for quick lookups and checklists. This helps organize interventions into the most effective format for the task.

我们将技能分为三类：技巧类技能针对特定方法，模式类技能针对重复出现的场景解决方案，参考类技能用于快速查询和检查清单。这有助于将干预措施组织成最适合任务的格式。

Quick Start

快速入门

Skill Analysis

技能分析

```bash

Analyze skill complexity

分析技能复杂度

python scripts/analyze.py

Estimate tokens

估算Token数量

python scripts/tokens.py ```

Validation

验证

```bash

Validate skill structure

验证技能结构

python scripts/abstract_validator.py --check ```

Verification: Run analysis and review token estimates before proceeding.

python scripts/abstract_validator.py --check ```

验证步骤：在继续之前，先运行分析并查看Token估算结果。

Description Optimization

描述优化

Skill descriptions must be optimized for semantic search and explicit triggering. Follow the formula

[What it does] + [When to use it] + [Key triggers]

. Use a third-person voice (e.g., "Guides...", "Provides...") and include specific, concrete use cases. Avoid marketing language or vague phrases like "helps with coding."

技能描述必须针对语义搜索和显式触发进行优化。请遵循公式：

[功能说明] + [适用场景] + [关键触发词]

。使用第三人称语态（例如："指导……"、"提供……"），并包含具体的实际用例。避免使用营销话术或模糊表述，如"辅助编码"。

Skill Character Budget (Claude Code 2.1.32+)

技能字符预算（Claude Code 2.1.32及以上版本）

Skill description character budgets now scale with context window at 2% of available context. This means:

Context Window	Description Budget
200K (standard)	~4,000 characters
1M (Opus 4.6 beta)	~20,000 characters

Previously constrained skills can use more descriptive text on larger windows. However, keep descriptions concise regardless — longer is not better. The scaling primarily prevents truncation for skills with legitimately complex trigger conditions, not as an invitation to add verbose content.

技能描述的字符预算现在随上下文窗口缩放，为可用上下文的2%。具体如下：

上下文窗口	描述预算
200K（标准版）	~4,000字符
1M（Opus 4.6测试版）	~20,000字符

之前受限制的技能在更大的窗口中可以使用更具描述性的文本。但无论如何，请保持描述简洁——更长并不意味着更好。缩放主要是为了防止具有合理复杂触发条件的技能被截断，而非鼓励添加冗长内容。

Plugin Name Auto-Display (Claude Code 2.1.33+)

插件名称自动显示（Claude Code 2.1.33及以上版本）

Plugin names are now automatically shown alongside skill descriptions in the

/skills

menu. Do not repeat the plugin name in skill descriptions — it is redundant and wastes character budget. Focus descriptions on what the skill does and when to use it.

现在，插件名称会自动与技能描述一起显示在

/skills

菜单中。请勿在技能描述中重复插件名称——这属于冗余内容，会浪费字符预算。请将描述重点放在技能功能和适用场景上。

The TDD Cycle for Skills

技能的TDD周期

RED Phase: Document Baseline Failures

RED阶段：记录基线失效情况

Establish empirical evidence that an intervention is needed. Create at least three pressure scenarios that combine time pressure and ambiguity. Run these in a fresh instance without the skill active and document the exact failures, such as skipped error handling or missing validation.

建立需要进行干预的实证证据。创建至少三个结合时间压力和模糊性的压力场景。在未激活技能的全新实例中运行这些场景，并记录确切的失效情况，例如跳过错误处理或缺少验证。

GREEN Phase: Minimal Skill Implementation

GREEN阶段：最小化技能实现

Create the smallest intervention that addresses the documented failures. Write the

SKILL.md

with required frontmatter and content that directly counters the baseline failures. Include one example of correct behavior and verify that the same pressure scenarios now show measurable improvement.

创建能够解决已记录失效情况的最小干预措施。编写包含必要前置内容的

SKILL.md

，其内容需直接应对基线失效情况。包含一个正确行为的示例，并验证相同的压力场景现在是否显示出可衡量的改进。

REFACTOR Phase: Anti-Rationalization

REFACTOR阶段：反合理化

Eliminate the ability for Claude to explain away requirements. Run pressure scenarios with the skill active to identify common rationalizations, such as claiming a task is "too simple" for the full process. Add explicit counters, such as exception tables and red flag lists, until rationalizations stop.

消除Claude为绕过要求找借口的能力。在激活技能的情况下运行压力场景，找出常见的合理化借口，例如声称任务"太简单"无需完整流程。添加明确的应对措施，如异常表和红标列表，直到合理化借口不再出现。

Anti-Rationalization

反合理化

Skills must explicitly counter patterns where Claude attempts to bypass requirements. Common excuses include claiming a task is "too simple" or that a "spirit vs letter of the law" approach is sufficient. Skills should include red flag lists for self-checking, such as "Stop if you think: this is too simple for the full process." When exceptions are necessary, document them explicitly to prevent unauthorized shortcuts.

技能必须明确应对Claude试图绕过要求的模式。常见的借口包括声称任务"太简单"，或认为"遵循法律精神而非字面意思"就足够。技能应包含用于自我检查的红标列表，例如："如果你认为：这个任务太简单无需完整流程，请停止。"当确实需要例外情况时，请明确记录，以防止未经授权的捷径。

Module References

模块参考

For detailed implementation guidance:

TDD Methodology: See
```
modules/tdd-methodology.md
```
for RED-GREEN-REFACTOR cycle details
Persuasion Principles: See
```
modules/persuasion-principles.md
```
for compliance research and techniques
Description Writing: See
```
modules/description-writing.md
```
for discovery optimization
Progressive Disclosure: See
```
modules/progressive-disclosure.md
```
for file structure patterns
Anti-Rationalization: See
```
modules/anti-rationalization.md
```
for bulletproofing techniques
Graphviz Conventions: See
```
modules/graphviz-conventions.md
```
for process diagram standards
Testing with Subagents: See
```
abstract:subagent-testing
```
skill for pressure testing methodology
Deployment Checklist: See
```
modules/deployment-checklist.md
```
for final validation

如需详细的实施指导：

TDD方法论：请参阅
```
modules/tdd-methodology.md
```
了解RED-GREEN-REFACTOR周期的详细信息
说服原则：请参阅
```
modules/persuasion-principles.md
```
了解合规研究与相关技巧
描述撰写：请参阅
```
modules/description-writing.md
```
了解可发现性优化方法
渐进式披露：请参阅
```
modules/progressive-disclosure.md
```
了解文件结构模式
反合理化：请参阅
```
modules/anti-rationalization.md
```
了解加固技巧
Graphviz规范：请参阅
```
modules/graphviz-conventions.md
```
了解流程图标准
子代理测试：请使用
```
abstract:subagent-testing
```
技能了解压力测试方法论
部署检查清单：请参阅
```
modules/deployment-checklist.md
```
了解最终验证步骤

Deployment and Quality Gates

部署与质量门限

Before deploying, verify that the RED, GREEN, and REFACTOR phases are complete and documented. Frontmatter must be valid, descriptions optimized, and line counts kept under 500 lines. Ensure all module references are valid and at least one concrete example is included.

在部署前，请验证RED、GREEN和REFACTOR阶段已完成并记录在案。前置内容必须有效，描述已优化，行数控制在500行以内。确保所有模块引用有效，且至少包含一个具体示例。

Scribe Validation

Scribe验证

All markdown files must pass scribe validation. This includes a slop scan to ensure a score under 2.5 and doc verification to confirm all file paths and command examples work. Bullet-to-prose ratios must remain under 60% to maintain readability. Use

Skill(scribe:slop-detector)

and

Skill(scribe:doc-verify)

for these checks.

所有Markdown文件必须通过Scribe验证。这包括进行冗余扫描以确保得分低于2.5，并进行文档验证以确认所有文件路径和命令示例均可正常工作。项目符号与正文的比例必须保持在60%以下，以保证可读性。请使用

Skill(scribe:slop-detector)

和

Skill(scribe:doc-verify)

进行这些检查。

Integration and Best Practices

集成与最佳实践

Individual skills are created using

skill-authoring

, while

modular-skills

handles the architecture of larger structures.

skills-eval

provides ongoing quality assessment. Avoid the common pitfall of writing skills based on theoretical behavior; always use documented failures to guide development. Use progressive disclosure to prevent monolithic files and ensure that each intervention remains focused and token-efficient.

单个技能使用

skill-authoring

创建，而

modular-skills

负责处理大型结构的架构。

skills-eval

提供持续的质量评估。避免基于理论行为编写技能的常见误区；始终以已记录的失效情况为指导进行开发。使用渐进式披露避免出现庞大的单体文件，并确保每个干预措施保持聚焦且Token使用高效。

Troubleshooting

故障排除

Common Issues

常见问题

Skill not loading Check YAML frontmatter syntax and required fields

Token limits exceeded Use progressive disclosure - move details to modules

Modules not found Verify module paths in SKILL.md are correct

技能无法加载 检查YAML前置内容的语法和必填字段

超出Token限制 使用渐进式披露——将详细内容移至模块中

模块未找到 验证SKILL.md中的模块路径是否正确