common-skills/skills/meta-creator/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 的标识名称，用于显示和识别。

```json
{ "name": "aws-expert" }
```

---

### `description`

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

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

---

### `prompt`

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

**内联：**
```json
{ "prompt": "You are an expert AWS infrastructure specialist" }
```

**文件引用：**
```json
{ "prompt": "file://./prompts/aws-expert.md" }
```

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

---

### `mcpServers`

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

```json
{
  "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 示例：**
```json
{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.github.com/mcp",
      "oauth": {
        "redirectUri": "127.0.0.1:8080",
        "oauthScopes": ["repo", "user"]
      }
    }
  }
}
```

---

### `tools`

Agent 可使用的工具列表。

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

**引用方式：**
- 内置工具：`"read"`、`"shell"`
- MCP 服务器所有工具：`"@server_name"`
- MCP 服务器特定工具：`"@server_name/tool_name"`
- 所有工具：`"*"`
- 所有内置工具：`"@builtin"`

---

### `toolAliases`

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

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

---

### `allowedTools`

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

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

**匹配方式：**

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

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

---

### `toolsSettings`

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

```json
{
  "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://`）

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

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

#### Skill 资源（`skill://`）

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

Skill 文件须以 YAML frontmatter 开头：

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

# DynamoDB Data Modeling
...
```

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

#### 知识库资源（`knowledgeBase`）

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

```json
{
  "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 生命周期特定时机执行命令。

```json
{
  "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 服务器。

```json
{ "includeMcpJson": true }
```

---

### `model`

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

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

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

---

### `keyboardShortcut`

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

```json
{ "keyboardShortcut": "ctrl+a" }
```

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

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

---

### `welcomeMessage`

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

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

---

## 完整示例

```json
{
  "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](https://kiro.dev/docs/cli/custom-agents/creating/)
- [内置工具参考](https://kiro.dev/docs/cli/reference/built-in-tools/)
- [Hooks 文档](https://kiro.dev/docs/cli/hooks)
- [Agent 示例](https://kiro.dev/docs/cli/custom-agents/examples/)