create-skill-file

Claude Agent Skill 作成ガイドライン

高品質な SKILL.md ファイルの作成方法

目次

• クイックスタート
• 基本原則
• ファイル構成のガイドライン
• 命名と説明のガイドライン
• コンテンツ作成ガイド
• 品質チェックリスト

---

クイックスタート

3ステップで Skill を作成

ステップ1：ディレクトリを作成

mkdir -p .claude/skill/your-skill-name
cd .claude/skill/your-skill-name

ステップ2：SKILL.md を作成

---
name: your-skill-name
description: Brief description with trigger keywords and scenarios
---

# Your Skill Title

## When to Use This Skill

- User asks to [specific scenario]
- User mentions "[keyword]"

## How It Works

1. Step 1: [Action]
2. Step 2: [Action]

## Examples

**Input**: User request
**Output**: Expected result

ステップ3：テスト

• 会話で description に含まれるキーワードを使ってトリガーします
• Claude が正しく実行するか確認します
• 結果に基づいて調整します

---

基本原則

1. 簡潔に保つ

Claude が知らない新しい情報だけを追加します。

• ✅ プロジェクト固有のワークフロー
• ✅ 特殊な命名規則や書式要件
• ✅ カスタムツールやスクリプトの使用方法
• ❌ 一般的なプログラミング知識
• ❌ 自明な手順

比較例：

# ❌ 过度详细
1. 创建 Python 文件
2. 导入必要的库
3. 定义函数
4. 编写主程序逻辑

# ✅ 简洁有效
使用 `scripts/api_client.py` 调用内部 API。
请求头必须包含 `X-Internal-Token`(从环境变量 `INTERNAL_API_KEY` 获取)。

2. 適切な自由度を設定する

自由度	適用シーン	記述方法
高	創造性や複数の解決策が必要	指針を示し、具体的な手順は限定しません
中	推奨パターンはあるが、変更も可能	パラメーター化した例とデフォルトの手順を示します
低	間違いやすく、厳密な実行が必要	詳細な手順やスクリプトを示します

判断基準：

• タスクに明確な「正解」はありますか？ → 自由度を低くします
• さまざまな状況への適応が必要ですか？ → 自由度を高くします
• 間違えた場合の代償はどの程度ですか？ → 代償が大きい場合は自由度を低くします

3. 段階的な情報開示

複雑な内容は階層的に整理します。

SKILL.md (主文档, 200-500行)
├── reference.md (详细文档)
├── examples.md (完整示例)
└── scripts/ (可执行脚本)

ルール：

• SKILL.md が 500行を超える場合 → 子ファイルに分割します
• 子ファイルが 100行を超える場合 → 目次を追加します
• 参照の深さは1階層以内にします

---

ファイル構成のガイドライン

YAML Frontmatter

---
name: skill-name-here
description: Clear description of what this skill does and when to activate it
---

フィールドのガイドライン：

フィールド	要件	説明
name	小文字、数字、ハイフンを使用し、64文字以内	ディレクトリ名と一致させる必要があります
description	プレーンテキスト、1024文字以内	検索と有効化に使用します

使用を避ける名前：

• ❌ XML タグ、予約語（anthropic、claude）
• ❌ 曖昧な語句（helper、utility、manager）
• ❌ 空白やアンダースコア（ハイフン - を使用します）

Description のコツ：

# ❌ 过于泛化
description: Helps with code tasks

# ✅ 具体且包含关键词
description: Processes CSV files and generates Excel reports with charts. Use when user asks to convert data formats or create visual reports.

# ✅ 说明触发场景
description: Analyzes Python code for security vulnerabilities using bandit. Activates when user mentions "security audit" or "vulnerability scan".

ディレクトリ構成

基本構成（シンプルな Skill）：

skill-name/
└── SKILL.md

標準構成（推奨）：

skill-name/
├── SKILL.md
├── templates/
│   └── template.md
└── scripts/
    └── script.py

---

命名と説明のガイドライン

Skill の命名

推奨形式：動名詞形式（verb-ing + noun）

✅ 好的命名:
- processing-csv-files
- generating-api-docs
- managing-database-migrations

❌ 不好的命名:
- csv (过于简短)
- data_processor (使用下划线)
- helper (过于模糊)

Description の作成

必ず三人称を使用します：

# ❌ 错误
description: I help you process PDFs

# ✅ 正确
description: Processes PDF documents and extracts structured data

4C 原則：

• Clear（明確）：専門用語や曖昧な語句を避けます
• Concise（簡潔）：中核となる機能を1～2文で説明します
• Contextual（文脈）：適用シーンを説明します
• Complete（完全）：機能とトリガー条件を含めます

---

コンテンツ作成ガイド

「When to Use」セクション

トリガーされる状況を明確に説明します。

## When to Use This Skill

- User asks to analyze Python code for type errors
- User mentions "mypy" or "type checking"
- User is working in a Python project with type hints
- User needs to add type annotations

パターン：

• 直接的な依頼：「User asks to X」
• キーワード：「User mentions 'keyword'」
• 文脈：「User is working with X」
• タスクの種類：「User needs to X」

ワークフローの設計

シンプルな線形フロー：

## How It Works

1. Scan the project for all `.py` files
2. Run `mypy --strict` on each file
3. Parse error output and categorize by severity
4. Generate summary report with fix suggestions

条件分岐フロー：

## Workflow

1. **Check project type**
   - If Django → Use `django-stubs` config
   - If Flask → Use `flask-stubs` config
   - Otherwise → Use default mypy config

2. **Run type checking**
   - If errors found → Proceed to step 3
   - If no errors → Report success and exit

チェックリスト形式（検証タスク）：

## Pre-deployment Checklist

Execute in order. Stop if any step fails.

- [ ] Run tests: `npm test` (must pass)
- [ ] Build: `npm run build` (no errors)
- [ ] Check deps: `npm audit` (no critical vulnerabilities)

例とテンプレート

入力と出力の例：

## Examples

### Example 1: Basic Check

**User Request**: "Check my code for type errors"

**Action**:
1. Scan for `.py` files
2. Run `mypy` on all files

**Output**:
   
   Found 3 type errors in 2 files:
   src/main.py:15: error: Missing return type
   src/utils.py:42: error: Incompatible types
   

スクリプトの統合

スクリプトを使用する場合：

• シンプルなコマンド → SKILL.md に直接記載します
• 複雑なフロー → 独立したスクリプトを用意します

スクリプト作成のガイドライン：

#!/usr/bin/env python3
"""
Brief description of what this script does.

Usage:
    python script.py <arg> [--option value]
"""

import argparse

DEFAULT_VALUE = 80  # Use constants, not magic numbers

def main():
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("directory", help="Directory to process")
    parser.add_argument("--threshold", type=int, default=DEFAULT_VALUE)

    args = parser.parse_args()

    # Validate inputs
    if not Path(args.directory).is_dir():
        print(f"Error: {args.directory} not found")
        return 1

    # Execute
    result = process(args.directory, args.threshold)

    # Report
    print(f"Processed {result['count']} files")
    return 0

if __name__ == "__main__":
    exit(main())

重要なガイドライン：

• ✅ Shebang 行と docstring
• ✅ 型注釈と定数
• ✅ パラメーターの検証とエラー処理
• ✅ 明確な戻り値（0=成功、1=失敗）

ベストプラクティス

推奨事項：

• ✅ 実行可能なコマンドとスクリプトを提供します
• ✅ 入力と出力の例を含めます
• ✅ 検証基準と成功条件を説明します
• ✅ Do/Don't リストを含めます

避けること：

• ❌ Claude が知っている一般的な知識を含める
• ❌ 具体的な手順ではなく、抽象的な説明を使う
• ❌ エラー処理の指針を省く
• ❌ 例に実際のコードではなく擬似コードを使う

---

品質チェックリスト

基本品質

• name が命名規則に準拠している（小文字、ハイフン、64文字以内）
• description にトリガーキーワードとシーンが含まれている（1024文字以内）
• 名前がディレクトリ名と一致している
• Claude が知らない情報だけを含んでいる
• 冗長または重複した内容がない

機能の完全性

• 「When to Use」セクションがあり、3～5個のトリガーシーンを挙げている
• 明確な実行フローまたは手順がある
• 完全な例が少なくとも2～3個ある
• 入力と期待される出力が含まれている
• エラー処理の指針がある

構成のガイドライン

• セクションが明確に整理されている
• 200行を超える場合、目次ナビゲーションがある
• 参照階層が1階層以内である
• すべてのパスでスラッシュ / を使用している
• 用語が統一されている

スクリプトとテンプレート

• スクリプトに使用方法とパラメーターの説明が含まれている
• スクリプトにエラー処理がある
• マジックナンバーを避け、設定を使用している
• テンプレートの形式が明確で使いやすい

最終チェック

• 全文を読み直し、流暢で読みやすいことを確認する
• 実際のシーンでトリガーをテストする
• 適切な長さである（200～500行、または分割済み）

---

よくある質問

Q: Skill の適切な長さはどのくらいですか？

• 最小：50～100行
• 理想：200～500行
• 最大：500行（超える場合は分割します）

Q: Skill を有効化しやすくするにはどうすればよいですか？

• description にユーザーが使いそうなキーワードを含めます
• 具体的なシーンを説明します（「when user asks to X」）
• 関連するツール名に言及します

Q: 複数の Skill の機能が重複する場合はどうすればよいですか？

• より具体的な description を使って区別します
• 「When to Use」で関連性を説明します
• 1つの Skill に統合することを検討します

Q: Skill のメンテナンスは必要ですか？

• 四半期に1回見直し、古くなった情報を更新します
• 使用時のフィードバックに基づいて改善します
• ツールや API の変更時には速やかに更新します

---

クイックリファレンス

Frontmatter テンプレート

---
name: skill-name
description: Brief description with trigger keywords
---

基本構成テンプレート

# Skill Title

## When to Use This Skill
- Scenario 1
- Scenario 2

## How It Works
1. Step 1
2. Step 2

## Examples
### Example 1
...

## References
- [Link](url)

---

関連リソース

• Claude Agent Skills 公式ドキュメント
• ベストプラクティスのチェックリスト
• テンプレートファイル - すぐに使えるテンプレート
  • 基本 Skill のテンプレート
  • ワークフロー Skill のテンプレート
• サンプル集 - Skill の完成例
  • 優れた例
  • よくある間違いの例

---