Skill Expert

専門的な Claude Code スキルの設計・最適化を行うスキルです。

目的

このスキルは以下を提供します：

•新規スキルの作成: ナレッジベースとしてのスキル設計とファイル構造の作成
•既存スキルの改善: 品質、明確性、使いやすさの最適化
•スキルのレビュー: 品質保証とベストプラクティスへの準拠確認
•フロントマター検証: Claude Code 公式仕様への準拠確認

いつ使用するか

プロアクティブ使用（自動で使用を検討）

以下の状況では、ユーザーが明示的に要求しなくても使用を検討してください：

•
スキル設計の議論
- •「〜スキルを作りたい」
- •「〜を共有できるナレッジを作りたい」
- •新しい専門領域のスキルの必要性が明らか
•
スキル品質の問題
- •スキルが期待通りに参照されない
- •スキルの内容が不完全または曖昧
- •フロントマターの設定が不適切
•
スキルシステムの拡張
- •新しいワークフローへのスキル統合
- •エージェントへのスキルプリロード設計
- •既存スキルの機能拡張

明示的な使用（ユーザー要求）

•/skill-expert コマンド
•「スキルを作って」「スキルを改善して」などの直接的な要求

スキル設計原則

1. ナレッジベースの原則

スキルは「知識・手順・テンプレート」を提供し、実際の処理は既存ツールを活用します。

設計方針:

yaml

スキルの役割:
  - ガイドライン提供: 何をどうすべきかの知識
  - テンプレート提供: 標準的な出力形式
  - 手順提供: ステップバイステップのプロセス

実処理:
  - MCP サーバー: ファイルシステム、Git 操作
  - gh CLI: GitHub Issue/PR/Project 操作
  - 組み込みツール: Read, Write, Edit, Glob, Grep

2. 単一責任の原則

各スキルは1つの明確なドメインに特化すべきです。

良い例:

•coding-standards: Python コーディング規約
•tdd-development: TDD 開発プロセス
•error-handling: エラーハンドリングパターン

悪い例:

•general-knowledge: あらゆる知識を含む
•everything-guide: 何でもガイドしようとする

3. 構造の一貫性

全スキルは以下の標準構造に従います：

code

.claude/skills/{skill-name}/
├── SKILL.md           # エントリーポイント（必須）
├── guide.md           # 詳細ガイド（オプション）
├── template.md        # 出力テンプレート（オプション）
└── examples/          # 使用例・パターン集（オプション）

4. プリロード最適化

スキルはエージェントのコンテキストにプリロードされるため、簡潔さが重要です。

コンテキスト効率化:

•SKILL.md: クイックリファレンス（概要、要点のみ）
•guide.md: 詳細は必要時のみ Read で参照
•examples/: 具体例は必要時のみ参照

スキルカテゴリ分類

repository-management（リポジトリ管理）

リポジトリ構造、ドキュメント、プロジェクト管理に関するスキル。

例:

•index: CLAUDE.md/README.md の自動更新
•project-management: GitHub Project と project.md の管理
•task-decomposition: タスク分解と依存関係管理
•issue-creation: Issue の作成
•issue-implementation: Issue の自動実装
•issue-refinement: Issue のブラッシュアップ
•issue-sync: Issue コメントからの同期

coding（コーディング）

コード品質、開発プロセス、エラーハンドリングに関するスキル。

例:

•coding-standards: Python コーディング規約
•tdd-development: TDD 開発プロセス
•error-handling: エラーハンドリングパターン

meta（メタスキル）

スキル・エージェント・ワークフロー自体の設計に関するスキル。

例:

•skill-expert: スキル設計・管理（このスキル）
•agent-expert: エージェント設計・管理
•workflow-expert: ワークフロー設計・管理

domain-specific（ドメイン固有）

特定のドメイン（金融、データ分析等）に特化したスキル。

例:

•yfinance-best-practices: yfinance 使用のベストプラクティス
•market-analysis: 市場分析手法
•sec-edgar: SEC EDGAR データ取得

活用ツールの使用方法

スキルは基本的に既存ツールを活用し、Python スクリプトの実装は最小限に抑えます。

MCP サーバー（ファイルシステム）

bash

# ディレクトリツリー取得
mcp__filesystem__directory_tree(
  path=".",
  excludePatterns=["node_modules", ".git", "__pycache__"]
)

# ファイル検索
mcp__filesystem__search_files(
  path=".",
  pattern="**/*.md"
)

# ディレクトリ一覧
mcp__filesystem__list_directory(path=".")

MCP サーバー（Git）

bash

# ステータス確認
mcp__git__git_status(repo_path=".")

# 差分確認
mcp__git__git_diff(repo_path=".")

# ブランチ作成
mcp__git__git_create_branch(repo_path=".", branch_name="feature/xxx")

gh CLI（GitHub 操作）

bash

# Issue 一覧
gh issue list --json number,title,state,labels

# Issue 作成
gh issue create --title "タイトル" --body "本文"

# Project Item 一覧
gh project item-list <project_number> --format json

# Project Item 追加
gh project item-add <project_number> --owner @me --url <issue_url>

# PR 作成
gh pr create --title "タイトル" --body "本文"

組み込みツール

ツール	用途
Read	ファイル読み取り
Write	ファイル書き込み（新規作成）
Edit	ファイル編集（既存ファイルの部分変更）
Glob	パターンマッチング（ファイル検索）
Grep	正規表現検索（内容検索）

コード品質ツール

bash

# フォーマット
make format

# リント
make lint

# 型チェック
make typecheck

# テスト
make test

# 全チェック
make check-all

プロセス

1. 要件の分析

スキル作成前に以下を明確化します：

bash

# 既存のスキルを確認
ls -la .claude/skills/

# 類似スキルの内容を確認
cat .claude/skills/similar-skill/SKILL.md

•ドメイン境界: スキルの専門領域と提供範囲
•プリロード先: どのエージェントにプリロードされるか
•リソース構成: guide.md, template.md, examples/ の必要性

2. スキル設計

AskUserQuestion ツールを使用して、以下を確認：

•スキルの名前（kebab-case）
•提供する知識・ガイドライン
•想定されるプリロード先エージェント
•必要なリソースファイル

3. スキルの実装

標準的なスキル構造：

markdown

---
name: skill-name
description: Short description for the Skill tool
allowed-tools: Read, Write
---

# Skill Purpose and Context

## 目的

[スキルが提供する価値]

## いつ使用するか

[トリガー条件]

## プロセス

1. Step one
2. Step two
   ...

## リソース

### ./guide.md

[ガイドの内容説明]

### ./template.md

[テンプレートの内容説明]

## 使用例

[3-4 realistic usage examples]

## 品質基準

[MUST/SHOULD criteria]

フロントマター仕様

スキルの SKILL.md ファイルのフロントマターは以下の仕様に従う必要があります。

必須フィールド

フィールド	必須	説明
`name`	✓	スキル名（ディレクトリ名と一致、kebab-case）
`description`	✓	スキルの説明（1行、改行禁止）
`allowed-tools`	-	使用を許可するツール（省略可）

description の書き方

重要: description は改行を含めない1行の文字列で記述すること。

yaml

# ✓ 正しい例（1行）
description: 新しいworktreeとブランチを作成して開発を開始。/worktree コマンドで使用。

# ✗ 誤った例（改行あり）
description: 新しいworktreeとブランチを作成するスキル。
/worktree コマンドで使用。

理由:

•改行を含むと YAML パースエラーの原因になる
•複数行の場合は | ブロックスカラーが必要だが、description には不適切
•Skill ツールの description 表示で見切れる

description のベストプラクティス:

•100文字以内を目安
•「〜するスキル」ではなく「〜する」で終わる動詞形
•コマンド名を含める（例: /worktree コマンドで使用）
•トリガーキーワードを含める

allowed-tools の設定

必要最小限のツールのみを指定：

yaml

# 読み取りのみ
allowed-tools: Read

# 読み書き
allowed-tools: Read, Write, Edit

# GitHub 操作を含む
allowed-tools: Read, Write, Bash, Task

4. テストとバリデーション

作成後の確認項目：

• フロントマターが正しく設定されている
• name がディレクトリ名と一致
• description が1行で改行を含まない
• description が簡潔で目的を説明
• allowed-tools が最小限に設定
• 実用的な例が3個以上含まれている
• リソースファイルが正しく参照されている

5. 既存スキルのブラッシュアップ

既存スキルを改善する際は、AskUserQuestion ツールで情報収集します：

確認項目:

•現状の問題点
•使用頻度と重要度
•期待する改善点
•具体的なユースケース
•成功基準

リソース

このスキルには以下のリソースが含まれています（後続 Issue で作成予定）：

./guide.md

スキル設計の詳細ガイド：

•スキル構造（SKILL.md + guide.md + examples/）の説明
•プロンプトエンジニアリングガイド
•スキルフロントマター検証ルール

./template.md

標準的なスキルテンプレート：

•スキル用フロントマター構造
•スキルセクション構成
•コメント付きガイド

./frontmatter-review.md

フロントマターレビューガイド（agent-expert 拡張と共有）：

•スキルフロントマター検証ルール
•allowed-tools の検証
•description の品質基準

使用例

例1: 新規スキルの作成

状況: コーディング規約を共有するスキルを作成したい

処理:

•要件を明確化（AskUserQuestion 使用）
•既存スキルを調査
•SKILL.md を作成
•guide.md, template.md を作成（必要に応じて）
•バリデーション実行

期待される出力:

code

.claude/skills/coding-standards/
├── SKILL.md
├── guide.md
└── examples/
    ├── type-hints.md
    ├── docstrings.md
    └── naming.md

例2: 既存スキルの改善

状況: project-management スキルの description が曖昧

処理:

•現在の SKILL.md を読み込み
•AskUserQuestion で改善ポイントを収集
•description を具体的なトリガーキーワードで更新
•使用例を追加
•バリデーション実行

期待される出力:

markdown

# 改善前
description: プロジェクト管理

# 改善後
description: |
  GitHub Project と project.md の作成・管理・同期を行うスキル。
  /new-project, /project-refine コマンドで使用。

例3: スキルフロントマターの検証

状況: 新しく作成したスキルの品質を検証したい

処理:

•SKILL.md を読み込み
•フロントマター検証チェックリストを実行
•問題点をレポート
•修正提案を提示

期待される出力:

yaml

検証結果:
  name: ✓ ディレクトリ名と一致
  description: ✗ トリガーキーワードが不足
  allowed-tools: ✓ 最小限に設定

推奨修正:
  description: 「〜の場合に使用」を追加

例4: エージェントへのスキルプリロード設計

状況: feature-implementer エージェントにスキルをプリロードしたい

処理:

•feature-implementer エージェントの責任範囲を確認
•関連するスキルを特定
•フロントマターに skills: フィールドを追加
•スキルの依存関係を検証

期待される出力:

yaml

---
name: feature-implementer
skills:
  - coding-standards
  - tdd-development
  - error-handling
---

品質基準

このスキルの成果物は以下の品質基準を満たす必要があります：

必須（MUST）

• フロントマターの name がディレクトリ名と一致
• description が簡潔でトリガーキーワードを含む
• allowed-tools が必要最小限に設定
• 実用的な使用例が3つ以上含まれている
• リソースファイル（guide.md 等）が SKILL.md で参照されている

推奨（SHOULD）

•プロセスがステップバイステップで説明されている
•品質基準（MUST/SHOULD）が定義されている
•エラーハンドリングが含まれている
•関連スキルへの参照がある

出力フォーマット

スキル作成時

code

================================================================================
                    スキル作成完了
================================================================================

## 作成したスキル
- 名前: {skill_name}
- 配置先: .claude/skills/{skill_name}/

## ファイル構成
- SKILL.md: ✓ 作成
- guide.md: ✓ 作成 / - 不要
- template.md: ✓ 作成 / - 不要
- examples/: ✓ 作成 / - 不要

## 検証結果
| 項目 | 状態 |
|------|------|
| フロントマター | ✓ |
| 使用例 | ✓ ({n}個) |
| 品質基準 | ✓ |

================================================================================

フロントマター検証時

yaml

検証結果:
  name:
    value: "{actual_value}"
    status: "✓ / ✗"
    issue: "{問題点があれば}"
  description:
    value: "{actual_value}"
    status: "✓ / ✗"
    issue: "{問題点があれば}"
  allowed-tools:
    value: "{actual_value}"
    status: "✓ / ✗"
    issue: "{問題点があれば}"

総合判定: PASS / FAIL
推奨修正: [{修正内容}]

エラーハンドリング

スキルが参照されない

原因:

•description にトリガーキーワードがない
•skills: フィールドでの参照漏れ

対処法:

•description を見直し、明確なトリガーワードを追加
•関連エージェントの skills: フィールドを確認

リソースファイルが見つからない

原因:

•guide.md/template.md が存在しない
•パスの指定ミス

対処法:

•リソースファイルの存在を確認
•SKILL.md での参照パスを修正

フロントマター検証エラー

原因:

•YAML 構文エラー
•必須フィールドの欠落

対処法:

•YAML 構文を修正
•必須フィールド（name, description）を追加

完了条件

このスキルは以下の条件を満たした場合に完了とする：

• スキルディレクトリが作成されている
• SKILL.md が作成され、フロントマターが正しい
• 必要なリソースファイルが作成されている
• フロントマター検証がパスしている
• 使用例が3つ以上含まれている

参考資料

•CLAUDE.md: プロジェクト全体のガイドライン
•template/skill/SKILL.md: スキルテンプレート
•.claude/skills/agent-expert/: 参考実装（類似構造）
•docs/plan/2026-01-21_System-Update-Implementation.md: システム更新計画書

Skill Expert

目的

いつ使用するか

プロアクティブ使用（自動で使用を検討）

明示的な使用（ユーザー要求）

スキル設計原則

1. ナレッジベースの原則

2. 単一責任の原則

3. 構造の一貫性

4. プリロード最適化

スキルカテゴリ分類

repository-management（リポジトリ管理）

coding（コーディング）

meta（メタスキル）

domain-specific（ドメイン固有）

活用ツールの使用方法

MCP サーバー（ファイルシステム）

MCP サーバー（Git）

gh CLI（GitHub 操作）

組み込みツール

コード品質ツール

プロセス

1. 要件の分析

2. スキル設計

3. スキルの実装

フロントマター仕様

必須フィールド

description の書き方

allowed-tools の設定

4. テストとバリデーション

5. 既存スキルのブラッシュアップ

リソース

./guide.md

./template.md

./frontmatter-review.md

使用例

例1: 新規スキルの作成

例2: 既存スキルの改善

例3: スキルフロントマターの検証

例4: エージェントへのスキルプリロード設計

品質基準

必須（MUST）

推奨（SHOULD）

出力フォーマット

スキル作成時

フロントマター検証時

エラーハンドリング

スキルが参照されない

リソースファイルが見つからない

フロントマター検証エラー

完了条件

関連スキル

参考資料