Team
c0d14c6ac1
- Add new skills: deep-dive, docs-rag, meta-creator, ppt-maker, sdlc - Add agent configs: g-assistent, meta-creator, sdlc with prompt files - Add reference docs for custom agents and skills specification - Add utility scripts: install-agents.sh, orchestrate.py, puml2svg.sh - Update README and commit-message skill config - Remove deprecated skills: codereview, python, testing, typescript - Add .gitignore
481 lines
10 KiB
Markdown
481 lines
10 KiB
Markdown
# 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/)
|