skill-writer

Skill Writer

この Skill は、ベストプラクティスと検証要件に準拠した、構成の整った Claude Code 向け Agent Skills の作成を支援します。

この Skill を使用するタイミング

次の場合にこの Skill を使用してください：

• 新しい Agent Skill を作成するとき
• SKILL.md ファイルを作成または更新するとき
• Skill の構造とフロントマターを設計するとき
• Skill が見つからない問題をトラブルシューティングするとき
• 既存のプロンプトやワークフローを Skills に変換するとき

手順

ステップ 1：Skill の範囲を決める

まず、Skill にどのような機能を持たせるかを把握します。

1. 確認の質問をします：

   • この Skill が提供すべき具体的な機能は何ですか？
   • Claude はどのようなときにこの Skill を使用しますか？
   • どのようなツールやリソースが必要ですか？
   • 個人利用向けですか、それともチームで共有しますか？

2. 対象を絞ります：1 つの Skill につき 1 つの機能にします

   • 適切：「PDF フォームへの入力」、「Excel データ分析」
   • 広すぎる：「ドキュメント処理」、「データツール」

ステップ 2：Skill の保存場所を選ぶ

Skill の作成場所を決めます。

個人用 Skills（~/.claude/skills/）：

• 個人のワークフローや設定
• 実験的な Skills
• 個人の生産性向上ツール

プロジェクト用 Skills（.agents/skills/。Claude Code では .claude/skills がここにリンクされます）：

• チームのワークフローや規約
• プロジェクト固有の専門知識
• 共有ユーティリティ（git にコミット）

ステップ 3：Skill の構造を作成する

ディレクトリとファイルを作成します。

# Personal
mkdir -p ~/.claude/skills/skill-name

# Project
mkdir -p .agents/skills/skill-name

複数ファイルで構成する Skills の場合：

skill-name/
├── SKILL.md (required)
├── reference.md (optional)
├── examples.md (optional)
├── scripts/
│   └── helper.py (optional)
└── templates/
    └── template.txt (optional)

ステップ 4：SKILL.md のフロントマターを記述する

必須フィールドを含む YAML フロントマターを作成します。

---
name: skill-name
description: Brief description of what this does and when to use it
---

フィールドの要件：

• name：

  • 小文字、数字、ハイフンのみを使用
  • 最大 64 文字
  • ディレクトリ名と一致していること
  • 適切な例：pdf-processor、git-commit-helper
  • 不適切な例：PDF_Processor、Git Commits!

• description：

  • 最大 1024 文字
  • 機能と使用するタイミングの両方を含めること
  • ユーザーが実際に使う、具体的なトリガーとなる語句を使用
  • ファイルの種類、操作、コンテキストに言及すること

任意のフロントマターフィールド：

• allowed-tools：ツールへのアクセスを制限します（カンマ区切りのリスト）

  allowed-tools: Read, Grep, Glob
  

  次の場合に使用します：
  • 読み取り専用の Skills
  • セキュリティに配慮が必要なワークフロー
  • 範囲を限定した操作

ステップ 5：効果的な説明を記述する

説明は、Claude が Skill を見つけるうえで重要です。

形式：[機能] + [使用するタイミング] + [主なトリガー]

例：

✅ 適切：

description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.

✅ 適切：

description: Analyze Excel spreadsheets, create pivot tables, and generate charts. Use when working with Excel files, spreadsheets, or analyzing tabular data in .xlsx format.

❌ 曖昧すぎる：

description: Helps with documents
description: For data analysis

ヒント：

• 具体的なファイル拡張子（.pdf、.xlsx、.json）を含める
• よく使われるユーザーの表現（「分析」、「抽出」、「生成」など）に言及する
• 汎用的な動詞ではなく、具体的な操作を列挙する
• 「次の場合に使用」、「〜向け」など、状況を示す手がかりを加える

ステップ 6：Skill の内容を構成する

わかりやすい Markdown セクションを使用します。

# Skill Name

Brief overview of what this Skill does.

## Quick start

Provide a simple example to get started immediately.

## Instructions

Step-by-step guidance for Claude:
1. First step with clear action
2. Second step with expected outcome
3. Handle edge cases

## Examples

Show concrete usage examples with code or commands.

## Best practices

- Key conventions to follow
- Common pitfalls to avoid
- When to use vs. not use

## Requirements

List any dependencies or prerequisites:
```bash
pip install package-name

高度な使い方

複雑な状況については、reference.md を参照してください。

### Step 7: Add supporting files (optional)

Create additional files for progressive disclosure:

**reference.md**: Detailed API docs, advanced options
**examples.md**: Extended examples and use cases
**scripts/**: Helper scripts and utilities
**templates/**: File templates or boilerplate

Reference them from SKILL.md:
```markdown
For advanced usage, see [reference.md](reference.md).

Run the helper script:
\`\`\`bash
python scripts/helper.py input.txt
\`\`\`

ステップ 8：Skill を検証する

次の要件を確認します。

✅ ファイル構造：

• SKILL.md が正しい場所にある
• ディレクトリ名がフロントマターの name と一致している

✅ YAML フロントマター：

• 1 行目が開始区切りの ---
• コンテンツの前に終了区切りの --- がある
• 有効な YAML である（タブを使用せず、インデントが正しい）
• name が命名規則に従っている
• description が具体的で、1024 文字未満である

✅ コンテンツの品質：

• Claude 向けの指示が明確である
• 具体例が示されている
• エッジケースに対応している
• 依存関係が記載されている（該当する場合）

✅ テスト：

• 説明がユーザーの質問に合致している
• 関連する質問で Skill が有効になる
• 指示が明確で、実行可能である

ステップ 9：Skill をテストする

1. Skill を読み込むため、Claude Code を（起動中の場合は）再起動します

2. 説明に合致する、関連性の高い質問をします：

   Can you help me extract text from this PDF?
   

3. 有効化を確認する：Claude が自動的に Skill を使用することを確認します

4. 動作を確認する：Claude が指示に正しく従うことを確認します

ステップ 10：必要に応じてデバッグする

Claude が Skill を使用しない場合：

1. 説明をより具体的にする：

   • トリガーとなる語句を追加する
   • ファイル形式を含める
   • ユーザーがよく使う表現に言及する

2. ファイルの場所を確認する：

   ls ~/.claude/skills/skill-name/SKILL.md
   ls .agents/skills/skill-name/SKILL.md
   

3. YAML を検証する：

   cat SKILL.md | head -n 10
   

4. デバッグモードを実行する：

   claude --debug
   

よくあるパターン

読み取り専用の Skill

---
name: code-reader
description: Read and analyze code without making changes. Use for code review, understanding codebases, or documentation.
allowed-tools: Read, Grep, Glob
---

スクリプトベースの Skill

---
name: data-processor
description: Process CSV and JSON data files with Python scripts. Use when analyzing data files or transforming datasets.
---

# Data Processor

## Instructions

1. Use the processing script:
\`\`\`bash
python scripts/process.py input.csv --output results.json
\`\`\`

2. Validate output with:
\`\`\`bash
python scripts/validate.py results.json
\`\`\`

段階的開示を用いた複数ファイルの Skill

---
name: api-designer
description: Design REST APIs following best practices. Use when creating API endpoints, designing routes, or planning API architecture.
---

# API Designer

Quick start: See [examples.md](examples.md)

Detailed reference: See [reference.md](reference.md)

## Instructions

1. Gather requirements
2. Design endpoints (see examples.md)
3. Document with OpenAPI spec
4. Review against best practices (see reference.md)

Skill 作成者向けのベストプラクティス

1. 1 つの Skill に 1 つの目的を持たせる：巨大な Skill を作成しない
2. 具体的な説明にする：ユーザーが使うトリガーとなる語句を含める
3. 明確な指示を書く：人間ではなく Claude 向けに書く
4. 具体例を示す：擬似コードではなく実際のコードを示す
5. 依存関係を列挙する：必要なパッケージを説明に記載する
6. チームメイトとテストする：有効化と明確さを確認する
7. Skill をバージョン管理する：内容の変更を記録する
8. 段階的開示を利用する：高度な詳細は別ファイルに記載する

検証チェックリスト

Skill を完成させる前に、次の項目を確認してください：

• 名前が小文字で、ハイフンのみを使用し、64 文字以内である
• 説明が具体的で、1024 文字未満である
• 説明に「何を」と「いつ」が含まれている
• YAML フロントマターが有効である
• 指示が手順ごとに記載されている
• 例が具体的で現実的である
• 依存関係が記載されている
• ファイルパスにスラッシュを使用している
• 関連するクエリで Skill が有効になる
• Claude が指示に正しく従う

トラブルシューティング

Skill が有効にならない：

• トリガーとなる語句を使って説明をより具体的にする
• ファイル形式と操作を説明に含める
• ユーザーの表現を含む「次の場合に使用する」節を追加する

複数の Skill が競合する：

• 説明をより明確に区別する
• 異なるトリガーとなる語句を使う
• 各 Skill の対象範囲を狭める

Skill にエラーがある：

• YAML の構文を確認する（タブを使わず、適切にインデントする）
• ファイルパスを確認する（スラッシュを使用する）
• スクリプトに実行権限があることを確認する
• すべての依存関係を列挙する

例

完全な例については、ドキュメントを参照してください：

• シンプルな単一ファイルの Skill（commit-helper）
• ツール権限を持つ Skill（code-reviewer）
• 複数ファイルの Skill（pdf-processing）

出力形式

Skill を作成する際、次の手順を実行します：

1. 対象範囲と要件について確認の質問をする
2. Skill の名前と配置場所を提案する
3. 適切なフロントマターを含む SKILL.md ファイルを作成する
4. 明確な指示と例を含める
5. 必要に応じて補助ファイルを追加する
6. テスト手順を提示する
7. すべての要件に照らして検証する

完成するのは、すべてのベストプラクティスと検証ルールに従った、完全に動作する Skill です。