はじめに
こんにちは。株式会社シーイーシーのAWSコミュニティチームです。
今回は、2026 Japan AWS Jr. Championsの長井崇文が執筆します。
Kiroは、AWSが提供するAIを活用した開発環境で、仕様の整理からコード、ドキュメント、テストの作成まで、ソフトウェア開発を支援します。
その機能の一つであるAgent Skills（以下、スキル）は、特定の作業に必要な手順、参照資料、スクリプトなどをまとめ、Kiroで再利用する仕組みです。
依頼内容に応じて自動的に選択されるほか、明示的に呼び出すこともできます。
スキルはGitで管理し、チームで共有できます。
一方で、チーム全員に影響するため、変更しにくいことや、個人で試した改善がチームに広がらない、といった課題が生じます。
本記事では、スキルをチームで使っている方に向けて、個人検証とレビューを通じて、チーム共通のスキルを定期的に見直す運用方法を紹介します。
前提：スキルのアンチパターン
Kiro公式の指針では、利用場面を具体的に説明し、スキルを簡潔に保ち、詳細資料を分離することが推奨されています。
これらも参考に、今回の運用で避けたい状態を整理します。
- 過剰な記述：一つのスキルに無関係な作業や、長い参考資料まで詰め込む
- 記述不足：必要な前提や、手順を採用した理由が記載されておらず、AIの推測に頼る
- 曖昧な利用場面：いつ使うスキルなのかが分からず、選択されない、または無関係な作業に対して選択される
- 重複・矛盾：同じ手順が複数のスキルにあり、内容が一致していない
- 古い手順の放置：実コードや開発環境が変わっても、以前のコマンドや参照先を残し続ける
スキルは、必要な情報を過不足なく、かつ最新の状態に保つことが重要です。記述量だけで判断せず、実際に使用して見直します。
背景：なぜ、Gitで共有するだけでは更新が進まなかったのか
私たちのチームでも、プロジェクト共通のスキルをGitで管理していました。
開発が進むにつれて実コードや現在の運用との間に差が生じても、変更するとチーム全員へ影響するため、更新されにくくなっていました。
チームで共有のスキルの見直しに向けて各チームメンバーの.kiroを比較し、整理しました。
共有するスキルも、その時点で完成とすれば、同じように更新が滞りかねません。必要なのは、チームで追加・変更・削除を判断できる仕組みだと考えました。
以降では、チームでスキルを育てるための運用を4つの段階で説明します。
1. チーム共通のスキルを変える前に、個人で試す
チーム標準では、Steeringなどの個人検証用ファイルをtesting.local.mdのような名前にし、.gitignoreで除外します。
一方、スキルはSKILL.mdを含むフォルダー単位で構成するため、個人検証用のフォルダーごと除外します。
以下は、Steeringとスキルの構成例です。
.kiro/
├─ steering/
│ ├─ product.md # チーム共通
│ └─ testing.local.md # 個人検証用・Git管理対象外
├─ skills/
│ ├─ implementation-completion/ # チーム共通
│ │ └─ SKILL.md
│ ├─ propose-kiro-change/ # チーム共通・変更提案用
│ │ ├─ SKILL.md
│ │ └─ references/
│ │ └─ change-proposal.md # 提案テンプレート・レビュー観点
│ └─ implementation-completion-local/ # 個人検証用・Git管理対象外
│ └─ SKILL.md
└─ .gitignore
個人検証用のSteeringはファイル名に.localを付けます。一方、スキルはSKILL.mdというファイル名が決められているため、フォルダー名の末尾に-localを付けます。
※ .localと-local：共有対象を判別するために設けたチーム独自の命名規則です。
次は、.kiro/直下の.gitignoreに設定した除外ルールです。
# Steeringなどの個人検証用ファイル
**/*.local.*
**/.local.*
# 個人検証用スキル
skills/*-local/
.gitignoreと.kiroignoreは用途が異なります
-
.gitignore：個人検証用のファイルやフォルダーをGitの管理対象から除外するための設定 -
.kiroignore：指定したファイルやフォルダーをKiroから参照されないようにするための設定
.gitignoreへ追加しても、Kiroからの読み取りやスキルの自動選択は無効になりません。また、すでにGitで管理しているファイルは、後から.gitignoreへ追加しただけでは除外されません。
2. 試した結果を添えて提案する
個人で有用だったスキルでも、そのまま全員の作業に合うとは限りません。
チームへ提案するときは、SKILL.mdをただ共有するのではなく、変更理由と確認結果をPRに添えます。
| 残す情報 | 記載する内容 |
|---|---|
| 解決したい課題 | どの作業で困り、なぜ手順を追加・変更するのか |
| 利用する場面 | 開始時に必要な情報、対象外の作業、期待する成果物 |
| 確認結果 | どの依頼・作業差分で試してどう動いたか、何がまだ未確認か |
| 変更の影響 | 既存のスキルやチーム規約との重複・矛盾、必要な実行環境 |
| 採用後の確認方法 | 確認する担当・時期、次の作業で確かめること、見直す条件 |
「便利だった」という感想だけでなく、ほかのメンバーが採否を判断できる材料をそろえるためです。
AIには、実際の差分や試行結果を渡し、変更理由の整理を補助させます。
/propose-kiro-changeはチーム独自のスキルです
Kiroが標準で提供するコマンドではありません。本記事で紹介する運用を支援するため、チームで作成しました。
チームで共有する標準として、この/propose-kiro-changeを用意しました。
対象の差分と試行結果から変更案・影響・未確認事項を整理し、共有ファイルの変更前に人による承認を求める手順にしています。
主な手順はSKILL.mdに、提案テンプレートと詳細なレビュー観点はreferences/change-proposal.mdに置き、必要な場面で参照するよう指示しています。
3. チームレビューを続けられる形にする
今回の運用で最も負担が大きいのは、チームレビューです。
スキルはコードのように、コンパイルや自動テストだけで正否を判断できません。
一方で、文章をコード以上に細かくレビューすると、表現の好みについての議論が増え、更新が再び止まりやすくなります。
そこで、表現の好みを一行ずつ確認するのではなく、その手順が必要な場面で役立ち、意図しない場面に悪影響を及ぼさないかを基準にします。
レビュー基準
- チームに共通する課題への対策か
- 手順を追加・変更する理由が明記されているか
- 利用する場面、必要な入力、期待する出力、完了条件が明確か
- 既存のスキル、チーム規約、実コードと重複・矛盾していないか
- 対象となる依頼で意図した結果が得られるか
- 無関係な依頼で誤って選ばれず、必要な確認や人による承認が維持されるか
- 不要になった場合の削除・切り戻し条件があるか
レビューの負担を抑える工夫
- 共通の提案テンプレートを使い、前節の項目をPRへ記載する
- 表記だけを議論せず、Kiroの動作や判断が変わる部分を優先する
- レビュー担当者と利用者を明確にし、全員が同じ内容を重ねて確認しない
- ファイルの重複・矛盾・参照切れを確認する静的レビューと、実際の依頼で確認する動作レビューを分ける
AIには、既存ファイルとの重複や参照切れ、レビュー観点の確認を補助させます。
ただし、提案を自動採用せず、最終的な採否は人が変更理由・差分・試行結果を確認して決めます。
4. 定期的に.kiroを持ち寄り、見直す
合意した内容をチーム共通のスキルへ反映したら、重複した個人検証用スキルは本人の確認のもとで整理し、実際の開発で意図どおり使えるかを確認します。
ただし、採用時に適切だった手順も、そのまま使い続けられるとは限りません。定期的に見直す理由は、主に次の3つです。
- 利用状況の変化：使われなくなった手順や、個人の中にとどまる改善を把握するため
- 開発環境の変化：実コード、コマンド、参照資料と手順のずれを確認するため
- モデルや推奨手法の変化：スキルの書き方や情報の渡し方に関する知見が更新され、以前の制約や情報量が現在も適切とは限らないため
以下はClaude Codeの事例です
AnthropicによるClaude Codeの解説を、コンテキスト設計を見直す事例として参照しています。Kiroの仕様や公式見解を示すものではありません。
同記事では、モデルの進化に合わせて、過剰な制約や重複した指示を整理する考え方が示されています。
スキルも簡潔に保ち、詳細な情報は必要な場面で参照する構成が紹介されています。
これは「丁寧に書く必要がなくなった」という意味ではなく、チーム固有の知識は残し、詳細は必要に応じて参照できるようにするという見直しです。
見直す際は、各メンバーの.kiroの構成と、共有可能な内容を持ち寄る方法を推奨します。
Gitで共有しているスキルだけでなく、個人で試した変更も並べることで、対話につなげます。
まとめ
スキルは、Gitで共有して終わりではありません。
チームで定期的に対話し、実際の動作を確かめながら、育てていくものだと考えています。
-
.kiroの構造を把握し、共有範囲・参照先・変更の影響を理解する - 個人で試した工夫を持ち寄り、根拠を添えてチームでレビューする
- 定期的に見直し、追加・修正・統合・削除を判断する
次回の振り返りで、各自が使用しているスキルを一つずつ持ち寄り、違いを確認するところから始めてみてはいかがでしょうか。
※本記事は2026年9月時点の情報に基づいて執筆しています。