skill-forge-build

Skill Builder — スキャフォールディングと生成

プロセス

ステップ 1：入力を収集する

以下をもとに、何を作成するかを判断します。

• 計画ドキュメント：/skill-forge plan の出力（推奨）
• 説明：スキルの自然言語による説明
• 既存のスキル：土台として使用するスキルのパス

計画がない場合は、簡単な計画作成を行います（重要な質問を 3 つします）。

1. スキルは何をしますか？（1〜2 文）
2. どのようなコマンドが必要ですか？（リスト）
3. スクリプトや外部ツールが必要ですか？（はい／いいえ）

ステップ 2：フロントマターを生成する

最も重要なステップです。説明フィールドによって、スキルが有効になるかどうかが決まります。

説明を書くためのフレームワーク：

[Capability statement] + [Detailed capabilities] + [Trigger phrases]

ルール：

• 全体で 1024 文字未満にする
• XML の山括弧（< >）を含めない
• ユーザーが使いそうなトリガーフレーズを 5〜10 個含める
• 該当する場合はファイルの種類に言及する
• 過剰にトリガーされるリスクがある場合は、除外するトリガーを追加する

フレームワークの全容については references/description-guide.md を使用してください。

ステップ 3：メインの SKILL.md を作成する

次のテンプレートに従って本文を構成します。

# [Skill Name] -- [Tagline]

[1-2 sentence overview]

## Quick Reference

| Command | What it does |
|---------|-------------|
| /name cmd1 | Description |
| /name cmd2 | Description |

## Orchestration Logic

[How commands route to sub-skills]
[Decision trees for conditional routing]

## [Domain-Specific Section]

[Core rules, thresholds, quality gates]

## Reference Files

[List of on-demand reference files]

## Sub-Skills

[List of sub-skills with one-line descriptions]

SKILL.md の重要なルール：

• 500 行未満にする
• 5000 トークン未満にする
• 具体的な手順を記載する（曖昧にしない）
• エラー処理を含める
• 参照ファイルは本文に埋め込まず、リンクする

ステップ 4：サブスキルを生成する（ティア 3〜4）

サブスキルごとに、次の内容を含む SKILL.md を生成します。

---
name: parent-child
description: >
  [What it does]. Use when user says "[trigger 1]", "[trigger 2]",
  "[trigger 3]", or "[trigger 4]".
---

サブスキル本文のガイドライン：

• 1 つのワークフローに関する、自己完結した手順にする
• 他のサブスキルの内容を本文に含めず、名前で相互参照する
• 親スキルの references/ ディレクトリにある共有ファイルを参照する
• 入力と出力を明確に定義する

ステップ 5：スクリプトを生成する（ティア 2〜4）

スクリプトごとに、以下を行います。

#!/usr/bin/env python3
"""
Purpose: [What this script does]
Input: [Expected input format]
Output: [Expected output format]
Usage: python scripts/script_name.py [args]
"""

import argparse
import json
import sys
from typing import Any


def main(args: argparse.Namespace) -> dict[str, Any]:
    """Main execution function."""
    # Validate inputs
    # Do the work
    # Return structured output
    pass


if __name__ == "__main__":
    parser = argparse.ArgumentParser(description="[Script description]")
    parser.add_argument("input", help="[Input description]")
    parser.add_argument("--output", "-o", help="Output file path")
    args = parser.parse_args()

    try:
        result = main(args)
        print(json.dumps(result, indent=2))
    except Exception as e:
        print(json.dumps({"error": str(e)}), file=sys.stderr)
        sys.exit(1)

スクリプトのルール：

• 1 つのスクリプトに 1 つの役割を持たせる
• argparse を使用した CLI インターフェースにする
• 構造化された JSON を出力する
• 明確なエラーメッセージを表示する
• 可能な限り、標準ライブラリ以外の依存関係をなくす

ステップ 6：参照ファイルを生成する

参照ファイルごとに、以下を行います。

• 1 つのトピックに絞る
• 200 行未満にする
• 具体例を含める
• しきい値や仕様には表を使用する
• 親の SKILL.md に「オンデマンドで読み込む」と記載する

ステップ 7：エージェント定義を生成する（ティア 4）

エージェントファイルでは YAML フロントマターを使用します（スキルとは異なります）。

---
name: [skill-name]-[role]
description: >
  [What this agent analyzes].
  <example>User says: "[trigger]"</example>
model: inherit
color: blue
tools:
  - Read
  - Grep
  - Glob
---

You are a [role] specialist.

## Your Role
[What this agent does]

## Process
1. [Steps...]

## Output Format
Return structured markdown with findings and recommendations.

スキルとの主な違い： エージェントの name は 3〜50 文字です。説明では <example> ブロックを使用できます。エージェント専用のフィールドには tools、color、permissionMode、maxTurns、memory があります。本文はシステムプロンプトになります（2 人称）。

ステップ 8：インストールスクリプトを生成する

ファイルを ~/.claude/skills/ と ~/.claude/agents/ にコピーする install.sh を作成します。

ステップ 9：検証する

生成したスキルに対して python scripts/validate_skill.py <path> を実行します。 メインの SKILL.md にある品質ゲートをすべて確認します。

ステップ 10：概要を出力する

次の内容をユーザーに提示します。

1. 生成したファイルツリー
2. 主なファイルとその用途
3. インストール手順
4. 推奨するテストクエリ（トリガーされるべきものを 3 つ、されるべきでないものを 3 つ）
5. 次のステップ（テスト、反復、公開）

スキャフォールディングコマンド

すばやくスキャフォールディングするには、以下を使用します。

python scripts/init_skill.py <skill-name> --tier <1-4> --path <output-path>

これにより、プレースホルダーの内容を含むディレクトリ構造全体が作成されます。