Kongyo Skill Creator

kongyo 系 skill の強みは「知識の説明」ではなく「その場で動ける運用メモ」にある。最初の 1 画面で何をすればいいかが分かり、分岐基準と失敗時の戻り方が見え、必要なら references/ と assets/ に深掘りできる形へ整える。新規作成や大きな変更では、skill もコードと同じく「失敗例で検証してから直す」対象として扱う。

いつ使うか

• 新規 skill を作るが、実行手順・判断基準・落とし穴まで含めたいとき
• 既存 skill が説明中心で、現場でそのまま使えないとき
• 複数の skill を同じ書き味に寄せたいとき
• description の trigger、section 順序、テンプレ資産の切り出し方を見直したいとき
• 新規 skill や重要 skill を、subagent シナリオで検証してから出したいとき

使わない場面:

• 一回限りのメモ
• API 仕様を保管するだけの資料
• 既に短く完結していて、分岐も再利用資産もない skill

クイックスタート

1. 入力の形を確認する。実ファイル、貼り付け本文、箇条書きメモのどれでもよい。
2. ## モードを決める の表で new / refactor / standardize / review を 1 つ選ぶ。
3. ## 必要入力 の不足を埋める。不明な値は推測で固定せず、placeholder と確認事項に回す。
4. ## 出力契約 と ## 出力テンプレート に沿って、SKILL.md 草案またはレビュー結果を出す。
5. 新規作成、大幅変更、discipline-enforcing skill なら ## 検証サイクル で失敗シナリオと再評価を設計する。
6. 最後に references/review-checklist.md の Quality Gate で自己採点する。

必要入力

モードを決める

最初に読むもの

• references/kongyo-skill-patterns.md

kongyo 系 skill を 3 archetype に分類している。まずこれで寄せる型を決める。

• references/review-checklist.md

仕上げ前の品質ゲート。trigger 明確性、初速、分岐、コピペ性、事故防止を採点する。

• references/skill-tdd-and-discovery.md

新規作成、大幅変更、description 見直し、subagent 検証が必要なときだけ読む。

出力契約

最低でも次を満たす。

必要に応じて次も追加する。

• references/: variant ごとの詳細、長い API/CLI 補足、評価軸、比較表
• assets/: 雛形ファイル、最小プロジェクト、設定例、画像・アイコン
• scripts/: 同じコードを何度も書くか、手動では壊しやすい処理があるとき

Archetype を決める

primary archetype を 1 つ決めてから書く。hybrid は許容するが、初速を支配するのは 1 つに絞る。

具体例は references/kongyo-skill-patterns.md を読む。

Workflow

1. ソースを監査する

次を抜き出す。

• 誰が何を終えるための skill か
• 最短成功パスは何か
• どこで判断が分岐するか
• 何を間違えると痛いか
• 何を assets/ や references/ に切り出せるか
• 不明な固有値を placeholder にするか、確認事項に回すか
• どんな状況で agent が失敗・合理化しそうか

1. primary archetype を決める

Operations / Practice / Meta のどれが中心かを先に決める。全部入りにしない。

1. `SKILL.md` / `references/` / `assets/` の境界を切る

• SKILL.md: すぐ動くための手順、判断、注意点だけ残す
• references/: variant 詳細、長い比較表、評価軸、公式情報の要約
• assets/: そのままコピーしたい雛形や最小構成
• scripts/: deterministic にしたい処理だけ

1. frontmatter を先に確定する

description は trigger-only にする。 Use when <task>, <symptom>, or <decision point>.

悪い例: XX を設定し、A を確認し、B を修正する runbook 良い例: Use when 新規導入、既存設定の修正、または failure 原因調査を行うとき。

1. 先頭 1 画面を作る

以下を優先順に置く。

• ## いつ使うか
• 使わない場面
• quickstart か minimal workflow
• 必要入力 / 前提環境

抽象的な背景説明はこの後ろに回す。

1. 分岐と判断基準を書く

branch が 2 つ以上あるなら、table か if ... then ... を必ず入れる。 判断が暗黙だと skill は trigger しても実行で詰まる。

1. コピペ資産を置く

次のどれかを必ず 1 つ以上用意する。

• コマンド列
• dispatch prompt
• 設定ファイル全文
• 雛形 SKILL
• 変更提案フォーマット

placeholder を使うなら、何に置換するかも 1 行で明記する。 資産の中に fenced code block を含めるなら、外側は 4 backticks 以上にして Markdown が壊れないようにする。

1. 落とし穴と戻り方を書く

気をつける だけで終わらせない。 誤り -> 実害 -> 回避策 か 症状 -> 原因 -> 打ち手 で書く。

1. 仕上げを検査する

references/review-checklist.md で採点する。

検証サイクル

新規 skill、大幅変更、discipline-enforcing skill は、読むだけのレビューで出さない。subagent が使えるなら、最低 1 本は「実際に使う」シナリオで検証する。

検証で失敗したら、失敗内容をそのまま潰す最小修正だけを入れる。詳細な scenario 設計、合理化表、RED-GREEN-REFACTOR の進め方は references/skill-tdd-and-discovery.md を読む。

不足情報の扱い

• 命名規則、承認者、CLI、DBMS、framework などの固有値が無いときは、<PLACEHOLDER> にして置換ルールを書く
• 一般化してよい値は一般化する。例: DBMS 不明なら PostgreSQL 固有構文を避け、EXPLAIN など共通概念に寄せる
• references/ や assets/ は、ユーザーがファイル作成を求めていない場合は「切り出し候補」として示す

出力テンプレート

new / refactor

---
name: <skill-name>
description: "Use when <task>, <symptom>, or <decision point>."
---

# <Skill Title>

## いつ使うか

- <trigger 1>
- <trigger 2>

使わない場面:
- <out of scope>

## クイックスタート / 最短成功パス

1. <first action>
2. <decision or verification>
3. <final output or handoff>

## 必要入力 / 前提環境

| 入力 | 必須 | 不足時の扱い |
|---|---|---|
| <input> | 必須 | <ask / placeholder / skip> |

## Decision Table

| 状況 | 次の操作 |
|---|---|
| <condition> | <action> |

## コピペ資産

<command / prompt / checklist / file template>

## Failure Handling

| 症状 | 原因 | 打ち手 |
|---|---|---|
| <symptom> | <cause> | <action> |

## 検証計画

- Scenario: <agent がこの skill を実際に使う現実的な状況>
- Expected failure without skill: <baseline で起きそうな失敗>
- Pass condition: <成果物が満たす条件>

review

## 現状評価

<合格 / 要修正 / 提案不要>。<理由 1-2 文>

## Checklist 採点

| 軸 | 点 | 理由 |
|---|---:|---|
| Trigger clarity | <0-2> | <reason> |
| First-screen success path | <0-2> | <reason> |
| Inputs / prerequisites | <0-2> | <reason> |
| Decision support | <0-2> | <reason> |
| Copy-paste assets | <0-2> | <reason> |
| Failure handling | <0-2> | <reason> |
| Progressive disclosure | <0-2> | <reason> |
| Fidelity | <0-2> | <reason> |
| Validation readiness | <0-2> | <reason> |

## 最小修正案

| 変更箇所 | 修正内容 |
|---|---|
| `description` | <trigger-only に直し、workflow 要約を消す> |
| body | <first-screen / decision / template / failure handling の不足を埋める> |
| validation | <必要なら scenario と pass condition を追加する> |

## 改善パッチ案

<貼り付け可能な差分または置換案>

記述ルール

• 理屈より先に操作を書く
• 見出しは 読む順 = 作業順 に寄せる
• 断定できることは断定する
• description は起動条件だけを書く。手順や workflow を要約しない
• 一般論より固有名詞、コマンド、ファイル名、しきい値を優先する
• テンプレート内に三連バッククォートを含める場合、外側 fence は四連バッククォート以上にする
• 例は少なくてよい。使える 1 例を、複数の薄い例より優先する
• section が長くなったら要約だけ SKILL.md に残し、詳細は references/ に逃がす
• 複数 variant があるなら対称的な section を並べるより、decision table で入口を一本化する
• 関連 skill は「次に何を読むべきか」が自然なものだけ残す

Quality Gate

references/review-checklist.md の合格条件を満たすまで出さない。

• 合計 14/18 以上
• Trigger clarity, First-screen success path, Decision support, Failure handling の 4 軸で 0 点を出さない
• references/ や assets/ を追加した場合は、SKILL.md から直接たどれる状態にする
• 新規、大幅変更、規律を守らせる skill では検証シナリオか検証結果を示す

Red Flags

• description が「ガイド」「ベストプラクティス」だけで終わっている
• description が手順や workflow を要約していて、本文を読まずに動けてしまう
• quickstart が理屈の後ろに埋もれている
• branch があるのに decision table がない
• テンプレが抽象的で、コピペしても動かない
• テンプレ内テンプレの code fence が同じ backtick 数で、Markdown として閉じ位置が崩れる
• 「明らかに分かるから検証不要」として、使うシナリオを走らせていない
• references/ に逃がしたのに SKILL.md から読みに行く条件が書かれていない
• 落とし穴が 注意する 確認する で終わる
• archetype を混ぜすぎて、最初の見出し順が作業順になっていない