kongyo-skill-creator

name	kongyo-skill-creator
description	Use when authoring a new skill, refactoring an explanation-heavy skill into an executable runbook, standardizing skill structure, reviewing skill practicality, or preparing skill validation before deployment.

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 で自己採点する。

必要入力

入力	必須	不足時の扱い
対象 source	必須	skill 化する本文、既存 SKILL.md、またはメモの提示を依頼する
作業モード	推奨	## モードを決める で推定し、成果物に推定理由を書く
想定利用者 / 完了条件	推奨	誰が何を終えるための skill か を仮置きし、確認事項に残す
前提環境 / toolchain	任意	不明なら汎用 placeholder にし、固有コマンドを断定しない
既存の references/ / assets/	任意	無ければ候補だけ示し、実ファイル作成は求められた場合だけ行う
検証要否	任意	新規、大幅変更、規律を守らせる skill は検証対象として扱う

モードを決める

状況	モード	返すもの
新しい skill を作る材料だけがある	new	kongyo-style の SKILL.md 草案
既存 skill が説明中心で実行しにくい	refactor	書き換え後の SKILL.md 草案と主な変更点
複数 skill の書き味を揃えたい	standardize	共通構成、差分方針、代表テンプレ
既存 skill が実用可能か見たい	review	checklist 採点、合否、最小修正案
skill の効き方を確かめたい	validate	pressure/application scenario、期待失敗、再評価計画
source が短すぎて skill 化の価値が薄い	no-op / ask	提案不要の理由、または不足情報の質問

最初に読むもの

• references/kongyo-skill-patterns.md kongyo 系 skill を 3 archetype に分類している。まずこれで寄せる型を決める。
• references/review-checklist.md 仕上げ前の品質ゲート。trigger 明確性、初速、分岐、コピペ性、事故防止を採点する。
• references/skill-tdd-and-discovery.md 新規作成、大幅変更、description 見直し、subagent 検証が必要なときだけ読む。

出力契約

最低でも次を満たす。

項目	必須条件
Frontmatter	name は kebab-case、description だけで trigger が判断できる
First screen	先頭 1 画面で「いつ使うか」「最短成功パス」「必要入力」が読める
Decision support	分岐が 2 つ以上あるなら table または if ... then ... を置く
Reuse	コマンド、プロンプト、設定例、テンプレのいずれかを 1 つ以上置く
Failure handling	3 件以上の落とし穴、または troubleshooting を置く
Disclosure	長い詳細は references/、コピーして使う雛形は assets/ に逃がす
Discovery	description は trigger-only。workflow 要約を書かない
Validation	新規・大幅変更なら検証シナリオまたは検証結果を残す

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

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

Archetype を決める

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

Archetype	向いている skill	最初に必要なもの	典型的な追加資産
Operations	個人/チーム運用、日常手順、環境管理	前提環境、layout/table、日常フロー	command cheat sheet、troubleshooting
Practice	CLI / library / FFI / framework の実践ガイド	quickstart、原則、実例、decision table	references/ の詳細 docs、assets/ の starter
Meta	skill 作成、分類、提案、ふりかえり	分類基準、出力契約、提案テンプレ	archetype 別 template、review checklist

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

Workflow

1. ソースを監査する 次を抜き出す。

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

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

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

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

4. frontmatter を先に確定する description は trigger-only にする。 Use when <task>, <symptom>, or <decision point>.

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

5. 先頭 1 画面を作る 以下を優先順に置く。

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

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

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

7. コピペ資産を置く 次のどれかを必ず 1 つ以上用意する。

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

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

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

9. 仕上げを検査する references/review-checklist.md で採点する。

検証サイクル

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

対象	検証方法	見るもの
規律を守らせる skill	pressure scenario	agent が抜け道や合理化をしないか
実践 guide / runbook	application scenario	手順、入力、分岐、failure handling が使えるか
reference skill	retrieval scenario	必要情報にたどり着けるか、穴がないか
review だけ	static checklist	0 点軸、template 崩れ、description trap

検証で失敗したら、失敗内容をそのまま潰す最小修正だけを入れる。詳細な 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 を追加する> |

## 改善パッチ案

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

記述ルール

• 理屈より先に操作を書く
• 見出しは 読む順 = 作業順 に寄せる
• 断定できることは断定する
• 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 を混ぜすぎて、最初の見出し順が作業順になっていない