claude-skills

Claude Skills メタスキル

散在するドメイン資料を、再利用・保守が容易で、確実に有効化される Skill にまとめます。

• エントリーポイントとしての SKILL.md（トリガー、制約、パターン、例）
• 詳細な根拠資料とナビゲーション用の references/
• スキャフォールディングとテンプレート用の任意の scripts/ と assets/

この Skill を使用する場面

次のような場合に、このメタスキルを使用します。

• ドキュメント、仕様書、リポジトリから新しい Skill を一から作成する
• 既存の Skill をリファクタリングする（長すぎる、分かりにくい、一貫性がない、誤作動する）
• 確実に有効化されるよう設計する（フロントマター、トリガー、境界）
• 大量の資料から簡潔なクイックリファレンスを抽出する
• 長いコンテンツを、ナビゲーションしやすい references/ に分割する
• 品質ゲートとバリデーターを追加する

対象外／境界

このメタスキルは、次のものではありません。

• 単独で使えるドメイン Skill（ドメイン Skill を構築するためのものです）
• 外部の事実を作り出す許可（資料で裏付けられない場合は、その旨を明記し、検証方法を追加してください）
• 必要な入力の代わり（入力が不足している場合は、作業を進める前に1～3個質問してください）

クイックリファレンス

成果物（作成必須のもの）

出力には、必ず次の内容を含めてください。

1. 具体的なディレクトリ構成（通常は skills/<skill-name>/）
2. 判断可能なトリガーと境界、再現可能な例を含む、実用的な SKILL.md
3. references/ に移動した詳細ドキュメントと、references/index.md
4. 提出前チェックリスト（品質ゲート）

推奨レイアウト（最小構成から完全構成まで）

skill-name/
|-- SKILL.md              # Required: entrypoint with YAML frontmatter
|-- references/           # Optional: long-form docs/evidence/index
|   `-- index.md          # Recommended: navigation index
|-- scripts/              # Optional: helpers/automation
`-- assets/               # Optional: templates/configs/static assets

本当に最小限の構成は SKILL.md のみです（後から references/ を追加できます）。

YAML フロントマター（必須）

---
name: skill-name
description: "What it does + when to use (activation triggers)."
---

フロントマターのルール：

• name は ^[a-z][a-z0-9-]*$ に一致する必要があり、ディレクトリ名と一致させることが推奨されます
• description は判断可能な内容でなければなりません（「X を支援する」のような表現は不可）。具体的なトリガーキーワードを含めてください

最小限の SKILL.md のひな形（コピーして貼り付け）

---
name: my-skill
description: "[Domain] capability: includes [capability 1], [capability 2]. Use when [decidable triggers]."
---

# my-skill Skill

One sentence that states the boundary and the deliverable.

## When to Use This Skill

Trigger when any of these applies:
- [Trigger 1: concrete task/keyword]
- [Trigger 2]
- [Trigger 3]

## Not For / Boundaries

- What this skill will not do (prevents misfires and over-promising)
- Required inputs; ask 1-3 questions if missing

## Quick Reference

### Common Patterns

**Pattern 1:** one-line explanation
```text
[command/snippet you can paste and run]

例

例1

• 入力：
• 手順：
• 期待される出力／受け入れ基準：

例2

例3

リファレンス

• references/index.md：ナビゲーション
• references/...：トピックごとに分割した詳細ドキュメント

メンテナンス

• ソース：ドキュメント／リポジトリ／仕様書（作り出さないこと）
• 最終更新日：YYYY-MM-DD
• 既知の制限：明示的に対象外とする内容

### Authoring Rules (Non-negotiable)

1. Quick Reference is for short, directly usable patterns
   - Keep it <= 20 patterns when possible.
   - Anything that needs paragraphs of explanation goes to `references/`.
2. Activation must be decidable
   - Frontmatter `description` should say "what + when" with concrete keywords.
   - "When to Use" must list specific tasks/inputs/goals, not vague help text.
   - "Not For / Boundaries" is mandatory for reliability.
3. No bluffing on external details
   - If the material does not prove it, say so and include a verification path.

### Workflow (Material -> Skill)

Do not skip steps:
1. Scope: write MUST/SHOULD/NEVER (three sentences total is fine)
2. Extract patterns: pick 10-20 high-frequency patterns (commands/snippets/flows)
3. Add examples: >= 3 end-to-end examples (input -> steps -> acceptance)
4. Define boundaries: what is out-of-scope + required inputs
5. Split references: move long text into `references/` + write `references/index.md`
6. Apply the gate: run the checklist and the validator

### Quality Gate (Pre-delivery Checklist)

Minimum checks (see `references/quality-checklist.md` for the full version):
1. `name` matches `^[a-z][a-z0-9-]*$` and matches the directory name
2. `description` states "what + when" with concrete trigger keywords
3. Has "When to Use This Skill" with decidable triggers
4. Has "Not For / Boundaries" to reduce misfires
5. Quick Reference is <= 20 patterns and each is directly usable
6. Has >= 3 reproducible examples
7. Long content is in `references/` and `references/index.md` is navigable
8. Uncertain claims include a verification path (no bluffing)
9. Reads like an operator's manual, not a documentation dump

Validate locally:

```bash
# From repo root (basic validation)
./skills/claude-skills/scripts/validate-skill.sh skills/<skill-name>

# From repo root (strict validation)
./skills/claude-skills/scripts/validate-skill.sh skills/<skill-name> --strict

# From skills/claude-skills/ (basic validation)
./scripts/validate-skill.sh ../<skill-name>

# From skills/claude-skills/ (strict validation)
./scripts/validate-skill.sh ../<skill-name> --strict

ツールとテンプレート

新しい Skill のひな形を生成します。

# From repo root (generate into ./skills/)
./skills/claude-skills/scripts/create-skill.sh my-skill --full --output skills

# From skills/claude-skills/ (generate into ../ i.e. ./skills/)
./scripts/create-skill.sh my-skill --full --output ..

# Minimal skeleton
./skills/claude-skills/scripts/create-skill.sh my-skill --minimal --output skills

テンプレート：

• assets/template-minimal.md
• assets/template-complete.md

例

例1：ドキュメントから Skill を作成する

• 入力：公式ドキュメント／仕様書、実際のコードサンプル2～3件、よくある失敗例
• 手順：
  1. create-skill.sh を実行して skills/<skill-name>/ を作成する
  2. フロントマターの description を「何をするか＋いつ使うか」の形式で記述する
  3. 頻出するパターンを10～20件、クイックリファレンスに抽出する
  4. 受け入れ基準を含む、エンドツーエンドの例を3件以上追加する
  5. 長いコンテンツを references/ に移し、references/index.md から参照できるようにする
  6. validate-skill.sh --strict を実行し、必要に応じて修正する

例2：「ドキュメントの貼り付け集」Skill をリファクタリングする

• 入力：長いドキュメントを貼り付けた既存の SKILL.md
• 手順：
  1. どの部分がパターンで、どの部分が詳細な説明なのかを特定する
  2. 詳細な説明を references/ に移し、トピックごとに分割する
  3. クイックリファレンスを、短くコピーして貼り付けられるパターンとして書き直す
  4. 再現可能になるまで、例を追加または修正する
  5. 誤作動を減らすため、「対象外／境界」を追加する

例3：Skill を検証して品質ゲートを適用する

• 入力：skills/<skill-name>/
• 手順：
  1. validate-skill.sh（strict なし）を実行し、警告を確認する
  2. フロントマターと名前の不一致や、欠落しているセクションを修正する
  3. validate-skill.sh --strict を実行して、仕様への準拠を徹底する
  4. 提出前に references/quality-checklist.md の採点基準を実施する

参考資料

ローカルドキュメント：

• references/index.md
• references/skill-spec.md
• references/quality-checklist.md
• references/anti-patterns.md
• references/README.md（上流の公式リファレンス）

外部（公式）：

• https://support.claude.com/en/articles/12512176-what-are-skills
• https://support.claude.com/en/articles/12512180-using-skills-in-claude
• https://support.claude.com/en/articles/12512198-creating-custom-skills
• https://docs.claude.com/en/api/skills-guide

メンテナンス

• ソース：skills/claude-skills/references/ 内のローカル仕様ファイルと、references/README.md 内の上流の公式ドキュメント
• 最終更新日：2025-12-14
• 既知の制限：validate-skill.sh はヒューリスティックです。厳格モードでは、推奨されるセクション見出しがあることを前提とします