skill-writer

Skill Writer

この Skill は、ベストプラクティスと検証要件に従って、Claude Code 用の適切に構成された Agent Skills を作成するのに役立ちます。

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

次の場合にこの Skill を使用します。

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

手順

Step 1: Skill の範囲を決める

まず、この Skill が何を行うべきかを把握します。

1. 明確化のための質問をします：

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

2. 範囲を絞ります：1 つの Skill につき 1 つの機能

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

Step 2: Skill の保存場所を選ぶ

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

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

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

プロジェクト用 Skills（.claude/skills/）：

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

Step 3: Skill の構成を作成する

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

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

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

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

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

Step 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
  • セキュリティ上の配慮が必要なワークフロー
  • 対象範囲が限定された操作

Step 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）を含めます
• よく使われるユーザーの表現（「分析」、「抽出」、「生成」）に言及します
• 具体的な操作を列挙します（汎用的な動詞ではなく）
• 文脈を示す手がかり（「次の場合に使用...」、「...向け」）を加えます

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

Step 8: Skill を検証する

次の要件を確認します。

✅ ファイル構成：

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

✅ YAML フロントマター：

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

✅ コンテンツの品質：

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

✅ テスト：

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

Step 9: Skill をテストする

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

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

   Can you help me extract text from this PDF?
   

3. 有効化を確認します：Claude が Skill を自動的に使用するはずです。

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

Step 10: 必要に応じてデバッグする

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

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
   

一般的なパターン

読み取り専用の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が有効にならない場合：

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

複数の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です。