skillkit

セクション 1：意図の検出とルーティング

ユーザーの意図を検出し、適切なワークフローにルーティングします。

意図	キーワード	ルーティング先
スキルの完全な作成	"create skill", "build skill", "new skill"	セクション 2
サブエージェントの作成	"create subagent", "build subagent", "new subagent"	セクション 6
検証	"validate", "check quality"	セクション 3
判断	"Skills vs Subagents", "decide", "which to use"	セクション 4
移行	"convert", "migrate doc"	セクション 5
単一ツール	"validate only", "estimate tokens", "scan"	セクション 7

意図を検出したら、対応するセクションに進んでください。

停止条件（必須）：

• 複数のルートが該当する場合、または意図が曖昧な場合は、停止してユーザーにルートを選択するよう求めます。
• ユーザーがルートを確定するまで先に進まないでください。

ワークフローの価値： 調査に基づくアプローチにより、構築前に設計を検証できます。 チェックポイントを設けた順次ステップにより、場当たり的な作成と比べて 9.0/10 以上の品質を実現できます。

---

セクション 2：作成ワークフロー（二つのモード）

前提条件： スキルの説明が提供されており、ワークスペースを利用できること。

モードの選択（開始時に必須）

作成フローを実行する前に、ワークフローのモードを検出するか、ユーザーに確認してください。

停止条件（必須）：

• モードが明示されていない場合は、停止して「fast モードと full モードのどちらにしますか？」と尋ねます。
• ユーザーがモードを確定するまで先に進まないでください。

モード	ステップ数	検証	品質目標	所要時間
fast	10	構造のみ	>=9.0/10	<10 分
full	14	構造＋動作	>=9.0/10 かつ動作 >=7.0	<20 分

モードが明示的に特定されていない場合、暗黙のデフォルトモードは使用できません。

ワークフロー A：fast モード（10 ステップ）

.skillkit-mode に fast が含まれている場合、またはマーカーが存在しない場合に使用します。

→ 開始前に references/section-2-fast-creation-workflow.md を最後まで読んでください。 そのファイルに記載された各ステップのタスクを作成し、順番に実行してください。 以下の概要は要約にすぎません。正式な手順は参照ファイルに従ってください。

フェーズ 1：判断と調査

• ステップ 0：アプローチを決定する（decision_helper.py）
• ステップ 1：調査と提案
• ステップ 2：ユーザーによる検証
• 停止条件：ステップ 3 に進む前に停止し、ユーザーの承認を求めます。

フェーズ 2：作成

• ステップ 3：スキルを初期化する（init.py skill <name> --mode fast）
• ステップ 4：コンテンツを作成する

フェーズ 3：構造検証

• ステップ 5：スキルを検証する（validate_skill.py）— 1 回の呼び出しで構造＋セキュリティ＋トークンを実行します

フェーズ 4：パッケージ化

• ステップ 6：段階的開示を確認する
• ステップ 7：テストを生成する（test_generator.py）
• ステップ 8：品質を評価する（quality_scorer.py）
• ステップ 9：パッケージ化する（package_skill.py）

ワークフロー B：フルモード（14 ステップ）

.skillkit-mode に full が含まれている場合に使用します。

→ 開始前に references/section-2-full-creation-workflow.md を最後まで読んでください。 このファイルに記載されている各ステップのタスクを作成し、順番に実行してください。 以下の概要は要約のみです。正式な手順は参照ファイルに従ってください。

フェーズ 1：判断と調査

• ステップ 0：アプローチを決定します（decision_helper.py）
• ステップ 1：調査と提案
• ステップ 2：ユーザーによる確認
• 停止条件：ステップ 3 に進む前に停止し、ユーザーの承認を求めてください。

フェーズ 2：行動ベースライン（fast モードより追加）

• ステップ 3（RED）：スキルなしでプレッシャーシナリオを実行します → references/section-2-full-creation-workflow.md の「Full Mode Behavioral Testing Protocol」セクションを読み込んでください（必須）。
• ステップ 4：ベースラインでの失敗を記録します

フェーズ 3：作成

• ステップ 5：スキルを初期化します（init.py skill <name> --mode full）
• ステップ 6：ベースラインでの失敗に対処するコンテンツを作成します

フェーズ 4：行動検証（fast モードより追加）

• ステップ 7（GREEN）：スキルを使ってシナリオを実行します → references/section-2-full-creation-workflow.md の「Full Mode Behavioral Testing Protocol」セクションを読み込んでください（必須）。
• ステップ 8：不足箇所を修正します

フェーズ 5：構造検証

• ステップ 9：スキルを検証します（validate_skill.py）。1 回の呼び出しで構造、セキュリティ、トークンを検証します

フェーズ 6：改善（fast モードより追加）

• ステップ 10（REFACTOR）：統合プレッシャーテストを実行します → references/section-2-full-creation-workflow.md の「Full Mode Behavioral Testing Protocol」セクションを読み込んでください（必須）。
• ステップ 11：抜け穴を塞ぎます

フェーズ 7：パッケージ化

• ステップ 12：品質を評価します（quality_scorer.py --format json）。行動スコアは --behavioral フラグではなく、ステップ 3、7、10 のサブエージェントの結果から算出されます
• ステップ 13：パッケージ化します（package_skill.py）

モードの検出

優先順位：

1. 明示的なフラグ：--mode fast または --mode full
2. スキルマーカー：.skillkit-mode ファイルの内容
3. 不明な場合：停止し、fast または full の選択をユーザーに求めます

---

セクション 3：検証ワークフロー（概要）

用途： 既存のスキルを検証する場合

ステップ： 検証対象のステップ（ステップ 3～6）を実行します

1. スキルを検証します。構造、セキュリティ、トークンを検証します（validate_skill.py。フラグは不要です）
2. 段階的開示を確認します
3. テストを生成します（任意）
4. 品質を評価します（quality_scorer.py）

注： --security-only と --tokens-only フラグは、セクション 7 で個別のツールを使用する場合に利用できます。ワークフローの検証ステップでは使用しません。

詳細なワークフロー： references/section-3-validation-workflow-existing-skill.md を参照してください

---

セクション 4：判断ワークフロー（概要）

用途： Skills が適切なアプローチか判断できない場合

重要：エージェントは、まず一時的な JSON ファイルを作成する必要があります。 decision_helper.py スクリプトはインラインの JSON 文字列を受け付けません。JSON ファイルへのパスが必要です。

ステップごとの実行方法： references/section-4-decision-workflow-skills-vs-subagents.md を参照してください

精度： 最高（確信度 90～95％）。

手順：

1. JSON ファイルを使って decision_helper.py を実行します。
2. 対話形式の質問に回答します
3. 確信度スコア付きの推奨事項を受け取ります
4. Skills が推奨された場合は、先に進みます（確信度 >=75%）
5. 確信度が 75％ 未満、または推奨事項が不確かな場合は、停止し、続行するか、別の方法に切り替えるか、入力を調整するかをユーザーに確認します。

詳細なワークフロー： references/section-4-decision-workflow-skills-vs-subagents.md を参照してください

---

セクション 6：サブエージェント作成ワークフロー（概要）

用途： 新しいサブエージェントを作成する場合（ユーザーから明示的に依頼された場合、または判断ワークフローで推奨された場合）

前提条件： 役割の定義が明確であること、ワークスペースを利用できること 品質目標： 明確な役割、包括的なワークフロー、テスト可能な例 所要時間： テンプレートを使って 15 分未満

8 ステップのプロセス：

STEP 0：要件と役割の定義

• 回答する項目：主な役割は何か？ 呼び出し条件は何か？ ツール要件は何か？
• 定義済みリストから subagent_type を選択します

STEP 1：サブエージェントファイルの初期化

• ツール：python scripts/init.py subagent subagent-name --path ~/.claude/agents
• 作成されるもの：テンプレートを含む ~/.claude/agents/subagent-name.md
• 重要： サブエージェントは個別の .md ファイルです（ディレクトリではありません）
• 停止条件：対象ファイルがすでに存在する場合は、上書き、名前変更、キャンセルのどれにするかユーザーに確認して停止します。

STEP 2：設定の定義

• YAML フロントマター（name、description、type、tools、skills）を編集します
• ツール権限を設定します（必要最小限）

STEP 3：役割とワークフローの定義

• 役割の定義セクション
• 呼び出し条件（いつ呼び出すか）
• 複数フェーズのワークフロー

STEP 4：応答形式の定義

• 出力構造のテンプレート
• トーンとスタイルのガイドライン
• エラー処理

STEP 5：例の追加

• 完全な例を少なくとも 1 つ追加します
• 入力／処理／出力の形式

STEP 6：検証

• YAML の妥当性チェック
• 構造の検証
• 完全性の確認

STEP 7：テスト

• Task ツールで呼び出しをテストします
• 結果に基づいて反復します

STEP 8：ドキュメント作成とデプロイ

• README.md を作成します
• システムに登録します
• 停止条件：登録／デプロイする前に、ユーザーに明示的な確認を求めます。

詳細なワークフロー： references/section-6-subagent-creation-workflow.md を参照

---

セクション 5：移行ワークフロー（概要）

使用する場面： ドキュメントをスキルに変換する場合

プロセス：

1. 判断の確認（Step 0）
2. 移行分析（migration_helper.py）
3. 構造の作成
4. 検証手順の実行（5～8）
5. パッケージ化（Step 9）

停止条件（必須）：

• 構造の作成、または書き込み／上書き操作を行う前に、ユーザーに確認を求めます。
• ユーザーの確認があるまで、ファイルを変更してはいけません。

詳細なワークフロー： references/section-5-migration-workflow-doc-to-skill.md を参照

---

セクション 7：個別ツールの使用

使用する場面： ユーザーがワークフロー全体ではなく、単一のツールを必要としている場合

開始点： 「トークン数を見積もる」や「セキュリティスキャン」など、特定のツールをユーザーが求めている場合

利用可能なツール

検証ツール：

python scripts/validate_skill.py skill-name/ --format json

ガイド：knowledge/tools/14-validation-tools-guide.md

トークン数見積もりツール：

python scripts/validate_skill.py skill-name/ --tokens-only --format json

ガイド：knowledge/tools/15-cost-tools-guide.md

セキュリティスキャナー：

python scripts/validate_skill.py skill-name/ --security-only --format json

ガイド：knowledge/tools/16-security-tools-guide.md

パターン検出ツール：

# Analysis mode with JSON output
python scripts/pattern_detector.py "convert PDF to Word" --format json

# List all patterns
python scripts/pattern_detector.py --list --format json

# Interactive mode (text only)
python scripts/pattern_detector.py --interactive

ガイド：knowledge/tools/17-pattern-tools-guide.md

判断支援ツール：

# Analyze use case (JSON output - agent-layer default)
python scripts/decision_helper.py --analyze "code review with validation"

# Show decision criteria (JSON output)
python scripts/decision_helper.py --show-criteria --format json

# Text mode for human reading (debugging)
python scripts/decision_helper.py --analyze "description" --format text

ガイド：knowledge/tools/18-decision-helper-guide.md

テスト生成ツール（v1.2：パラメーター更新）：

python scripts/test_generator.py skill-name/ --test-format pytest --format json

• --test-format：テストフレームワーク（pytest/unittest/plain、デフォルト：pytest）
• --format：出力形式（text/json、デフォルト：text）
• 後方互換性：以前の --output パラメーターも引き続き使用できます（非推奨）

ガイド：knowledge/tools/19-test-generator-guide.md

スキル分割ツール：

python scripts/split_skill.py skill-name/ --format json

ガイド：knowledge/tools/20-split-skill-guide.md

品質スコアラー：

python scripts/quality_scorer.py skill-name/ --format json

ガイド：knowledge/tools/21-quality-scorer-guide.md

移行ヘルパー：

python scripts/migration_helper.py doc.md --format json

ガイド：knowledge/tools/22-migration-helper-guide.md

サブエージェント初期化ツール（新規）：

python scripts/init.py subagent subagent-name --path /path/to/subagents

ガイド：references/section-6-subagent-creation-workflow.md

ツール出力の標準化（v1.0.1 以降）

9 つのツールすべてが --format json に対応しています。--format text を指定すれば、テキストモードも引き続き利用できます（後方互換性あり）。decision_helper は自動化向けに JSON をデフォルトとします。

JSON 出力構造：

{
  "status": "success" | "error",
  "tool": "tool_name",
  "timestamp": "ISO-8601",
  "data": { /* tool-specific results */ }
}

品質保証の強化（v1.2+）

ファイルと参照の検証：

• validate_skill.py がファイル参照（Markdown リンク、コード参照、パスパターン）を包括的にチェックするようになりました
• package_skill.py はパッケージ化の前に参照を検証し、孤立したファイルを検出します
• デプロイ済みのスキルで参照切れや不完全なファイルが発生するのを防ぎます

コンテンツ予算の適用（v1.2+）：

• ファイルサイズに上限を設定：P0 ≤150 行、P1 ≤100 行、P2 ≤60 行
• 進捗インジケーター付きのリアルタイムのトークン数カウント
• 以前、目標を4～9倍超過する原因となっていたファイルの肥大化を防ぎます

実行計画（v1.2+）：

• P0/P1/P2 の優先順位付けにより、スコープの過剰な拡大を防ぎます
• 効率を維持するため、ファイルごとにトークン予算を割り当てます
• リサーチフェーズでは、Verbalized Sampling の確率しきい値（p>0.10）を遵守します

品質スコアのコンテキスト：

• スコアは、一般的なスキル品質のヒューリスティクスに合わせて調整されています
• 目標：70%+ は良好、80%+ は優秀です
• スタイルのスコアリングは、すべてのスキルタイプ（教育向けと技術向けなど）に適合するとは限りません
• 指針として利用し、エッジケースでは手動レビューを併用してください

---

セクション 8：モード選択ガイド

スキルの種類	推奨モード	理由
TDD または規律を重視するスキル	full	プレッシャー下での合理化に抵抗する必要があります
コードパターンのスキル	fast	通常は構造チェックで十分です
API リファレンスのスキル	fast	主に検索精度が重要です
ワークフローオーケストレーションのスキル	full	複雑なフローにはプレッシャーチェックが有効です
デバッグ手法のスキル	fast	明確な手法を備えた簡潔な技術です

full モードでは、行動テスト（プレッシャーシナリオ）が追加されます。規律の徹底がスキルの目的の中核をなす場合に使用してください。

---

セクション 9：ナレッジリファレンスマップ（概要）

戦略的なコンテキストを必要に応じて読み込みます。

基礎概念（ファイル 01-08）：

• スキルが存在する理由と、代替手段との比較
• スキルとサブエージェントの選択フレームワーク
• トークンのコストと効率
• プラットフォームの制約とセキュリティ
• スキルを使用しない場合

応用知識（ファイル 09-13）：

• 実際の事例研究（Rakuten、Box、Notion）
• 技術アーキテクチャのパターン
• 導入とテストの戦略
• 競合状況の分析

ツールガイド（ファイル 14-22）：

• 自動化スクリプトごとのガイド
• 使用パターンとパラメーター
• JSON 出力形式
• 統合例

リファレンスマップの全容はこちら： references/section-7-knowledge-reference-map.md を参照

---

ワークフローの遵守

ワークフローを順番に実行してください。ゲートを設けた順次ステップにより、9.0/10+ の品質が得られます。ユーザーが理由を示した場合は、逸脱も認められます。

柔軟な開始方法：

• 単一ツール（セクション 7）：ワークフロー全体を省略
• 検証のみ（セクション 3）：検証の一部を実行
• サブエージェント（セクション 6）：簡略化された8ステップのワークフロー

---

追加リソース

詳細な実装ガイダンスが必要な場合は、references/ からリファレンスファイルを必要に応じて読み込んでください。