skill-creator
スキル作成・更新のガイド。「スキルを作成」「スキルを作りたい」「新しいスキルを追加」「〇〇用のスキルを作って」と言われた時、またはスキル構造、段階的開示、YAML frontmatter、description の書き方について質問された時に使用する。
📖 中文导读:スキル作成・更新のガイド。「スキルを作成」「スキルを作りたい」「新しいスキルを追加」「〇〇用のスキルを作って」と言われた時、またはスキル構造、段階的開示、YAML frontmatter、description の書き方について質問された時に使用する。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。
name: skill-creator description: スキル作成・更新のガイド。「スキルを作成」「スキルを作りたい」「新しいスキルを追加」「〇〇用のスキルを作って」と言われた時、またはスキル構造、段階的開示、YAML frontmatter、description の書き方について質問された時に使用する。
スキル作成ガイド
クイックスタート
スキル作成の基本ステップ:
- 具体例の理解 - どのようなクエリでトリガーされるか明確化
- リソース計画 - scripts/, references/, assets/に何を含めるか決定
- 初期化 -
scripts/init_skill.pyでテンプレート生成 - 実装 - SKILL.mdとリソースを作成
- 検証 -
scripts/validate_skill.pyで品質チェック
スキル構造
skill-name/
├── SKILL.md # 必須: メタデータ + 指示
├── scripts/ # 任意: 実行可能コード
├── references/ # 任意: 参照ドキュメント
└── assets/ # 任意: 出力用ファイル(テンプレート等)
SKILL.md の書き方
Frontmatter(最重要)
---
name: skill-name
description: スキルの機能説明。「〇〇して」「△△を作成」などの具体的トリガーフレーズを含める。
---
descriptionのルール:
- スキルが「何をするか」と「いつ使うか」の両方を記述
- 具体的なトリガーフレーズを含める(「〇〇を作成」「△△を編集」など)
- 三人称で記述(「ユーザーを支援します」ではなく「〇〇を処理する」)
- 1024文字以内
良い例:
description: PDFファイルからテキスト・表を抽出し、フォーム入力・文書マージを行う。「PDFからテキスト抽出」「PDFフォームに入力」「PDF結合」と言われた時に使用。
悪い例:
description: PDFを処理します # 曖昧すぎる、トリガーフレーズがない
Body(本文)
原則: Claudeは賢い。Claudeが知らない情報のみ追加する。
含めるべき:
- 具体的なワークフロー手順
- スクリプトの使用方法
- references/への参照(いつ読むべきか明記)
- 具体的なコード例
含めないでおく:
- 一般的な概念説明(「PDFとは」など)
- Claudeが既に知っている情報
- 冗長な説明
500行以下を維持。超える場合はreferences/に分離。
段階的開示パターン
パターン1: 参照分離
## 基本操作
[基本的なコード例]
## 高度な機能
- **フォーム入力**: [references/forms.md](references/forms.md)参照
- **API詳細**: [references/api.md](references/api.md)参照
パターン2: ドメイン別分離
複数ドメインがある場合、ドメイン別にファイルを分け、必要なものだけロード:
references/
├── finance.md # 財務関連クエリ時のみロード
├── sales.md # 営業関連クエリ時のみロード
└── product.md # 製品関連クエリ時のみロード
パターン3: 条件付き詳細
## 基本編集
XMLを直接編集する。
**追跡変更が必要な場合**: [references/redlining.md](references/redlining.md)
**OOXML詳細が必要な場合**: [references/ooxml.md](references/ooxml.md)
ワークフロー設計
順次ワークフロー
複雑なタスクは明確なステップに分解:
## PDFフォーム入力ワークフロー
進捗チェックリスト:
- [ ] Step 1: フォーム分析(analyze_form.py実行)
- [ ] Step 2: フィールドマッピング作成(fields.json編集)
- [ ] Step 3: マッピング検証(validate_fields.py実行)
- [ ] Step 4: フォーム入力(fill_form.py実行)
- [ ] Step 5: 出力確認(verify_output.py実行)
条件付きワークフロー
1. 変更タイプを判断:
**新規作成?** → 「作成ワークフロー」へ
**既存編集?** → 「編集ワークフロー」へ
フィードバックループ
品質が重要なタスクには検証ループを実装:
1. 変更を実行
2. **すぐに検証**: `python scripts/validate.py`
3. エラーがあれば修正して再検証
4. **検証成功後のみ**次のステップへ
scripts/ の設計
いつスクリプトを含めるか
- 同じコードを繰り返し書く場合
- 決定論的な信頼性が必要な場合
- エラーハンドリングを統一したい場合
スクリプト設計原則
問題を解決し、Claudeに任せない:
# 良い例: エラーを明示的に処理
def process_file(path):
try:
with open(path) as f:
return f.read()
except FileNotFoundError:
print(f"ファイル {path} が見つかりません、デフォルト作成")
with open(path, 'w') as f:
f.write('')
return ''
# 悪い例: エラーをClaudeに任せる
def process_file(path):
return open(path).read() # 失敗したらClaude任せ
マジックナンバーを避ける:
# 良い例: 値を説明
REQUEST_TIMEOUT = 30 # HTTPリクエストは通常30秒以内に完了
MAX_RETRIES = 3 # 3回で一時的失敗の大半が解決
# 悪い例: なぜこの値?
TIMEOUT = 47
RETRIES = 5
references/ の設計
いつreferencesを使うか
- SKILL.mdが500行を超えそうな時
- ドメイン別に情報を分離したい時
- 詳細なAPIドキュメントがある時
長いファイルには目次
100行以上のファイルには冒頭に目次を追加:
# APIリファレンス
## 目次
- 認証とセットアップ
- コアメソッド(CRUD)
- 高度な機能
- エラー処理パターン
- コード例
## 認証とセットアップ
...
具体例: シンプルなスキル
---
name: commit-message
description: gitの差分を分析して説明的なコミットメッセージを生成する。「コミットメッセージを作成」「変更をコミット」と言われた時に使用。
---
# コミットメッセージ生成
## 形式
type(scope): 簡潔な説明
詳細説明(任意)
## 例
**入力**: JWT認証を追加
**出力**:
feat(auth): JWT認証を実装
ログインエンドポイントとトークン検証ミドルウェアを追加
**入力**: 日付表示バグ修正
**出力**:
fix(reports): タイムゾーン変換での日付フォーマット修正
レポート生成全体でUTCタイムスタンプを一貫使用
具体例: リソース付きスキル
pdf-processor/
├── SKILL.md
├── scripts/
│ ├── extract_text.py
│ ├── fill_form.py
│ └── validate.py
└── references/
├── forms.md
└── api.md
---
name: pdf-processor
description: PDFからテキスト・表抽出、フォーム入力、文書マージを行う。「PDFからテキスト抽出」「PDFフォーム入力」「PDF結合」と言われた時に使用。
---
# PDF処理
## クイックスタート
テキスト抽出:
python scripts/extract_text.py input.pdf > output.txt
## フォーム入力
1. フォーム分析: `python scripts/analyze_form.py form.pdf`
2. フィールド編集: `fields.json`を編集
3. 入力実行: `python scripts/fill_form.py form.pdf fields.json output.pdf`
**詳細**: [references/forms.md](references/forms.md)
## API詳細
高度なオプションについては[references/api.md](references/api.md)参照
避けるべきパターン
冗長な説明
# 悪い例
PDF(Portable Document Format)は、テキストや画像を含む一般的なファイル形式です...
# 良い例
pdfplumberでテキスト抽出:
複数オプションの提示
# 悪い例
pypdfまたはpdfplumberまたはPyMuPDFを使用できます...
# 良い例
テキスト抽出にはpdfplumberを使用:
(スキャンPDFでOCRが必要な場合はpdf2image + pytesseract)
深いネスト参照
# 悪い例: 2レベル以上のネスト
SKILL.md → advanced.md → details.md
# 良い例: 1レベルのみ
SKILL.md → references/advanced.md
SKILL.md → references/details.md
チェックリスト
作成完了前に確認:
必須
- descriptionに具体的トリガーフレーズがある
- descriptionに「何をするか」と「いつ使うか」が含まれる
- SKILL.md本文が500行以下
- 冗長な説明がない(Claudeは既に知っている情報)
推奨
- 具体的なコード例がある
- ワークフローに明確なステップがある
- 参照ファイルへのリンクに「いつ読むか」が明記
- スクリプトにエラーハンドリングがある
スクリプト
- 初期化:
python scripts/init_skill.py <skill-name> --path <output-dir> - 検証:
python scripts/validate_skill.py <skill-dir>