Kiro Skills入門 — 「AIオンボーディング生成Skill」でプロジェクト参画を自動化する | Tech Blog

/generate-onboarding と呼ぶだけで、AIがプロジェクトの文脈を構造化する

はじめに
Skillsとは
実践：オンボーディング生成Skillを作る
実演：災対バックアップ基盤での使用例
Skill × Steering の全体フロー
ワークスペース vs ユーザーレベル：Skillをどこに置くか
Steering側の設計：自動読み込み vs 手動読み込み
トークン効率の設計思想
公式機能との違い：「Generate project steering documents」
業界の動向：AIにプロジェクト文脈を渡す取り組み
応用Skill：人間用オンボーディングも生成する
Before/After
よくある失敗パターン
まとめ

1. はじめに

プロジェクトに途中参画する。過去の設計書、議事録、仕様書が散在している。「まず資料を読んで全体像を把握してください」と言われるが、読み切るのに時間がかかります。

これは人間の話ですが、同じ問題がAIでも起きます。

1-1. AI駆動開発における新しい課題

Kiroやコーディングアシスタントを使い始めると、すぐに気づくことがあります。

AIはプロジェクトの文脈を知らない。

用語の意味、アーキテクチャの全体像、「なぜこの設計にしたのか」という経緯を知らないまま、AIにコードを書かせたりレビューさせたりしても、なかなか精度が上がりません。的外れな提案が返ってくることも多いです。

人間なら1ヶ月かけて資料を読みこんで「立ち上がる」。AIにも同じことが必要ですが、コンテキストウィンドウに過去資料を全部流し込むのも現実的ではないです（容量に制約があるので）。

1-2. 今回のアプローチ

「資料を読んで構造化する手順」をSkillにする。

Skillは「汎用的なやり方」を持ち運ぶ仕組みです。プロジェクトが変わっても/generate-onboardingと呼べば同じ手順でオンボーディング用コンテキストが生成されます。

生成された結果（プロジェクト固有の知識）は、Steeringに配置してAIに常時適用します。

ここで「Steering」「Skill」「トークン」など聞き慣れない用語が出てくるので、先に整理します。

用語	意味
Steering（ステアリング）	Kiroに「このルールを常に守ってね」と伝える設定ファイル。.kiro/steering/に置くと、チャットのたびに自動でAIに読み込まれる
Skill（スキル）	Kiroに「この手順でやってね」と伝える手順書ファイル。チャットで/スキル名と打った時だけAIに読み込まれる
トークン	AIが一度に処理できるテキスト量の単位。日本語1文字≒1.5トークン。上限があるため、AIに渡す情報は簡潔な方がいい
コンテキスト	AIが「今回の会話で知っていること」の総体。Steeringの内容やチャット履歴がここに入る

これを踏まえて、今回のアプローチの全体像です:

Skill = やり方（汎用）、Steering = 知識（固有）。この使い分けが今回のポイントです。

2. Skillsとは

2-1. Steeringとの違い

本シリーズの第2回・第4回・第6回ではステアリングファイルを紹介しました。ステアリングは「自動的に適用されるルール」。Skillsは「手動で呼び出す手順・知識」です。

観点	Steering	Skills
適用タイミング	自動（毎回のチャットで常時適用 / inclusion: always）	手動（/スキル名と打った時だけ）
置くべきもの	ルール・制約・固有知識	手順・やり方・テンプレート
トークンコスト	毎回消費される	呼び出した時だけ消費
配置場所	.kiro/steering/（プロジェクト内）	.kiro/skills/（PJ内）or ~/.kiro/skills/（PC全体）
Git管理	✅	✅（PJ内）/ ❌（PC全体）
持ち運び	リポジトリに紐づく	PC全体に置けば、どのPJでも使える
比喩	就業規則（常に適用）	手順書の棚（必要時に引き出す）

※ ~/.kiro/skills/ の ~ はホームディレクトリ（Windowsなら C:\Users\ユーザー名\.kiro\skills\）を意味します。ここに置いたSkillはどのプロジェクトでも使えます。

2-2. なぜ「やり方」をSkillにするのか

「プロジェクト資料を読んで構造化して」というプロンプトは、プロジェクトが変わっても毎回同じです。出力フォーマット（用語辞書・アーキ概要・環境構成…）も同じ。変わるのは入力（読む資料）だけ。

これは典型的な「再利用可能な手順」です。毎回プロンプトをゼロから打つのは非効率。Skillにしておけば/generate-onboardingと打つだけで、最適化されたプロンプトが展開される。

2-3. Skillファイルの構造

Skillファイルは普通のMarkdownファイルです。冒頭に「フロントマター」（---で囲った設定部分）を付け、その下に本文を書きます。

---

name: generate-onboarding

description: プロジェクト資料からAI用構造化コンテキストを生成する手順

---

（ここに書いた内容が、チャットで /generate-onboarding と打った時にAIに渡される）

name: チャットで呼び出す時の名前。/generate-onboardingのgenerate-onboarding部分
description: このSkillが何をするかの説明（Kiroがスキル一覧を表示する時に使う）

チャットに/generate-onboardingと入力すると、本文の内容がまるごとAIに渡されます。また、チャットの内容がSkillのdescriptionに一致する場合は、自動的にactivateされることもあります。

3. 実践：オンボーディング生成Skillを作る

3-1. 完成形

~/.kiro/skills/generate-onboarding/SKILL.md（ユーザーレベル = 全プロジェクト共通）:

完全版ファイル

以下は要点のみ記載します。

主要セクション構成:

セクション	内容
バイナリファイルの読み込み手順	Excel/Word/PDF → Pythonスクリプト自動生成で対応
出力先とファイル分割	5000トークン以内なら1ファイル(auto)、超えたらcore(auto)+details(manual)に分割
出力フォーマット（7セクション）	①用語辞書 ②アーキ概要 ③環境構成 ④コンポーネント ⑤制約・設計判断 ⑥スクリプト ⑦外部連携
設計方針（厳守）	テーブル/箇条書き中心。散文は避ける。コード名そのまま。core=2000〜3000トークン
生成後の確認	用語正確性、守秘情報チェック、コード名一致

ポイント:

セクション1〜5が必須、6〜7はオプション（PJの種類を問わず使える）
5000トークン超の場合は自動でcore/detailsに分割（プログレッシブローディング）
バイナリ読み込み手順を内包しているので、ステアリングがない初期状態でも自律動作する

3-2. なぜこの構成なのか

セクション1〜5が必須、6〜7がオプションにしているのは、プロジェクトの種類を問わず使えるようにするためです。

Webアプリ → 1〜5 + 7（外部API連携）
インフラ運用 → 1〜6（スクリプト一覧が重要）
組み込みFW → 1〜5（制約・設計判断が重要）
マイクロサービス → 1〜5 + 7（サービス間連携）

どんなプロジェクトでも/generate-onboarding→資料を渡す、で構造化コンテキストが出力される。

3-3. なぜバイナリ読み込み手順をSkill内に含めるのか

実際に試すとすぐ分かりますが、プロジェクトの過去資料は大半がExcelやWordです。Kiroはこれらを直接読めません。

ステアリングファイルにバイナリ読み込みルールを書く方法は第6回で紹介しましたが、/generate-onboardingを使う時点ではまだステアリングが存在しない（生成するのが目的だから）。つまりSkill自体に手順を内包しないと、初回実行時に詰まります。

Skillは「呼んだら自律的に完了まで動ける」状態に設計する。外部のステアリングやルールに依存しない自己完結性が重要です。

4. 実演：災対バックアップ基盤での使用例

4-1. 呼び出し

/generate-onboarding
以下の資料からプロジェクトコンテキストを生成してください。
docs/内のExcelファイルを全て読み込んでください。

資料がExcelだったため、AIはSkill内の「バイナリファイルの読み込み手順」に従い、自動でKIROTOOLS/read_excel.pyを生成・実行しました。人間が別途スクリプトを用意する必要はありません。

4-2. 生成結果（実際に出力された`.kiro/steering/project-context.md`を編集済み）

---

inclusion: auto

---

# プロジェクトコンテキスト: DR基盤運用改修

## 1. 用語辞書

| 略語 | 正式名称 | 説明 |

|------|---------|------|

| DR | Disaster Recovery | 災害復旧。障害時に切替える待機系 |

| ST環境 | Staging環境 | テスト実施環境 |

| MainDB | メインデータベース | 業務アプリケーション用スキーマ |

| SubDB | サブデータベース | 集計・分析用スキーマ |

| LAW | Log Analytics Workspace | ログ収集・監視サービス |

| カスタムログ | LAW カスタムログ | アプリ固有ログ定義 |

## 2. アーキテクチャ概要

- クラウド: Azure（東日本=本番, 西日本=DR）

- 主要構成要素: VM (バッチ/運用), マネージドDB, Storage, コンテナ基盤

- 通信方式: ファイル共有マウント, Blob API (CLI), VPN（保守用）

- 言語/FW: Bash, Java APサーバ, 帳票エンジン, MySQL

- 監視: LAW → カスタムログ → アラートルール → メール通知

## 3. 環境構成

| 環境 | 用途 | 命名規則 | 備考 |

|------|------|---------|------|

| 本番 (東日本) | 本番運用 | prd-vm-eastjp-01-{op/bt} | op=運用, bt=バッチ |

| DR (西日本) | 災害復旧 | prd-vm-westjp-01-{op/bt} | — |

| ST | テスト | st-vm-eastjp-01-{op/bt} | — |

## 4. 主要コンポーネント

| 名前 | 責務 | 関連パス |

|------|------|---------|

| backup_full.sh | DR フルバックアップ (MainDB) | /opt/app/infra/dump_main/ |

| backup_diff.sh | DR 差分バックアップ (MainDB) | /opt/app/infra/dump_main/ |

| backup_sub_full.sh | DR フルバックアップ (SubDB) | /opt/app/infra/dump_sub/ |

| backup_sub_diff.sh | DR 差分バックアップ (SubDB) | /opt/app/infra/dump_sub/ |

| log_rotate.sh | ログ転送及びローテート | /opt/app/common/ |

| monitor_end.sh | バックアップ終了確認（新規） | 本対応で新規作成 |

## 5. 制約・設計判断

- DR環境はテスト環境に存在しない→テストはST環境のみ

- ローテーション: cp+empty → mv+touch に変更（理由: 監視エージェントがinode追跡するため）

- フルバックアップ開始: 0:00→0:05に変更（理由: ログローテート0:00と書込競合回避）

- 終了監視: 終了ログ文字列の有無で判定（理由: シンプルさ優先）

- DB接続パスワード: RSA鍵で暗号化

## 6. 運用スクリプト/ジョブ

|-----------|---------|------------|------|

| backup_full.sh | bt | 0:05 毎日 | MainDB フルダンプ→圧縮→Storage |

| backup_diff.sh | bt | 9:00, 12:00, 15:00 | MainDB 差分ダンプ |

| backup_sub_full.sh | bt | 0:05 毎日 | SubDB フルダンプ→圧縮→Storage |

| backup_sub_diff.sh | bt | 6:00, 9:00, 12:00 | SubDB 差分ダンプ |

## 7. データフロー/外部連携

| 連携先 | プロトコル | 方向 | 内容 |

|--------|----------|------|------|

4-3. 実験結果の評価

Skillが期待通りに機能しました:

確認項目	結果
バイナリ読み込み（Excel）	✅ KIROTOOLS/read_excel.pyを自動生成・実行
inclusion: alwaysフロントマター	✅
テーブル/箇条書きのみ（散文なし）	✅
「なぜ」を含む設計判断	✅（ローテ変更理由、開始時間変更理由等）
スクリプト名そのまま記載	✅（app1050.sh等）
セクション1〜7の構造	✅ + 自発的にセクション8（タスク一覧）も追加

⚠️ 1点だけ手動修正が必要だった: 顧客を特定できる情報が一部残っていた。Skillの「生成後の確認」項目2（守秘情報チェック）は自動では完全に効かない — 人間レビューが必須です。

5. Skill × Steering の全体フロー

Day 0（参画時）:
1. リポジトリをclone
2. 過去資料を確認
3. チャットで: /generate-onboarding + 資料を渡す
4. AIがSkillの指示に従い、構造化コンテキストを生成
5. .kiro/steering/project-context.md が出来上がる
6. git add → commit → push（チーム共有）

Day 1〜（日常開発）:
- Steeringが自動適用され、AIがプロジェクトを「知っている」状態
- 追加で詳細が必要なら /generate-onboarding で追加生成
- 設計変更があればSteeringを更新

新メンバー参画時:
- git pull するだけでSteering（=コンテキスト）が手に入る
- 自分で /generate-onboarding を使う必要なし（先人が生成済み）

5-1. ポイント: Skillは「1回使えば役目を終える」

/generate-onboardingは生成時にだけ使うSkillです。生成されたSteeringが日常の会話に適用される。

Skillを毎回呼ぶ必要はありません。一度コンテキストを生成したら、あとはSteeringが自動で仕事をする。

5-2. ポイント: 生成して終わりではない — 育てるサイクル

Rahul Garg（ThoughtWorks / martinfowler.com掲載）は「自動生成して放置するな」と警告しています。Tembo社も「自動生成されたファイルは肝心なこと — 設計判断や制約 — が抜ける」と指摘しています。

今回の実験でも、生成直後のコンテキストには顧客特定情報が残っていたし、設計判断の「なぜ」が浅い箇所もありました。/generate-onboardingで生成されるのは「初版」であり、そこからチームで育てていくものです。

生成→育てるサイクル:

更新のシグナル: AIが2回同じ間違いをしたら、それが1行追加するタイミングです。「AIが間違えた」＝「コンテキストに情報が足りていない」の証拠。

コードレビューと同じ扱い: Steeringの変更はPRでレビューしてください。「この用語定義おかしくない？」「この制約もう古いよ」という指摘ができます。コードと同格で品質を担保する。

6. ワークスペース vs ユーザーレベル：Skillをどこに置くか

Skillファイルは2つの場所に置けます。置く場所によって「使える範囲」が変わります。

レベル	配置場所	使える範囲	使い方
ワークスペース	.kiro/skills/（PJフォルダ内）	そのプロジェクト内のみ	PJ固有の手順
ユーザー	~/.kiro/skills/（PC全体）	どのプロジェクトでも	汎用的な手順

※ Windowsの場合: ~/.kiro/skills/ = C:\Users\ユーザー名\.kiro\skills\

generate-onboardingはユーザーレベルに置きます。プロジェクトが変わっても同じ手順でコンテキストを生成したいので。

~/.kiro/skills/ ← ユーザーレベル（持ち運び）

├── generate-onboarding/SKILL.md ← 今回の主役。全PJで使う

├── code-review/SKILL.md ← レビュー観点（汎用）

└── incident-response/SKILL.md ← 障害対応手順（汎用）

my-project/.kiro/
├── steering/
│ └── project-context.md ← generate-onboardingで生成した結果
└── skills/
└── （PJ固有のSkillがあれば）

Skill = 汎用手順（持ち運ぶ）。Steering = PJ固有知識（リポジトリに紐づく）。

7. Steering側の設計：自動読み込み vs 手動読み込み

Steeringファイルの冒頭（フロントマター）に書くinclusion設定で、「毎回自動で読み込む」か「必要時に手動で呼ぶ」かを切り替えられます。

設定	動作	使い道
inclusion: always	毎回のチャットで常にAIに渡される（デフォルト動作）	常に知っていてほしい情報（用語、制約）
inclusion: manual	チャットで#ファイル名と打った時だけ渡される	特定作業時だけ必要な詳細情報
inclusion: auto	リクエスト内容がdescriptionに一致した時に自動で渡される	特定のコンテキストで必要な情報（name+descriptionで制御）
inclusion: fileMatch	指定パターンに一致するファイルを操作した時だけAIに渡される	特定ファイル種別の規約（例: *.tsx編集時のみReactガイドを適用）

※ always と auto の使い分け:

always: 軽い基礎情報（用語辞書、アーキ概要等、2000トークン程度）に最適。毎回確実に注入される
auto: 重い詳細情報（5000トークン超のコンテキスト全体等）に合理的。リクエスト内容がdescriptionに一致した時だけ注入されるため、トークン節約効果がある
本記事のSkillでは auto を採用: 生成コンテキストが大きくなるケースを想定し、無関係な質問時にトークンを消費しない設計としている

生成されたコンテキストが大きくなった場合の分割戦略です。

7-1. 小〜中規模（5000トークン以内）: always一本

.kiro/steering/
└── project-context.md ← inclusion: always

毎回全量注入しても問題ないサイズ。これで十分。

7.2 大規模（5000トークン超）: core + manual分割

.kiro/steering/
├── project-context-core.md       ← inclusion: always（用語+アーキ+制約。2000トークン）
├── project-context-scripts.md    ← inclusion: manual（スクリプト詳細。#で呼ぶ）
└── project-context-network.md    ← inclusion: manual（NW詳細。#で呼ぶ）

always（core）: 全会話で必要な最小限（用語辞書、アーキ概要、主要制約）
manual: 特定作業時のみ必要な詳細（#project-context-scriptsで呼び出し）

/generate-onboardingを呼ぶ際に「コンテキストが大きい場合はcore/detailsに分割して」と追加指示すれば、AIが自動で分割してくれます。]

7-3. プログレッシブローディングの考え方

この「必要な時に必要な情報だけ読み込む」設計は、AI駆動開発のコミュニティでプログレッシブルールローディングと呼ばれている手法と同じ考え方です。

コンテキストウィンドウに全部入れると:

本当に必要な情報が埋もれる（注意力の分散）
トークン枠を圧迫して作業に使える余力が減る

inclusion: manualで「必要な時だけ呼ぶ」にしておけば:

普段はcore（用語と制約）だけで軽く動作
スクリプト改修の時だけ#project-context-detailsで詳細を読み込む
AIの注意力が「今必要な情報」に集中する

Skillの出力指示にこの分割ロジックを組み込んであるので、生成時点で自動的にプログレッシブローディング対応のSteeringが出来上がります。

8. トークン効率の設計思想

AIには「一度に読める文字量の上限」があります（これを「コンテキストウィンドウ」と呼びます）。Steeringに書いた内容は毎回その枠を消費するので、同じ情報をより少ない文字数で表現できれば、その分だけAIが作業に使える余力が増えます。

8-1. なぜテーブルなのか

同じ情報量で3倍以上のトークン差が出ます。ステアリングは毎回注入されるので、この差が蓄積する。

8-2. なぜ散文を避けるのか

AIは散文の「導入」「接続詞」「修飾語」にトークンを使いますが、それらは情報量としてはほぼゼロです。テーブルや箇条書きにすれば、情報密度を最大化できます。

「以下に示すように、データフローは次のようになっています：」← この1文に12トークン消費。情報量ゼロ。

8-3. なぜコード内の名前をそのまま書くのか

AIがコード修正する際、コンテキストにbackup_full.shとあればそのまま参照する。「フルバックアップスクリプト」と書くとAIがファイル名を推測する余地が生まれ、精度が落ちる。

9. 公式機能との違い：「Generate project steering documents」

Kiroには公式で「ステアリングドキュメント自動生成」機能が組み込まれています。コマンドパレットから「Kiro: Generate project steering documents」を実行すると、リポジトリ内のコードを自動探索し、以下の3ファイルを生成します。

生成ファイル	内容
product.md	プロダクトの目的、ターゲットユーザー、主要機能
tech.md	使用FW、ライブラリ、開発ツール、技術制約
structure.md	ファイル構成、命名規約、アーキテクチャ判断

9-1. 公式機能と`/generate-onboarding`の使い分け

観点	公式「Generate steering docs」	今回の/generate-onboarding
入力	コードベースを自動探索	人間が指定した資料（設計書等）
得意な場面	コードが既にあるPJ	コードが少ない参画初期
情報源	ソースコードから推論	設計書・仕様書・議事録から抽出
バイナリ対応	なし（コードのみ）	あり（Excel/Word/PDF対応）
カスタマイズ	できない（固定出力）	Skillを編集すれば自由に変更可能
持ち運び	Kiro組込コマンド	Skillファイルとして携帯

補完関係にあります。公式機能はコードからtech/structureを推定するのに強い。今回のSkillはコードがまだ少ない段階で、設計書等のドキュメントから文脈を構造化するのに強くしています。

9-2. なぜコードからの推論だけでは不十分なのか

公式機能は優秀です。でも「コードを読めば分かること」と「コードからは読み取れないこと」があります。

コードから分かること	コードからは分からないこと
使用FW・ライブラリ（package.json等）	なぜそのFWを選んだか（選定理由）
ファイル構成・ディレクトリ構造	なぜその構成にしたか（設計判断）
命名パターン（実例から推測）	明文化された命名規則（例外含む）
現在のコードの状態	過去の経緯（移行中、廃止予定、暫定実装）
依存関係	運用上の制約（RPO/RTO、容量制限、保持期間）
テストの存在有無	テスト戦略の意図（何を守りたいか）
—	用語の定義（「災対」「BT」「OP」の意味）

実際に今回の実験で生成されたコンテキストを見てください:

「ローテーション方式をcp+emptyからmv+touchに変更。理由: エージェントがinode追跡するため」
「フルバックアップ開始を0:00→0:05に変更。理由: ログローテート0:00と書込競合回避」
「DR切替は手動。理由: 自動フェイルオーバーはコスト見合わず」

これらは設計書や議事録にしか書かれていない情報です。コードを読んでも「0:05にcronが走る」という事実は分かりますが、「なぜ0:00ではなく0:05なのか」は分かりません。

AIが「backup_full.shの開始時間を0:00に変更して効率化しませんか？」と提案してきた時、コンテキストに理由が書いてあれば「書込競合が起きるので変更不可」とAI自身が判断できます。書いてなければ、人間が毎回止める必要があります。

コードは「what」を教えてくれる。設計書は「why」を教えてくれる。 AIが的確に働くには両方が必要です。

おすすめの使い方:

1. 参画直後: /generate-onboarding + 設計書 → 用語・アーキ・制約を構造化
2. コードが揃った後: 公式「Generate steering docs」 → tech.md / structure.md を自動生成
3. 両方をステアリングに配置 → AIが設計意図もコード構造も理解した状態になる

10. 業界の動向：AIにプロジェクト文脈を渡す取り組み

今回のアプローチは独自の発明ではなく、業界全体で「AIにプロジェクトの文脈をどう渡すか」が急速に標準化されている流れの中にあります。

アプローチ	提唱者	特徴
AGENTS.md	Linux Foundation傘下のAgentic AI Foundation (AAIF) が管理するオープン標準	60,000+ OSSリポジトリが採用。20+ツール対応。「エージェントのためのREADME」
CLAUDE.md	Anthropic	Claude Code固有。セッション開始時に自動読み込み
Knowledge Priming	Rahul Garg (ThoughtWorks / martinfowler.com掲載)	「AIのオンボーディング＝新人のオンボーディングと同じ」。7セクション・50行以内が目標
Context Scaffolding	Ability.ai	コンテキストの有無でAI精度が大幅に変わる。差はモデル能力ではなく情報の有無
Cursor Rules	Cursor	「Rulesはプロンプトレベルで永続的・再利用可能なコンテキストを提供する」

共通する考え方:

AIは毎回ゼロから始まる — セッション間で記憶を持たない。明示的にコンテキストを渡す必要がある
コンテキストをコードと同格で管理する — バージョン管理、PRレビュー、定期更新
散文よりコマンド — 「包括的なテスト戦略がある」ではなく「pnpm testを実行せよ」と書く
「新人に教えること」がそのままAIに渡すべきコンテキスト

Kiroのステアリング + Skillsは、この流れにおける「Kiro版の実装」です。他ツールとの違いはinclusion制御（auto/manual/fileMatch）による粒度設計と、Skillによる手順の標準化・持ち運びができる点です。

11. 応用Skill: 人間用オンボーディングも生成する

AI用コンテキスト（Steering）とは別に、人間用オンボーディングも同じ資料から生成できます。これも汎用Skillにしておけば便利です。

~/.kiro/skills/generate-onboarding-human/SKILL.md:

---

name: generate-onboarding-human

description: プロジェクト資料から人間向け段階的オンボーディングガイドを生成する

---

# 人間用オンボーディングガイド生成

ユーザーが指定する資料を読み込み、新規参画者向けの段階的学習ドキュメントを生成してください。

## 出力先

`docs/onboarding/README.md`

## 構成

### Level 0: 30秒で分かる全体像

- 1段落で「何のシステムか」「誰が使うか」「何をするか」

### Level 1: 主要コンポーネントと役割

- ASCII図で構成を可視化

- 各コンポーネントの1行説明

### Level 2: 各モジュール詳細

- FAQ形式（「○○とは何？」「なぜ○○？」）

- ADR形式（状況→決定→根拠→結果）で設計判断を記録

### 用語集

- 略語→正式名称→説明（Steeringの用語辞書と共通ソース）

## 設計方針

- 概要→詳細の段階的開示（情報過多を避ける）

- 「なぜそうなっているか」を必ず含める（ADR形式）

- 見出し・アンカーを明確に（検索しやすく）

- 図はASCII or Mermaid

11-1. AI用 vs 人間用の違い

観点	AI用（Steering）	人間用（docs/）
設計目標	トークン効率	段階的理解
構造	フラット・テーブル	Level 0→1→2
散文	避ける	OK（理解を助ける）
図	使わない（矢印テキスト）	ASCII/Mermaid活用
「なぜ」	箇条書きで簡潔に	ADR形式で丁寧に

同じ情報源から、対象読者に合わせて表現形式を変える。 AI向けは圧縮、人間向けは展開。

12. Before/After

観点	Before	After
AIへの文脈共有	毎回チャットで説明/プロンプト職人芸	Steeringで自動注入
コンテキスト生成	毎回プロンプトを考える	/generate-onboardingで即実行
プロジェクト横断	PJごとにやり方がバラバラ	Skill統一で全PJ同品質
新規参画者のAI環境	「まず資料を…」と口頭説明	git pullでSteering入手済
チーム間のAI品質差	渡す情報がバラバラ	Steering統一で全員同精度
生成物の品質	フォーマットが毎回違う	Skillで出力形式を標準化

13. よくある失敗パターン

失敗パターン	何が起きるか	対策
結果をSkillに置く	PJ固有知識なのに手動呼出が必要→忘れる	結果はSteeringに置く
手順をSteeringに置く	汎用手順が毎回トークン消費→無駄	手順はSkill(手動)に置く
全部alwaysに入れる	トークン超過で会話が狭くなる	core(auto)+details(manual)に分割
更新されないSteering	古い情報でAIが間違う	設計変更PRにSteering更新を含める
散文で書く	トークン効率が悪い	テーブル・箇条書きを徹底
Skill呼び忘れ(初回)	コンテキスト未生成で精度低い	READMEに初回手順を書く

14. まとめ

14-1. 今回構築したもの

✅ /generate-onboarding Skill（汎用・ユーザーレベル・全PJ持ち運び）
✅ 生成結果は.kiro/steering/に配置（PJ固有・auto適用）
✅ /generate-onboarding-human で人間用も生成可能
✅ Skill × Steering の使い分け原則

14-2. キーメッセージ

Skill = やり方（汎用・持ち運び）。Steering = 知識（固有・常時適用）。

この使い分けを理解すれば、どのプロジェクトに参画しても:

/generate-onboardingで構造化コンテキストを即生成
Steeringに配置してチーム共有
以降、AIがプロジェクトを「知った」状態で動作

「AIもチームメンバーである」なら、AIにもオンボーディングが必要です。Skillsはその「オンボーディング手順書」を標準化・持ち運び可能にする仕組みです。

14-3. Kiroの仕組みの使い分け全体像

仕組み	適用方法	役割	例
Steering	自動（毎回注入）	PJ固有の知識・ルール	用語辞書、アーキ概要、命名規則、制約
Skills ← 今回	手動（/で呼出）	汎用的な手順・やり方	コンテキスト生成、レビュー手順、障害対応
Hooks	イベント駆動（自動実行）	違反検出して止める	命名チェック、テスト強制、セキュリティスキャン
Power	コンテキスト連動（自動activate）	AIの能力を外部ツールで拡張	IaC検証、セキュリティスキャン

関連記事

参考リンク

サブ-ナビゲーション

カテゴリ

最近の投稿

タグ

お問い合わせ

Kiro Skills入門 — 「AIオンボーディング生成Skill」でプロジェクト参画を自動化する

目次