AgentSkillsCN

creating-skills

为 Claude Agent Skills 的创建与优化提供辅助工具。遵循最佳实践，指导 SKILL.md 的结构化编写、分阶段的信息披露、测试与迭代改进。当需要新建技能或优化现有技能时，可随时使用此工具。

SKILL.md
--- frontmatter
name: creating-skills
description: Claude Agent Skillsを作成・改善するための支援ツール。ベストプラクティスに従ったSKILL.mdの構造化、段階的情報開示、テスト、反復改善をガイド。skillの新規作成や既存skillの改善が必要な時に使用。

Claude Agent Skills作成ガイド

このskillは、効果的なClaude Agent Skillsを作成・改善するためのガイドです。

コア原則

1. 簡潔さが鍵

コンテキストウィンドウは公共財です。以下を常に自問してください:

  • •「Claudeは本当にこの説明が必要か?」
  • •「Claudeがすでに知っていることを仮定できるか?」
  • •「この段落はトークンコストに見合うか?」

デフォルトの前提: Claudeはすでに非常に賢い。Claudeが持っていないコンテキストのみを追加してください。

2. 適切な自由度の設定

タスクの脆弱性と変動性に応じて、指示の具体性を調整します:

  • •高い自由度 (テキストベースの指示): 複数のアプローチが有効な場合
  • •中程度の自由度 (疑似コードやパラメータ付きスクリプト): 推奨パターンがあるが、多少の変更が許容される場合
  • •低い自由度 (具体的なスクリプト): 操作が脆弱でエラーが発生しやすい場合

3. すべての対象モデルでテスト

  • •Claude Haiku: 十分なガイダンスがあるか?
  • •Claude Sonnet: 明確で効率的か?
  • •Claude Opus: 過剰説明を避けているか?

Skill作成ワークフロー

このチェックリストをコピーして進捗を追跡してください:

code
Skill作成進捗:
- [ ] ステップ1: 目的とトリガーを特定
- [ ] ステップ2: YAMLフロントマターを作成
- [ ] ステップ3: 本文の構造を設計
- [ ] ステップ4: 内容を作成
- [ ] ステップ5: 段階的情報開示を適用
- [ ] ステップ6: テストと反復改善

ステップ1: 目的とトリガーを特定

実行内容:

  • •Skillが解決する具体的な問題を明確にする
  • •どのような状況で使用されるかを特定
  • •再利用可能なパターンを認識

質問リスト:

  • •このSkillは何をするのか?
  • •ユーザーがどのような言葉を使う時にこのSkillを使うべきか?
  • •このSkillはどのような価値を提供するか?

ステップ2: YAMLフロントマターを作成

必須フィールド:

yaml
---
name: skill-name-here
description: Skillの機能説明とトリガーキーワード。使用すべき状況を明記。
---

命名規則 (gerund形を推奨):

  • •✓ 良い例: processing-pdfs, analyzing-spreadsheets, testing-code
  • •✗ 避ける例: helper, utils, tools, pdf, data

name要件:

  • •最大64文字
  • •小文字、数字、ハイフンのみ
  • •XMLタグ不可
  • •予約語不可 ("anthropic", "claude")

description要件:

  • •最大1024文字
  • •空欄不可
  • •XMLタグ不可
  • •必ず三人称で記述 ("このSkillは〜を処理する")
  • •具体的なトリガーキーワードを含める

効果的なdescription例:

yaml
description: PDFファイルからテキストとテーブルを抽出、フォーム入力、文書結合を実行。PDF、フォーム、文書抽出について言及された時に使用。
yaml
description: Excelスプレッドシートを分析、ピボットテーブル作成、グラフ生成。Excel、スプレッドシート、表形式データ、.xlsxファイルの分析時に使用。

ステップ3: 本文の構造を設計

基本構造テンプレート:

markdown
# [Skill名]

## クイックスタート

[最も一般的なユースケースの簡潔な例]

```python
# 具体的なコード例
```

## 主要機能

**機能A**: 簡潔な説明
**機能B**: 簡潔な説明
**機能C**: より詳しい情報は [REFERENCE.md](REFERENCE.md) を参照

## ワークフロー

複雑なタスクの場合、ステップバイステップのワークフローを提供:

1. ステップ1の説明
2. ステップ2の説明
3. 検証とフィードバックループ

ステップ4: 内容を作成

テンプレートパターン を使用:

markdown
## 出力形式

必ずこのテンプレート構造を使用してください:

```markdown
# [タイトル]

## サマリー
[概要]

## 主要な発見
- 発見1
- 発見2

## 推奨事項
1. 具体的な推奨事項
```

例示パターン を使用:

markdown
## コミットメッセージフォーマット

以下の例に従ってコミットメッセージを生成:

**例1:**
入力: JWTトークンを使用したユーザー認証を追加
出力:
```
feat(auth): JWT認証を実装

ログインエンドポイントとトークン検証ミドルウェアを追加
```

**例2:**
入力: レポートで日付が正しく表示されないバグを修正
出力:
```
fix(reports): タイムゾーン変換の日付フォーマットを修正

レポート生成全体でUTCタイムスタンプを一貫して使用
```

条件付きワークフローパターン を使用:

markdown
## ドキュメント変更ワークフロー

1. 変更タイプを決定:

   **新規コンテンツ作成?** → 下記の「作成ワークフロー」に従う
   **既存コンテンツ編集?** → 下記の「編集ワークフロー」に従う

2. 作成ワークフロー:
   - ライブラリを使用
   - ゼロから構築

3. 編集ワークフロー:
   - 既存ドキュメントを展開
   - 直接変更
   - 変更後に検証

ステップ5: 段階的情報開示を適用

SKILL.mdは500行以内 に保つのが最適です。これを超える場合、以下のパターンで分割:

パターン1: 参照ファイルによる高レベルガイド:

markdown
## 高度な機能

**フォーム入力**: 完全なガイドは [FORMS.md](FORMS.md) を参照
**APIリファレンス**: 全メソッドは [REFERENCE.md](REFERENCE.md) を参照
**例**: 一般的なパターンは [EXAMPLES.md](EXAMPLES.md) を参照

パターン2: ドメイン別の整理:

code
skill-directory/
├── SKILL.md (概要とナビゲーション)
└── reference/
    ├── domain-a.md
    ├── domain-b.md
    └── domain-c.md

重要: 参照は1レベルの深さに保つ（深くネストしない）

長い参照ファイルには目次を含める (100行以上):

markdown
# APIリファレンス

## 目次
- 認証とセットアップ
- コアメソッド (作成、読取、更新、削除)
- 高度な機能 (バッチ操作、webhook)
- エラーハンドリングパターン
- コード例

## 認証とセットアップ
...

ステップ6: テストと反復改善

評価駆動開発:

  1. •ギャップを特定: Skillなしで代表的なタスクを実行し、失敗や不足を記録
  2. •評価を作成: これらのギャップをテストする3つのシナリオを構築
  3. •ベースラインを確立: Skillなしでのパフォーマンスを測定
  4. •最小限の指示を作成: ギャップに対処し評価に合格するのに十分な内容のみ
  5. •反復: 評価を実行し、ベースラインと比較して改善

Claudeとの反復開発:

  1. •Skillなしでタスクを完了し、提供したコンテキストを観察
  2. •再利用可能なパターンを特定
  3. •Claude Aに「このパターンを捉えたSkillを作成して」と依頼
  4. •簡潔さをレビュー（不要な説明を削除）
  5. •情報アーキテクチャを改善
  6. •別のClaudeインスタンス（Claude B）で類似タスクでテスト
  7. •観察に基づいて反復

アンチパターン（避けるべきこと）

Windowsスタイルのパスを避ける

常にフォワードスラッシュを使用:

  • •✓ 良い: scripts/helper.py, reference/guide.md
  • •✗ 避ける: scripts\helper.py, reference\guide.md

選択肢を多く提示しすぎない

markdown
✗ 悪い例（混乱を招く）:
「pypdf、pdfplumber、PyMuPDF、pdf2image、またはその他を使用できます...」

✓ 良い例（デフォルトと脱出ハッチを提供）:
「テキスト抽出にはpdfplumberを使用:
```python
import pdfplumber
```

OCRが必要なスキャンPDFの場合は、pdf2imageとpytesseractを使用。」

時間に依存する情報を避ける

markdown
✗ 悪い例:
「2025年8月以前の場合は古いAPIを使用。2025年8月以降は新しいAPIを使用。」

✓ 良い例:
## 現在の方法

v2 APIエンドポイントを使用: `api.example.com/v2/messages`

## 古いパターン

<details>
<summary>レガシーv1 API（2025-08非推奨）</summary>

v1 APIは使用: `api.example.com/v1/messages`

このエンドポイントはサポートされていません。
</details>

用語の一貫性を保つ

  • •✓ 良い: 常に「APIエンドポイント」、常に「フィールド」、常に「抽出」
  • •✗ 悪い: 「APIエンドポイント」「URL」「APIルート」「パス」を混在

チェックリスト

Skillを共有する前に確認:

コア品質

  • • descriptionが具体的でキーワードを含む
  • • descriptionにSkillの機能と使用タイミングの両方を記載
  • • SKILL.md本文が500行以内
  • • 追加の詳細は別ファイル（必要に応じて）
  • • 時間依存情報なし（または「古いパターン」セクションに記載）
  • • 全体で一貫した用語
  • • 例が具体的
  • • ファイル参照が1レベルの深さ
  • • 段階的情報開示を適切に使用
  • • ワークフローに明確なステップがある

コードとスクリプト（該当する場合）

  • • スクリプトがClaudeに丸投げせず問題を解決
  • • エラーハンドリングが明示的で有用
  • • 「魔法の定数」なし（すべての値が正当化されている）
  • • 必要なパッケージを指示に記載し、利用可能性を確認
  • • スクリプトに明確なドキュメント
  • • Windowsスタイルのパスなし（すべてフォワードスラッシュ）
  • • 重要な操作の検証/確認ステップ
  • • 品質重視タスクのフィードバックループ

テスト

  • • 少なくとも3つの評価を作成
  • • Haiku、Sonnet、Opusでテスト
  • • 実際の使用シナリオでテスト
  • • チームのフィードバックを組み込む（該当する場合）

参照リソース

詳細なベストプラクティス: BEST_PRACTICES.md テンプレート集: TEMPLATES.md 例示サンプル: EXAMPLES.md