common-skills/references/custom-agents-configuration-reference.md

Kiro CLI Custom Agents — 配置参考

原文：https://kiro.dev/docs/cli/custom-agents/configuration-reference/
更新：2026-04-14

---

快速开始

推荐在 Kiro 会话中使用 /agent generate 命令，通过 AI 辅助生成 Agent 配置。

---

文件位置

本地 Agent（项目级）

<project>/.kiro/agents/<name>.json

仅在该目录或其子目录下运行 Kiro CLI 时可用。

全局 Agent（用户级）

~/.kiro/agents/<name>.json

在任意目录下均可使用。

优先级

同名 Agent 时，本地优先于全局（并输出警告）。

---

配置字段总览

字段	说明
name	Agent 名称（可选，默认取文件名）
description	Agent 描述
prompt	系统提示词（内联或 file:// URI）
mcpServers	可访问的 MCP 服务器
tools	可用工具列表
toolAliases	工具名称重映射
allowedTools	无需确认即可使用的工具
toolsSettings	工具专项配置
resources	可访问的本地资源
hooks	生命周期钩子命令
includeMcpJson	是否引入 mcp.json 中的 MCP 服务器
model	指定使用的模型 ID
keyboardShortcut	快速切换快捷键
welcomeMessage	切换到该 Agent 时显示的欢迎语

---

字段详解

name

Agent 的标识名称，用于显示和识别。

{ "name": "aws-expert" }

---

description

人类可读的描述，帮助区分不同 Agent。

{ "description": "An agent specialized for AWS infrastructure tasks" }

---

prompt

类似系统提示词，为 Agent 提供高层上下文。支持内联文本或 file:// URI。

内联：

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

文件引用：

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

路径解析规则：

• 相对路径：相对于 Agent 配置文件所在目录
  • "file://./prompt.md" → 同目录
  • "file://../shared/prompt.md" → 上级目录
• 绝对路径：直接使用
  • "file:///home/user/prompts/agent.md"

---

mcpServers

定义 Agent 可访问的 MCP 服务器。

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

字段：

• command（必填）：启动 MCP 服务器的命令
• args（可选）：命令参数
• env（可选）：环境变量
• timeout（可选）：每次请求超时毫秒数，默认 120000
• oauth（可选）：HTTP 类型 MCP 服务器的 OAuth 配置
  • redirectUri：自定义重定向 URI
  • oauthScopes：请求的 OAuth 权限范围数组

OAuth 示例：

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

---

tools

Agent 可使用的工具列表。

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

引用方式：

• 内置工具："read"、"shell"
• MCP 服务器所有工具："@server_name"
• MCP 服务器特定工具："@server_name/tool_name"
• 所有工具："*"
• 所有内置工具："@builtin"

---

toolAliases

重命名工具，解决命名冲突或创建更直观的名称。

{
  "toolAliases": {
    "@github-mcp/get_issues": "github_issues",
    "@gitlab-mcp/get_issues": "gitlab_issues",
    "@aws-cloud-formation/deploy_stack_with_parameters": "deploy_cf"
  }
}

---

allowedTools

无需用户确认即可使用的工具。支持精确匹配和通配符。

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

匹配方式：

模式	说明
"read"	精确匹配内置工具
"@server_name/tool_name"	精确匹配 MCP 工具
"@server_name"	该服务器的所有工具
"@server/read_*"	前缀通配
"@server/*_get"	后缀通配
"@git-*/*"	服务器名通配
"?ead"	? 匹配单个字符

注意： allowedTools 不支持 "*" 通配所有工具。

---

toolsSettings

对特定工具进行专项配置。

{
  "toolsSettings": {
    "write": {
      "allowedPaths": ["src/**", "tests/**"]
    },
    "shell": {
      "allowedCommands": ["git status", "git fetch"],
      "deniedCommands": ["git commit .*", "git push .*"],
      "autoAllowReadonly": true
    },
    "@git/git_status": {
      "git_user": "$GIT_USER"
    }
  }
}

---

resources

Agent 可访问的本地资源，支持三种类型。

文件资源（file://）

启动时直接加载到上下文。

{
  "resources": [
    "file://README.md",
    "file://docs/**/*.md"
  ]
}

Skill 资源（skill://）

启动时仅加载元数据（name/description），按需加载完整内容，保持上下文精简。

Skill 文件须以 YAML frontmatter 开头：

---
name: dynamodb-data-modeling
description: Guide for DynamoDB data modeling best practices.
---

# DynamoDB Data Modeling
...

{
  "resources": [
    "skill://.kiro/skills/**/SKILL.md"
  ]
}

知识库资源（knowledgeBase）

支持对大量文档进行索引检索。

{
  "resources": [
    {
      "type": "knowledgeBase",
      "source": "file://./docs",
      "name": "ProjectDocs",
      "description": "Project documentation and guides",
      "indexType": "best",
      "autoUpdate": true
    }
  ]
}

字段	必填	说明
type	是	固定为 "knowledgeBase"
source	是	索引路径，使用 file:// 前缀
name	是	显示名称
description	否	内容描述
indexType	否	"best"（默认，质量更高）或 "fast"
autoUpdate	否	Agent 启动时重新索引，默认 false

---

hooks

在 Agent 生命周期特定时机执行命令。

{
  "hooks": {
    "agentSpawn": [
      { "command": "git status" }
    ],
    "userPromptSubmit": [
      { "command": "ls -la" }
    ],
    "preToolUse": [
      {
        "matcher": "execute_bash",
        "command": "{ echo \"$(date) - Bash:\"; cat; } >> /tmp/audit.log"
      }
    ],
    "postToolUse": [
      {
        "matcher": "fs_write",
        "command": "cargo fmt --all"
      }
    ],
    "stop": [
      { "command": "npm test" }
    ]
  }
}

触发时机：

钩子	触发时机
agentSpawn	Agent 初始化时
userPromptSubmit	用户提交消息时
preToolUse	工具执行前（可阻断）
postToolUse	工具执行后
stop	助手完成响应时

每个 hook 条目：

• command（必填）：要执行的命令
• matcher（可选）：用于 preToolUse/postToolUse 的工具名匹配模式，使用内部工具名（如 fs_read、fs_write、execute_bash、use_aws）

---

includeMcpJson

是否引入 ~/.kiro/settings/mcp.json（全局）和 <cwd>/.kiro/settings/mcp.json（工作区）中定义的 MCP 服务器。

{ "includeMcpJson": true }

---

model

指定该 Agent 使用的模型 ID。未指定或不可用时回退到默认模型。

{ "model": "claude-sonnet-4" }

可通过 /model 命令查看可用模型列表。

---

keyboardShortcut

快速切换到该 Agent 的键盘快捷键。

{ "keyboardShortcut": "ctrl+a" }

格式： [modifier+]key
修饰键： ctrl、shift
按键： a-z、0-9

• 当前不在该 Agent：切换到该 Agent
• 已在该 Agent：切换回上一个 Agent
• 多个 Agent 快捷键冲突时，快捷键被禁用并输出警告

---

welcomeMessage

切换到该 Agent 时显示的欢迎语。

{ "welcomeMessage": "What would you like to build today?" }

---

完整示例

{
  "name": "aws-rust-agent",
  "description": "Specialized agent for AWS and Rust development",
  "prompt": "file://./prompts/aws-rust-expert.md",
  "mcpServers": {
    "fetch": { "command": "fetch-server", "args": [] },
    "git": { "command": "git-mcp", "args": [] }
  },
  "tools": ["read", "write", "shell", "aws", "@git", "@fetch/fetch_url"],
  "toolAliases": {
    "@git/git_status": "status",
    "@fetch/fetch_url": "get"
  },
  "allowedTools": ["read", "@git/git_status"],
  "toolsSettings": {
    "write": { "allowedPaths": ["src/**", "tests/**", "Cargo.toml"] },
    "aws": { "allowedServices": ["s3", "lambda"], "autoAllowReadonly": true }
  },
  "resources": [
    "file://README.md",
    "file://docs/**/*.md"
  ],
  "hooks": {
    "agentSpawn": [{ "command": "git status" }],
    "postToolUse": [{ "matcher": "fs_write", "command": "cargo fmt --all" }]
  },
  "model": "claude-sonnet-4",
  "keyboardShortcut": "ctrl+shift+r",
  "welcomeMessage": "Ready to help with AWS and Rust development!"
}

---

最佳实践

本地 vs 全局 Agent

本地 Agent	全局 Agent
项目专属配置	跨项目通用 Agent
需要访问项目文件/工具	个人效率工具
通过版本控制与团队共享	常用工具和工作流

安全建议

• 仔细审查 allowedTools，优先使用精确匹配而非通配符
• 对敏感操作配置 toolsSettings（如限制 allowedPaths）
• 启用写工具（write、shell）时，Agent 拥有与当前用户相同的文件系统权限，可读写 ~/.kiro 下所有内容
• 使用 preToolUse hooks 审计或阻断敏感操作
• 在安全环境中充分测试后再共享 Agent

组织建议

• 使用描述性名称
• 在 description 中说明用途
• 将 prompt 文件单独维护
• 本地 Agent 随项目纳入版本控制

---

相关文档

• 创建自定义 Agent
• 内置工具参考
• Hooks 文档
• Agent 示例