Back to Details

skill-writing-best-practices

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Skill Writing Best Practices

Skill编写最佳实践

Patterns for creating effective AI agent skills that capture coding conventions and best practices. Contains 6 rules covering structure, content, and writing style.
本文介绍了创建有效AI Agent技能的模式，涵盖编码规范与最佳实践，包含6条涉及结构、内容和写作风格的规则。

When to Apply

适用场景

Reference these guidelines when:
  • Creating a new skill from scratch
  • Extracting patterns from an existing codebase
  • Reviewing or improving existing skills
  • Converting documentation into skill format
在以下场景中可参考本指南：
  • 从零开始创建新技能
  • 从现有代码库中提取模式
  • 审核或优化现有技能
  • 将文档转换为Skill格式

Rules Summary

规则概述

Structure (HIGH)

结构（高优先级）

skill-directory-structure - @rules/skill-directory-structure.md

skill-directory-structure - @rules/skill-directory-structure.md

Every skill has a SKILL.md and a rules/ directory.
skills/
└── topic-best-practices/
    ├── SKILL.md              # Main summary with all rules
    └── rules/
        ├── rule-name.md      # Detailed individual rules
        └── another-rule.md
每个技能都需包含SKILL.md文件和rules/目录。
skills/
└── topic-best-practices/
    ├── SKILL.md              # 包含所有规则的主摘要文件
    └── rules/
        ├── rule-name.md      # 详细的单个规则文件
        └── another-rule.md

skill-md-structure - @rules/skill-md-structure.md

skill-md-structure - @rules/skill-md-structure.md

SKILL.md has frontmatter, overview, and condensed rule summaries.
markdown
---
name: topic-best-practices
description: When to use this skill.
---
SKILL.md需包含前置元数据、概述和精简的规则摘要。
markdown
---
name: topic-best-practices
description: 本技能的适用场景。
---

Topic Best Practices

Topic Best Practices

Brief intro. Contains N rules across M categories.
简短介绍。包含M个类别下的N条规则。

When to Apply

适用场景

  • Situation 1
  • Situation 2
  • 场景1
  • 场景2

Rules Summary

规则概述

Category (IMPACT)

类别（影响级别）

rule-name - @rules/rule-name.md

rule-name - @rules/rule-name.md

One sentence. Code example.
undefined
一句话描述。附代码示例。
undefined

rule-file-structure - @rules/rule-file-structure.md

rule-file-structure - @rules/rule-file-structure.md

Each rule file has frontmatter, explanation, examples, and takeaways.
markdown
---
title: Rule Title
impact: HIGH
tags: [relevant, tags]
---
每个规则文件需包含前置元数据、说明、示例和要点总结。
markdown
---
title: 规则标题
impact: HIGH
tags: [相关标签]
---

Rule Title

规则标题

What to do and why.
说明操作内容及原因。

Why

原因

  • Benefit 1
  • Benefit 2
  • 优势1
  • 优势2

Pattern

模式示例

```ruby
```ruby

Bad

错误示例

bad_code
bad_code

Good

正确示例

good_code ```
good_code ```

Rules

要点总结

  1. Takeaway 1
  2. Takeaway 2
undefined
  1. 要点1
  2. 要点2
undefined

Content (HIGH)

内容（高优先级）

concrete-examples - @rules/concrete-examples.md

concrete-examples - @rules/concrete-examples.md

Every rule needs code examples. Abstract advice is hard to apply.
markdown
undefined
每条规则都需附带代码示例。抽象建议难以落地。
markdown
undefined

Bad: Too abstract

错误示例：过于抽象

"Keep your code organized."
"保持代码条理清晰。"

Good: Concrete

正确示例：具体明确

"Place concerns in 
app/models/model_name/
not 
app/models/concerns/
."
```ruby
"将相关代码放在
app/models/model_name/
目录下，而非
app/models/concerns/
。"
```ruby

Shows exactly what to do

明确展示操作方式

app/models/card/closeable.rb ```
undefined
app/models/card/closeable.rb ```
undefined

explain-why - @rules/explain-why.md

explain-why - @rules/explain-why.md

Don't just show what. Explain why it matters.
markdown
undefined
不仅要说明怎么做，还要解释为什么这么做很重要。
markdown
undefined

Why

原因

  • Testability: Sync method can be tested without job infrastructure
  • Flexibility: Callers choose sync or async based on context
  • Clarity: The 
    _later
    suffix makes async behavior explicit
undefined
  • 可测试性：同步方法无需任务基础设施即可测试
  • 灵活性：调用方可根据上下文选择同步或异步方式
  • 清晰性：
    _later
    后缀明确标识异步行为
undefined

Style (MEDIUM)

风格（中优先级）

writing-style - @rules/writing-style.md

writing-style - @rules/writing-style.md

Write naturally. Avoid AI-isms and excessive formatting.
markdown
undefined
采用自然的写作风格，避免AI腔和过度格式化。
markdown
undefined

Bad

错误示例

Here is an overview of the key points:

以下是核心要点概述：

Good

正确示例

Group related rules by category. Each rule gets a one-sentence description and a short code example.
undefined
按类别分组相关规则。每条规则配一句话描述和简短代码示例。
undefined

Philosophy

设计理念

Good skills are:
  1. Concrete - Every rule has code examples
  2. Reasoned - Explains why, not just what
  3. Scannable - Easy to find relevant rules quickly
  4. Honest - Shows when NOT to use a pattern
  5. Natural - Written like documentation, not AI output
优秀的Skill具备以下特质：
  1. 具体明确 - 每条规则都配有代码示例
  2. 有理有据 - 解释原因而非仅说明操作
  3. 易于浏览 - 可快速找到相关规则
  4. 诚实客观 - 说明模式的不适用场景
  5. 自然流畅 - 撰写风格类似文档，而非AI生成内容