skill-writing-best-practices

用途

skill-writing-best-practices 是一套用于创建有效 AI 智能体技能（agent skills）的模式与最佳实践，目标是把编码约定和最佳实践固化到技能文件中。它包含 6 条规则，覆盖结构、内容和写作风格三个方面。

适用时机：

从零创建新技能
从现有代码库中提取模式
审查或改进已有技能
把文档转换为技能格式

主要能力

该指南把规则按影响等级分为三类：

结构（Structure，HIGH）

skill-directory-structure（@rules/skill-directory-structure.md）：每个技能都有一个 SKILL.md 和一个 rules/ 目录。示例结构：

skills/
└── topic-best-practices/
    ├── SKILL.md              # Main summary with all rules
    └── rules/
        ├── rule-name.md      # Detailed individual rules
        └── another-rule.md

skill-md-structure（@rules/skill-md-structure.md）：SKILL.md 包含 frontmatter、概述和精简的规则摘要。示例：

---
name: topic-best-practices
description: When to use this skill.
---

# Topic Best Practices

Brief intro. Contains N rules across M categories.

## When to Apply

- Situation 1
- Situation 2

## Rules Summary

### Category (IMPACT)

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

One sentence. Code example.

rule-file-structure（@rules/rule-file-structure.md）：每个规则文件包含 frontmatter、解释、示例和要点。示例：

---
title: Rule Title
impact: HIGH
tags: [relevant, tags]
---

# Rule Title

What to do and why.

## Why

- Benefit 1
- Benefit 2

## Pattern

```ruby
# Bad
bad_code

# Good
good_code

Rules

Takeaway 1
Takeaway 2


**内容（Content，HIGH）**

4. concrete-examples（@rules/concrete-examples.md）：每条规则都需要代码示例，抽象建议难以落地。

Bad: Too abstract

"Keep your code organized."

Good: Concrete

"Place concerns in app/models/model_name/ not app/models/concerns/."

# Shows exactly what to do
app/models/card/closeable.rb


5. explain-why（@rules/explain-why.md）：不要只展示做什么，要解释为什么重要。示例：

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


**风格（Style，MEDIUM）**

6. writing-style（@rules/writing-style.md）：自然写作，避免 AI 腔和过度格式化。

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.


## 使用方式

按上述结构组织技能目录：根目录放置 SKILL.md 作为主摘要并罗列全部规则，rules/ 目录下按规则拆分文件，每条规则通过 @rules/文件名.md 引用。SKILL.md 用于快速浏览和定位规则，规则文件用于承载详细解释与代码示例。

## 核心理念

好的技能应当是：

- 具体（Concrete）：每条规则都有代码示例
- 有理由（Reasoned）：解释为什么，而不只是做什么
- 易浏览（Scannable）：能快速找到相关规则
- 诚实（Honest）：展示何时不应使用某个模式
- 自然（Natural）：写得像文档，而不是 AI 输出

## 限制

当前资料未提供该技能的收费、价格、平台或效果等信息，暂未提供。