skill-writing-best-practices

スキル作成のベストプラクティス

コーディング規約やベストプラクティスをまとめた、効果的な AI エージェントスキルを作成するためのパターンです。構成、内容、文体に関する 6 つのルールが含まれています。

適用するタイミング

以下の場合に、これらのガイドラインを参照してください。

• スキルを一から新規作成するとき
• 既存のコードベースからパターンを抽出するとき
• 既存のスキルをレビューまたは改善するとき
• ドキュメントをスキル形式に変換するとき

ルールの概要

構成（高）

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 には、フロントマター、概要、要約したルールが記載されています。

---
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

各ルールファイルには、フロントマター、解説、例、要点が記載されています。

---
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

1. Takeaway 1
2. Takeaway 2

内容（高）

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/`."

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

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

文体（中）

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.

基本方針

優れたスキルは次のようなものです。

1. 具体的 - すべてのルールにコード例がある
2. 理由が明確 - 何をすべきかだけでなく、その理由も説明している
3. 見つけやすい - 関連するルールをすぐに見つけられる
4. 誠実 - パターンを使うべきでない場合も示している
5. 自然 - AI の出力ではなく、ドキュメントのように書かれている