Kiro CLI v1.27 で「/agent create」が進化。カスタムエージェントの作り方を全部見せます

はじめに

こんにちは、AWS Japan でソリューションアーキテクトをしているいなりくです。

2026 年 3 月 2 日にリリースされた Kiro CLI v1.27 で、カスタムエージェントの作成体験が大きく変わりました。これまで /agent generate と /agent create に分かれていたワークフローが統合され、/agent create 一発で AI がエージェント設定を生成してくれるようになっています。

https://kiro.dev/changelog/cli/1-27/

この記事では、v1.27 の主要アップデートを紹介しつつ、カスタムエージェントの作成から設定ファイルの書き方まで一通り解説します。

この記事は Kiro CLI を使い始めた方〜中級者向けです。Kiro CLI のインストールや認証設定は完了している前提で進めます。セットアップがまだの方は「Kiro を組織で利用するためのセキュリティとガバナンス」を参照してください。

v1.27 の主要アップデート

今回のリリースには 3 つの大きな変更があります。

1. /agent create の AI アシストモード統合

以前は /agent generate で AI 生成、/agent create で手動作成と分かれていました。v1.27 からは /agent create がデフォルトで AI アシストモードになり、エージェントの説明を入力するだけで設定ファイルが自動生成されます。

> /agent create

✔ Enter agent name:  · backend-specialist
✔ Enter agent description:  · You are a specialist in backend coding practices
✔ Agent scope · Local (current workspace)
Select MCP servers (use Space to toggle, Enter to confirm): markdown-downloader (node), code-analysis (uv)

✓ Agent 'backend-specialist' has been created and saved successfully!

手動で設定ファイルを書きたい場合は --manual フラグを付けます。

> /agent create my-agent --manual

2. Granular Tool Trust（きめ細かいツール信頼設定）

ツール実行の許可を求められたとき、信頼範囲をインタラクティブに選べるようになりました。

• shell コマンド：完全一致 / 引数違いも許可 / ワイルドカード許可の 3 段階
• read / write ツール：特定ファイル / ディレクトリ単位 / ツール全体の 3 段階

3. Session Settings Tool

チャット中に設定を一時的に変更できるようになりました。モデルの切り替えや機能のトグルなど、設定ファイルを編集せずにセッション内で完結します。セッション終了時に自動リセットされます。

カスタムエージェントとは

Kiro CLI のカスタムエージェントは、特定のタスクに特化した AI アシスタントを定義する仕組みです。JSON 設定ファイルで以下を制御できます。

• 使えるツールの種類
• 許可するツール（確認なしで実行）
• 自動で読み込むコンテキスト（ファイル、スキル、ナレッジベース）
• MCP サーバーの接続先
• システムプロンプト
• 使用するモデル

エージェントの作成方法

AI アシストモード（推奨）

チャットセッション内で /agent create を実行します。

> /agent create backend-specialist -D "Backend coding specialist" -m code-analysis

主なオプション：

フラグ	説明
--directory	保存先（workspace / global / カスタムパス）
--description	エージェントの説明
--mcp-server	使用する MCP サーバー（複数指定可）
--manual	手動作成モードに切り替え
--from	既存エージェントをテンプレートとして使用

ターミナルから直接作成することもできます。

kiro-cli agent create backend-specialist

保存先の指定

--directory フラグで保存先を制御します。

値	保存先
workspace	.kiro/agents/（現在のプロジェクト）
global	~/.kiro/agents/（デフォルト）
./path or /path	任意のパス

設定ファイルの構造

カスタムエージェントの設定ファイルは JSON 形式です。ファイル名（.json を除く）がエージェント名になります。

最小構成

{
  "name": "my-agent",
  "description": "A custom agent for my workflow",
  "tools": ["read", "write"],
  "prompt": "You are a helpful coding assistant"
}

主要フィールド一覧

フィールド	必須	説明
name	-	エージェント名（省略時はファイル名）
description	-	エージェントの説明
prompt	-	システムプロンプト（インラインまたは file:// URI）
tools	-	使用可能なツール一覧
allowedTools	-	確認なしで実行を許可するツール
mcpServers	-	MCP サーバー設定
resources	-	読み込むリソース
hooks	-	ライフサイクルフック
model	-	使用するモデル ID
keyboardShortcut	-	エージェント切り替えのショートカット
welcomeMessage	-	切り替え時の表示メッセージ

各フィールドの詳細

prompt — システムプロンプト

インラインで直接書くか、外部ファイルを参照できます。

{
  "prompt": "You are an expert AWS infrastructure specialist"
}

{
  "prompt": "file://./prompts/aws-expert.md"
}

file:// URI のパス解決ルール：

• 相対パス → エージェント設定ファイルのディレクトリ基準
• 絶対パス → そのまま使用

長いプロンプトは外部ファイルに分離するのがおすすめです。バージョン管理もしやすくなります。

tools — 使用可能なツール

{
  "tools": [
    "read",
    "write",
    "shell",
    "@git",
    "@rust-analyzer/check_code"
  ]
}

指定方法のパターン：

記法	意味
"read"	ビルトインツール
"@server_name"	MCP サーバーの全ツール
"@server/tool_name"	MCP サーバーの特定ツール
"*"	全ツール
"@builtin"	全ビルトインツール

allowedTools — 自動許可ツール

確認プロンプトなしで実行を許可するツールを指定します。glob パターンに対応しています。

{
  "allowedTools": [
    "read",
    "@git/git_status",
    "@server/read_*",
    "@fetch"
  ]
}

• * は任意の文字列にマッチ
• ? は任意の 1 文字にマッチ
• 大文字小文字を区別する

allowedTools に "*" ワイルドカードは使えません。セキュリティのため、明示的にパターンを指定する必要があります。

mcpServers — MCP サーバー設定

{
  "mcpServers": {
    "fetch": {
      "command": "fetch3.1",
      "args": []
    },
    "git": {
      "command": "git-mcp",
      "args": [],
      "env": {
        "GIT_CONFIG_GLOBAL": "/dev/null"
      },
      "timeout": 120000
    }
  }
}

HTTP ベースの MCP サーバーには OAuth 設定も可能です。

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.github.com/mcp",
      "oauth": {
        "redirectUri": "127.0.0.1:8080",
        "oauthScopes": ["repo", "user"]
      }
    }
  }
}

resources — コンテキストリソース

3 種類のリソースタイプがあります。

{
  "resources": [
    "file://README.md",
    "file://.kiro/steering/**/*.md",
    "skill://.kiro/skills/**/SKILL.md",
    {
      "type": "knowledgeBase",
      "source": "file://./docs",
      "name": "ProjectDocs",
      "description": "Project documentation",
      "indexType": "best",
      "autoUpdate": true
    }
  ]
}

タイプ	読み込みタイミング	用途
file://	起動時に全文読み込み	常に必要なコンテキスト
skill://	メタデータのみ起動時、本文はオンデマンド	大量のドキュメント
knowledgeBase	インデックス化して検索	大規模ドキュメントセット

hooks — ライフサイクルフック

エージェントのライフサイクルの各ポイントでコマンドを実行できます。

{
  "hooks": {
    "agentSpawn": [
      { "command": "git status" }
    ],
    "preToolUse": [
      {
        "matcher": "execute_bash",
        "command": "{ echo \"$(date) - Bash command:\"; cat; echo; } >> /tmp/bash_audit_log"
      }
    ],
    "postToolUse": [
      {
        "matcher": "fs_write",
        "command": "cargo fmt --all"
      }
    ]
  }
}

トリガー	タイミング
agentSpawn	エージェント初期化時
userPromptSubmit	ユーザーがメッセージ送信時
preToolUse	ツール実行前（ブロック可能）
postToolUse	ツール実行後
stop	アシスタントの応答完了時

実践例：完全な設定ファイル

Amplify Gen2 × AgentCore × Strands で Agent アプリを開発するためのエージェントの例です。

{
  "name": "amplify-agentcore-dev",
  "description": "Amplify Gen2 と AgentCore を使った生成 AI エージェントアプリ開発の専門家",
  "prompt": "file://./prompts/amplify-agentcore.md",
  "mcpServers": {
    "fetch": {
      "command": "fetch3.1",
      "args": []
    },
    "git": {
      "command": "git-mcp",
      "args": []
    }
  },
  "tools": [
    "read", "write", "shell", "aws",
    "@git", "@fetch/fetch_url"
  ],
  "allowedTools": [
    "read",
    "@git/git_status"
  ],
  "toolsSettings": {
    "write": {
      "allowedPaths": [
        "amplify/**",
        "app/**",
        "components/**",
        "lib/**",
        "package.json",
        "tsconfig.json"
      ]
    }
  },
  "resources": [
    "file://README.md",
    "file://amplify_outputs.json",
    "file://amplify/**/*.ts"
  ],
  "hooks": {
    "agentSpawn": [
      { "command": "git status" }
    ],
    "postToolUse": [
      {
        "matcher": "fs_write",
        "command": "npx prettier --write ."
      }
    ]
  },
  "model": "claude-opus-4.6",
  "keyboardShortcut": "ctrl+a",
  "welcomeMessage": "Amplify Gen2 + AgentCore の開発を始めましょう！"
}

ポイント：

• resources で amplify_outputs.json と amplify/**/*.ts を自動読み込み。バックエンド定義を常にコンテキストに含める
• toolsSettings.write.allowedPaths で書き込み先を amplify/、app/、components/、lib/ に制限。設定ファイルの誤変更を防ぐ
• postToolUse フックでファイル書き込み後に Prettier を自動実行
• Amplify Powers や AgentCore Powers と組み合わせると、エージェント定義・Memory 設定・Gateway 設定のコード生成がさらに正確になる

サブエージェントとして活用する

カスタムエージェントは、チャットのメインエージェントとして使うだけでなく、サブエージェントとしても活用できます。サブエージェントは、メインエージェントから生成される独立した子プロセスで、複雑なタスクを自律的・並列的に実行します。

サブエージェントの基本

• メインエージェントが必要に応じて自動的にスポーンする
• 各サブエージェントは独自のコンテキストウィンドウを持ち、メインのコンテキストを汚さない
• 複数のサブエージェントを同時実行できる
• 完了後、結果は自動的にメインエージェントに返される

カスタムエージェントをサブエージェントとして呼び出す

作成したカスタムエージェントは名前で指定してサブエージェントとして呼び出せます。

> backend agent を使って payment モジュールをリファクタリングして

description フィールドの内容に基づいて、Kiro が自動的に適切なカスタムエージェントを選択することもあります。

サブエージェントのアクセス制御

親エージェントの設定で、どのカスタムエージェントをサブエージェントとして使えるかを制御できます。

{
  "toolsSettings": {
    "subagent": {
      "availableAgents": ["reviewer", "tester", "docs-*"],
      "trustedAgents": ["reviewer", "tester"]
    }
  }
}

• availableAgents：サブエージェントとしてスポーン可能なエージェントを制限（glob パターン対応）
• trustedAgents：確認プロンプトなしで実行を許可するエージェント

CLI と IDE でのサブエージェントの違い

Kiro IDE と Kiro CLI ではサブエージェントの仕組みにいくつか違いがあります。

	Kiro IDE	Kiro CLI
設定ファイル形式	Markdown（.md）+ YAML frontmatter	JSON（.json）
ビルトインサブエージェント	context gathering + general purpose の 2 つ	default subagent の 1 つ
呼び出し方	スラッシュコマンド（/code-reviewer ...）も可	自然言語で指示、または自動選択
Hooks	サブエージェント内では発火しない	サブエージェント内でも動作
Steering files	サブエージェントでも有効	—
使えないツール	—	web_search、use_aws、grep、glob 等は制限あり

IDE のカスタムサブエージェントは Markdown 形式で定義しますが、保存先は同じ ~/.kiro/agents/（グローバル）または .kiro/agents/（ワークスペース）です。

エージェントの使い方

チャット中に切り替え

> /agent swap

 Choose one of the following agents
❯ rust-developer-agent
  kiro_default
  backend-specialist

起動時に指定

kiro-cli --agent my-agent

ショートカットキーで切り替え

設定ファイルに keyboardShortcut を定義しておけば、キー一発で切り替えられます。もう一度押すと前のエージェントに戻ります。

保存場所とエージェントの優先順位

場所	パス	用途
ローカル	.kiro/agents/	プロジェクト固有
グローバル	~/.kiro/agents/	全プロジェクト共通

同名のエージェントがある場合、ローカルが優先されます（警告メッセージ付き）。

ベストプラクティス

• 最小権限で始める：tools と allowedTools は必要最小限から。後から拡張する
• プロンプトは外部ファイルに：file:// URI を使って分離。バージョン管理しやすい
• ローカル vs グローバルを使い分ける：プロジェクト固有のエージェントは .kiro/agents/ に、汎用的なものは ~/.kiro/agents/ に
• allowedTools は慎重に：ワイルドカードより具体的なパターンを優先する
• フックを活用する：postToolUse でフォーマッタを自動実行するなど、手作業を減らす

まとめ

Kiro CLI v1.27 で /agent create が AI アシストモードに統合され、カスタムエージェントの作成がかなり手軽になりました。「説明を書くだけ」で設定ファイルが生成されるので、まずは試してみてください。

設定ファイルを手で書く場合も、JSON の各フィールドを理解しておけば、ツール制限・MCP サーバー連携・ライフサイクルフックなど、かなり柔軟にエージェントの振る舞いを制御できます。

公式ドキュメントも合わせて参照してください。

• Creating custom agents
• Agent configuration reference
• Subagents (CLI)
• Subagents (IDE)
• Kiro CLI v1.27 Changelog