run-build-skill

※ creator-kit Phase 0 移行中は creator-kit/skills/ が正本、.claude/skills/ への配置は派生。本SKILL.mdは両配置で動作するよう self-relative パスを使用。

Purpose & Output Contract

ユーザー要求からClaude Code Skillを1本構築するワークフロー。

入力: skill_name (kebab-case), kind (run|ref|assign|wrap|delegate), mode (create|update, デフォルト: create), with_subagent (フラグ、指定時のみStep7実行), model (opus|sonnet, デフォルト: opus) 出力:

• $OUT_BASE/<name>/SKILL.md（Phase 0 は creator-kit/skills/、移行後は .claude/skills/ または plugin 配置。300行以下、frontmatter完備。本文はパラメーター名を除き日本語）
• 必要に応じ templates/, references/, scripts/, examples/
• eval-log/skill-build-trace.json（task→refs map、01aフロー、02/03/04/05/06/07/08/09/10/11/13/14/15/16/26/27/28/29/30/31/32/33/34/35 concern への対応証跡）
• assign-skill-design-evaluator による評価レポート (eval-log/docs/<NN>-<timestamp>.json) と eval-log/<plugin>/<date>-score.jsonl 追記

完了条件: rubric score >= 80 かつ high severity 0件。

Key Rules

1. 300行制約: SKILL.md本文は300行以下。超過分は references/ へ分割（07章）。
2. descriptionは発動条件のみ: 動作詳細は本文化（08章）。
3. triggerは2〜3個: description内のUse when句は2〜3個の動詞ベース条件（08章 hard rule）。
4. ディレクトリ名 == frontmatter.name: 第8条。
5. クロスプラットフォーム: Mac/Linux は zsh/bash + python3 stdlib、Windows は PowerShell 5.1+ + python3 stdlib（設計書22章）。OS分岐は本文 <important if="os=..."> で表現する。
6. 評価分離: 生成本体は評価しない。assign-skill-design-evaluator をforkで呼ぶ（09章 Goodhart対策）。
7. kindに応じたテンプレ選択: 11章テンプレを templates/ から展開。
8. context予算制約 (CD-005): 全章一括ロード禁止。各Stepで必要な章のみ参照。
9. --mode update: 既存Skillへの増分改修。既存SKILL.mdを読んでdiffを適用する。
10. モデル既定値: build-subagent.py は --model opus で実行（PF-F3-001）。
11. 横展開候補は登録案を作る: 生成物が Skill Creator 基盤、hook、lint、adapter、rubric、reference に該当する場合は run-skill-create の creator-kit 登録判定へ戻し、manifest更新をユーザー確認に委ねる。
12. 正本トレース必須: 生成・更新ごとに task→refs map の選択、Intent / Contract / Boundary / Execution / Feedback、01a Step 1〜9、02 Skill構造、03 frontmatter、04 invocation/permissions、05 execution layer、06 classification/naming、07 progressive disclosure、08本文設計、09評価編成、10Subagent/Hook連携、11テンプレ適用、13チェックリスト/lint、14 dynamic injection、15公式参照追跡、16公式Skills仕様、26メタSkillドッグフーディング、27rubricガバナンス、28script実行モデル の対応を skill-build-trace.json に残す。
13. 実行レイヤー判断を固定化: Skill / Subagent / Hook / MCP / CLI / script の配置理由を trace に記録し、決定論で落とせる検査は script/hook へ分離する。
14. 再現性ゲートは機械検証: scripts/validate-build-trace.py で source_docs / build_flow_coverage / doc_coverage / layer_decisions / gates を検証し、空欄・未読・N/A理由なしを通さない。
15. 量産情報を消費する: pattern_refs / variant_axes / reuse_targets / deterministic_checks / placement_candidates / hook_events を trace と生成本文へ反映し、未消費のまま捨てない。
16. 日本語成果物: SKILL.md、SubAgent、review、完了レポートの説明文は日本語で作成する。frontmatterキー、JSONキー、CLI引数、テンプレート変数などのパラメーター名は英語のままでよい。
17. 26/27/28章ゲートを省略しない: メタSkill、rubric、script、hook、subagent を生成・更新する場合は、設計書26/27/28章を読み、dogfooding_model / governance_model / script_execution_model を trace に記録する。対象外でも N/A と理由を残す。
18. 29〜35章を量産判断へ接続する: skill creator / 量産 / 再現性 / rubric合成 / output routing / adapter / 類推理解 / creator-kit配布 / change governance / plugin境界 / meta-harness を含む場合は、設計書29〜35章と references/skill-factory-reproducibility.md を読み、rubric_composition_model / paradigm_analogy_model / output_routing_model / implementation_ledger_model / change_governance_model / plugin_boundary_model / meta_harness_model / variable_contract を trace に残す。対象外でも N/A と理由を残す。
19. 具体値は変数化する: 再利用される Skill本文、SubAgent、テンプレート、config example には固定プロジェクト名、固定URL、固定owner、固定チャンネル名、固定secret service名を直書きしない。必要な具体値は source_trace に残し、成果物側は {{PROJECT_ROOT}} / {{KIT_ROOT}} / {{DOMAIN}} / {{TASK_KIND}} / {{SECRET_NAMESPACE}} などの変数で表現する。

Steps

Step 1: 要求ヒアリング

[MANDATORY - ch15/ch16 公式参照確認] このステップの最初に ref-yaml-spec-fetcher を呼び出して yaml-spec-cache.md を Read すること。スキップは禁止。 validate-build-trace.py が 15-official-source-notes / 16-official-skills-reference を検証し、 未実施の場合 exit 1 となる。

Skill(ref-yaml-spec-fetcher)

• skill_name の kebab-case とprefix妥当性を確認 → scripts/validate-naming.py
• kind を確定（run/ref/assign/wrap/delegate）
• mode を確定（create / update、デフォルト: create）
• references/resource-map.yaml を最初に読み、task category と読む設計書を決める
• 01章の5要素（Intent / Contract / Boundary / Execution / Feedback）を1文ずつ埋める
• 01a Step 2 の実行レイヤー判断表で、Skill / Subagent / Hook / MCP / CLI / script の分担を決める
• 02章で配置スコープ / reference-task 境界 / Additional Resources を決める
• 03章で frontmatter の trigger 2〜3個、独自メタデータ、依存注入フィールドを決める
• 04章で allowed-tools と permissions.deny / hook の責務分離を決める
• 詳細仕様が不足する場合は references/build-steps.md を参照
• context予算: 設計書は references/resource-map.yaml が選んだものだけ読む。同時に読む設計書は原則3章以下。
• 章番号の事前特定: task category から読むべき章番号を特定してから Read する (CD-005)。
• メタSkill量産系の追加選定: 要求に skill creator / rubric / governance / script / hook / subagent / dogfooding / 再現性 が含まれる場合、26/27/28章を優先候補に加える。3章上限を超える場合は、基礎章を references/build-steps.md の既読要約で代替し、26/27/28章を正本として読む。
• L1 ドメイン rubric の解決: brief.domain が指定されている場合、creator-kit/config/rubric-registry.json から該当 domain の L1 rubric パスを引き、DOMAIN_RUBRIC_REFS 環境変数に空白区切りで詰める。これが Step 5 の assign-evaluator 呼出時に --rubric-refs へ append される（設計書29、append-only）。未指定なら L0+L2 のみで採点（L1 スキップ）。
• 量産基盤の文脈選択: 要求に skill creator / 量産 / 再現性 / rubric合成 / output routing / adapter / 類推理解 / テンプレート変数が含まれる場合は、task category を skill-factory-reproducibility にし、設計書29/30/31章と references/skill-factory-reproducibility.md を読む。3章上限を超える基礎章は references/build-steps.md の既読要約で代替する。

# brief.domain → L1 rubric 解決
DOMAIN="$(python3 -c "import json,sys; d=json.load(open('eval-log/skill-brief.json')); print(d.get('domain',''))")"
if [ -n "$DOMAIN" ]; then
  REGISTRY="${RUBRIC_REGISTRY_PATH:-creator-kit/config/rubric-registry.json}"
  DOMAIN_RUBRIC_REFS="$(python3 -c "
import json, sys
reg=json.load(open('$REGISTRY'))
print(' '.join(r['rubric'] for r in reg.get('rubrics',[]) if r['domain']=='$DOMAIN'))
")"
  export DOMAIN_RUBRIC_REFS
fi

Step 2: テンプレ展開（create）/ 既存読込（update）

kind → template 選択表（COMPOSER_MODE=template の場合）:

kind / role_suffix	旧テンプレ (Phase 0)	atomic combinator (Phase 1)
run (workflow)	templates/run.md	_base.md + with-run.patch
run (agent-team 複合)	templates/agent-team.md	with-run.patch + with-subagent.patch
run (orchestrator 複合)	templates/orchestrator.md	with-run.patch + with-subagent.patch×N
run (hook-integrated 複合)	templates/hook-integrated.md	with-run.patch + with-hooks.patch
ref	templates/ref.md	_base.md + with-ref.patch
assign + role_suffix=generator	templates/assign-generator.md	with-assign-generator.patch (+ with-evaluator.patch)
assign + role_suffix=evaluator	templates/assign-evaluator.md	with-assign-evaluator.patch
wrap	templates/wrap.md	_base.md + with-wrap.patch
delegate	templates/delegate.md	_base.md + with-delegate.patch

COMPOSER_MODE="atomic" を選択した場合は kind-specific combinator を必ず 1 つ適用し、flag combinator を 0〜N 個重ねる（順序固定: kind → flag）。詳細は templates/combinators/README.md。

create モード:

OS判定プリアンブル（設計書22）:

!`uname -s 2>/dev/null || ver`

<important if="os=mac,os=linux"> ```bash # パス解決ロジックを外部スクリプトに移譲 (300行 cap 対策) # SKILL_DIR / OUT_BASE を確立する source creator-kit/scripts/resolve-skill-dirs.sh mkdir -p "$OUT_BASE/$SKILL_NAME" python3 "$SKILL_DIR/scripts/render-frontmatter.py" \ --name "$SKILL_NAME" --kind "$KIND" \ --brief eval-log/skill-brief.json \ --template "$SKILL_DIR/templates/${KIND}.md" \ > "$OUT_BASE/$SKILL_NAME/SKILL.md" ``` </important> <important if="os=windows"> ```powershell # Windows経路: PowerShell 5.1+ で resolve-skill-dirs.ps1 を dot-source . .\creator-kit\scripts\resolve-skill-dirs.ps1 New-Item -ItemType Directory -Force -Path "$env:OUT_BASE\$env:SKILL_NAME" | Out-Null python "$env:SKILL_DIR\scripts\render-frontmatter.py" ` --name "$env:SKILL_NAME" --kind "$env:KIND" ` --brief eval-log\skill-brief.json ` --template "$env:SKILL_DIR\templates\$($env:KIND).md" ` | Out-File -Encoding utf8 "$env:OUT_BASE\$env:SKILL_NAME\SKILL.md" ``` </important> <important if="os=unknown"> OS判定に失敗した。`ref-cross-platform-runtime` のフォールバック動線に従い、 ユーザーに OS (macOS / Windows / Linux) を確認してから対応分岐に進むこと。 </important>

update モード (CD-002):

# 既存SKILL.mdを読み込み、findingsを差分適用する
# 1. 既存ファイルをバックアップ
cp "$OUT_BASE/$SKILL_NAME/SKILL.md" "$OUT_BASE/$SKILL_NAME/SKILL.md.bak"
# 2. findingsに基づき Edit で差分適用（新規作成しない）
# 3. validate-frontmatter.py で整合性確認

Step 3: 補助ファイル生成

• run系: templates/, scripts/, examples/
• ref系: references/articles-full.md 等の長文置き場
• assign系: references/rubric.json, scripts/render-findings-score.py
• いずれも本文100行超なら references/ に追い出す
• references/ は skill-build-trace.json の source_docs / doc_coverage に対応付ける
• context予算: このステップで読む設計書は11章のみ。

Step 3.5: 再現性トレース生成

references/build-steps.md#reproducibility-trace の schema に従い、以下を eval-log/skill-build-trace.json に保存する:

• design_model: 01章5要素（Intent / Contract / Boundary / Execution / Feedback）
• context_map_decision: resource-map が選んだ task category / selected_docs / 理由
• build_flow_coverage: 01a Step 1〜9 の PASS/FAIL と証跡パス
• doc_coverage: 02 / 03 / 04 / 05 / 06 / 07 / 08 / 09 / 10 / 11 / 13 / 14 / 15 / 16 / 26 / 27 / 28 / 29 / 30 / 31 / 32 / 33 / 34 / 35 章の設計判断をどこへ反映したかの PASS/FAIL と証跡パス
• layer_decisions: Skill / Subagent / Hook / MCP / CLI / script の採否理由、deterministic判定、fallback、依存方向、macOS stdlib 適合
• variant_support: run/ref/assign/wrap/delegate と role-suffix の適用可否
• pattern_decisions: pattern_refs の採否、量産対象パターン、再利用先、negative cases
• script_execution_model: 28章に基づく script 種別、実行コンテキスト A-E、優先順位、権限境界、frontmatter 状態
• governance_model: 27章に基づく rubric version/hash、提案要否、影響評価、役割分離、猶予条件
• dogfooding_model: 26章に基づく artifact 化、fork evaluator、再帰チェック、eval-log 出力先
• reproducibility_gates: lint / evaluator / elegant-review / governance の結果
• rubric_composition_model: 設計書29に基づく L0/L1/L2 rubric_refs、合成順序、merge_strategy、conflict_policy、hash 証跡
• paradigm_analogy_model: 設計書30に基づく既存パラダイム類推、適用限界、最終配置判断
• output_routing_model: 設計書31に基づく task_kind、payload schema、route、adapter registry、fallback、secret境界
• implementation_ledger_model: 設計書32に基づく manifest登録、正本/派生、残課題、C1-C4判定の証跡
• change_governance_model: 設計書33に基づく P0-P3分類、approval、cooldown、blast radius、changelog の証跡
• plugin_boundary_model: 設計書34に基づく plugin境界、外部参照棚卸し、Phase gate、移行禁止条件の証跡
• meta_harness_model: 設計書35に基づく observables、ログスキーマ、hook opt-in、再現性しきい値の証跡
• variable_contract: 具体値からテンプレート変数への写像、既定値、必須性、不適用条件、source_trace

Step 4: 命名・構造Lint

python3 creator-kit/scripts/lint-skill-name.py "$OUT_BASE/$SKILL_NAME/SKILL.md"
python3 creator-kit/scripts/lint-skill-description.py "$OUT_BASE/$SKILL_NAME/SKILL.md"
python3 creator-kit/scripts/lint-skill-tree.py "$OUT_BASE/$SKILL_NAME"
python3 creator-kit/scripts/validate-frontmatter.py "$OUT_BASE/$SKILL_NAME/SKILL.md"
python3 creator-kit/scripts/lint-script-frontmatter.py "$OUT_BASE/$SKILL_NAME"
python3 "$SKILL_DIR/scripts/validate-build-trace.py" eval-log/skill-build-trace.json

ここでの lint は manual-preflight とし、28章の A/B 実行禁止に該当する強制 gate とは呼ばない。最終強制は Hook/CI の enforced-hook-ci で同じ検査を再実行する。

6つすべて exit 0 でなければ Step 2 または Step 3.5 へ戻る。

Step 5: フォーク評価

assign-skill-design-evaluator をforkで呼び出し、rubric採点:

Skill(assign-skill-design-evaluator) target=$OUT_BASE/$SKILL_NAME

出力JSON:

{"rubric_id":"skill-design","rubric_version":"1.0.0","score":N,"findings":[...]}

評価時は skill-build-trace.json も対象に含め、01/01a の正本フローに未対応の Step があれば C2 漏れとして扱う。メタSkill・rubric・script・hook を含む場合は、26/27/28章の trace 欠落を C2 漏れ、rubric自己編集や実行経路矛盾を C1/C4 失敗として扱う。

Step 6: ゲート判定

• score >= 80 かつ high=0 → 完了
• それ以外 → findings を本文に反映 → Step 4 へ戻る（最大3周）

Step 7: subagent自動生成と検証（--with-subagent 指定時のみ）

--with-subagent フラグが指定された場合に実行する (PF-G3-001: 条件明確化):

# Step 2 で確定した $SKILL_DIR / $OUT_BASE を再利用 (self-relative + fallback)。
python3 "$SKILL_DIR/scripts/build-subagent.py" \
  --skill-name "$SKILL_NAME" \
  --skill-md "$OUT_BASE/$SKILL_NAME/SKILL.md" \
  --output-dir .claude/agents/ \
  --model "${MODEL:-opus}"
python3 creator-kit/scripts/lint-skill-description.py ".claude/agents/$SKILL_NAME-subagent.md"

SKILL.md frontmatter と本文の目的・手順から .claude/agents/<skill-name>-subagent.md を派生し、派生物も lint 対象にする。詳細は references/build-steps.md#h2-subagent-生成の詳細実装。

Step 8: evaluator ペア自動生成（--with-evaluator 指定時 または brief.generate_pair_evaluator=true）

generator として作った skill に対し、対称な evaluator を同時生成して 孤児 evaluator / 孤児 generator を防ぐ。公式CLIは render-frontmatter.py --out --pair --rubric-refs とする。詳細手順は references/build-steps.md#h5-evaluator-ペア生成。

Step 9: Hook 配線自動生成（--with-hooks 指定時 または brief.hook_events 非空）

Hook 統合スキルの場合、scripts/hook-<name>-<event>.py スケルトンと settings.json マージ案を生成する。settings.json への自動 merge は行わず、人間承認後の手動 merge とする。詳細手順は references/build-steps.md#h6-hook-配線生成。

配置先（plugin 移行ロードマップ準拠）

| フェーズ | 出力先 | 正本 | | 現在（Phase 0 未完了） | creator-kit/skills/<skill>/SKILL.md | creator-kit/skills/ | | Phase 0 完了後 | plugins/<plugin-name>/skills/<skill>/SKILL.md | plugins/<name>/ |

• 正本/派生: Phase 0 完了後、.claude/skills/<skill>/ は plugins/*/skills/ への symlink 経由派生。直接書き込まない
• name: には plugin 名を含めない: kebab-case の Skill 名のみ。所属 plugin は配置パスで表現（06章第17条）
• 詳細: 34章 § plugin 物理レイアウトと symlink 戦略

Gotchas

• frontmatter順序事故: disable-model-invocation: true と user-invocable: true の共存は手動呼び出し専用の珍しい構成。禁止ではないが、意図を本文に明記する。
• description長文化: 動作詳細を書くと invocation時のtoken浪費（08章）。
• ref系のbody肥大: ref-*はSKILL.md本文をサマリに留め、原文は references/。300行制約はSKILL.md本文のみに適用。
• scripts内のyaml import禁止: stdlibだけで簡易パーサを書く（28章）。
• fork評価の自己採点禁止: 同じcontextで採点するとGoodhart罠（09章）。
• update時の全書き換え禁止 (CD-002): --mode update ではEditで差分適用のみ。Writeで上書きしない。
• 全章一括ロード禁止 (CD-005): token超過を防ぐため、各Stepで必要な章だけを Read する。

Additional Resources

• references/design-docs-index.md — 設計書00〜35への索引
• references/resource-map.yaml — task category → 読む設計書の決定論的map
• references/build-steps.md — 詳細手順、再現性trace schema、02/03/04 coverage
• templates/ — kind別雛形
• examples/minimal-ref.md, examples/workflow-with-evaluator.md — 完成例
• scripts/render-frontmatter.py, scripts/validate-naming.py, scripts/validate-build-trace.py
• 共通lint: scripts/lint-skill-name.py 他
• manifest登録案: scripts/build-manifest-registration-plan.py