skill-writer

スキルライター

このスキルは、ベストプラクティスと検証要件に従った、適切に構成された Claude Code 用 Agent Skills の作成を支援します。

このスキルを使う場面

次の場合にこのスキルを使います：

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

手順

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

まず、スキルで何を実現するのかを把握します。

1. 確認の質問をする：

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

2. 範囲を絞る：1 つのスキルにつき 1 つの機能にします。

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

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

スキルを作成する場所を決めます。

個人用スキル（~/.claude/skills/）：

• 個人のワークフローや好み
• 実験的なスキル
• 個人の生産性向上ツール

プロジェクト用スキル（.claude/skills/）：

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

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

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

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

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

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

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
  

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

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

説明は、Claude がスキルを見つけるうえで非常に重要です。

公式：[実行する内容] + [使用する場面] + [主なトリガー]

例：

✅ 適切：

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：スキルの内容を構成する

明確な 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.md が正しい場所に存在する
• ディレクトリ名がフロントマターの name と一致する

✅ YAML フロントマター：

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

✅ コンテンツの品質：

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

✅ テスト：

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

ステップ 9：スキルをテストする

1. スキルを読み込むため、Claude Code の実行中は再起動します。

2. 説明に合致する関連の質問をします。

   Can you help me extract text from this PDF?
   

3. 有効化を確認する：Claude がスキルを自動的に使うことを確認します。

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

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

Claude がスキルを使わない場合：

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

   • トリガーワードを追加する
   • ファイルの種類を含める
   • よく使われるユーザーの表現に言及する

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

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

3. YAML を検証する：

   cat SKILL.md | head -n 10
   

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

   claude --debug
   

よくあるパターン

読み取り専用スキル

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

スクリプトベースのスキル

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

段階的な情報開示を行う複数ファイルのスキル

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

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

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

検証チェックリスト

スキルを完成させる前に、次の点を確認してください。

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

トラブルシューティング

スキルが有効にならない場合：

• トリガーワードを加えて説明をより具体的にする
• ファイルの種類と操作を説明に含める
• ユーザーが使う表現を含む「Use when...」句を追加する

複数のスキルが競合する場合：

• 説明の違いをより明確にする
• 異なるトリガーワードを使う
• 各スキルの範囲を絞る

スキルにエラーがある場合：

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

例

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

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

出力形式

スキルを作成するときは、次の手順を実行します。

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

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