creating-kiro-agents

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Creating Kiro Agents

创建Kiro Agent

Expert guidance for creating specialized Kiro AI agents with proper configuration, tools, and security.

为创建具备合理配置、工具集和安全机制的专业Kiro AI Agent提供专家指导。

When to Use

适用场景

Use when:

User asks to create a Kiro agent
Need specialized AI assistant for specific workflow
Building domain-focused development tools
Configuring agent tools and permissions

Don't use for:

Generic AI prompts (not Kiro-specific)
Project documentation (use steering files instead)
One-off assistant interactions

适用场景：

用户要求创建Kiro Agent
针对特定工作流需要专业AI助手
构建聚焦特定领域的开发工具
配置Agent工具与权限

不适用场景：

通用AI提示词（非Kiro专属）
项目文档（请使用引导文件）
一次性助手交互

Quick Reference

快速参考

Minimal Agent Structure

最小Agent结构

json

{
  "name": "agent-name",
  "description": "One-line purpose",
  "prompt": "System instructions",
  "tools": ["fs_read", "fs_write"]
}

json

{
  "name": "agent-name",
  "description": "One-line purpose",
  "prompt": "System instructions",
  "tools": ["fs_read", "fs_write"]
}

File Location

文件位置

Project:
```
.kiro/agents/<name>.json
```
Global:
```
~/.kiro/agents/<name>.json
```

项目内：
```
.kiro/agents/<name>.json
```
全局：
```
~/.kiro/agents/<name>.json
```

Common Tools

常用工具

```
fs_read
```
- Read files
```
fs_write
```
- Write files (requires
```
allowedPaths
```
)
```
execute_bash
```
- Run commands (requires
```
allowedCommands
```
)
MCP server tools (varies by server)

```
fs_read
```
- 读取文件
```
fs_write
```
- 写入文件（需配置
```
allowedPaths
```
）
```
execute_bash
```
- 执行命令（需配置
```
allowedCommands
```
）
MCP server工具（因服务器而异）

Core Principles

核心原则

1. Specialization Over Generalization

1. 专业化优于通用化

✅ Good:

backend-api-specialist

- Express.js REST APIs ❌ Bad:

general-helper

- does everything

✅ 合理示例：

backend-api-specialist

- Express.js REST API专家 ❌ 错误示例：

general-helper

- 无所不能的助手

2. Least Privilege

2. 最小权限原则

Grant only necessary tools and paths.

json

{
  "toolsSettings": {
    "fs_write": {
      "allowedPaths": ["src/api/**", "tests/api/**"]
    },
    "execute_bash": {
      "allowedCommands": ["npm test", "npm run build"]
    }
  }
}

仅授予必要的工具和路径权限。

json

{
  "toolsSettings": {
    "fs_write": {
      "allowedPaths": ["src/api/**", "tests/api/**"]
    },
    "execute_bash": {
      "allowedCommands": ["npm test", "npm run build"]
    }
  }
}

3. Clear, Structured Prompts

3. 清晰结构化的提示词

✅ Good:

markdown

You are a backend API expert specializing in Express.js and MongoDB.

✅ 合理示例：

markdown

You are a backend API expert specializing in Express.js and MongoDB.

Focus Areas

RESTful API design
Security best practices (input validation, auth)
Error handling with proper status codes
MongoDB query optimization

RESTful API design
Security best practices (input validation, auth)
Error handling with proper status codes
MongoDB query optimization

Standards

Always use async/await
Implement proper logging
Validate all inputs
Use TypeScript interfaces


❌ **Bad**: "You are a helpful coding assistant."

Always use async/await
Implement proper logging
Validate all inputs
Use TypeScript interfaces


❌ **错误示例**："You are a helpful coding assistant."

Common Patterns

常见模板

Backend Specialist

后端专家

json

{
  "name": "backend-dev",
  "description": "Node.js/Express API development with MongoDB",
  "prompt": "Backend development expert. Focus on API design, database optimization, and security.\n\n## Core Principles\n- RESTful conventions\n- Input validation\n- Error handling\n- Query optimization",
  "tools": ["fs_read", "fs_write", "execute_bash"],
  "toolsSettings": {
    "fs_write": {
      "allowedPaths": ["src/api/**", "src/routes/**", "src/models/**"]
    }
  }
}

json

{
  "name": "backend-dev",
  "description": "Node.js/Express API development with MongoDB",
  "prompt": "Backend development expert. Focus on API design, database optimization, and security.\n\n## Core Principles\n- RESTful conventions\n- Input validation\n- Error handling\n- Query optimization",
  "tools": ["fs_read", "fs_write", "execute_bash"],
  "toolsSettings": {
    "fs_write": {
      "allowedPaths": ["src/api/**", "src/routes/**", "src/models/**"]
    }
  }
}

Code Reviewer

代码审核员

json

{
  "name": "code-reviewer",
  "description": "Reviews code against team standards",
  "prompt": "You review code for:\n- Quality and readability\n- Security issues\n- Performance problems\n- Standard compliance\n\nProvide constructive feedback with examples.",
  "tools": ["fs_read"],
  "resources": ["file://.kiro/steering/review-checklist.md"]
}

json

{
  "name": "code-reviewer",
  "description": "Reviews code against team standards",
  "prompt": "You review code for:\n- Quality and readability\n- Security issues\n- Performance problems\n- Standard compliance\n\nProvide constructive feedback with examples.",
  "tools": ["fs_read"],
  "resources": ["file://.kiro/steering/review-checklist.md"]
}

Test Writer

测试用例编写者

json

{
  "name": "test-writer",
  "description": "Writes comprehensive Vitest test suites",
  "prompt": "Testing expert using Vitest.\n\n## Test Requirements\n- Unit tests for all functions\n- Edge case coverage\n- Proper mocking\n- AAA pattern (Arrange, Act, Assert)\n- Descriptive test names",
  "tools": ["fs_read", "fs_write"],
  "toolsSettings": {
    "fs_write": {
      "allowedPaths": ["**/*.test.ts", "**/*.spec.ts", "tests/**"]
    }
  }
}

json

{
  "name": "test-writer",
  "description": "Writes comprehensive Vitest test suites",
  "prompt": "Testing expert using Vitest.\n\n## Test Requirements\n- Unit tests for all functions\n- Edge case coverage\n- Proper mocking\n- AAA pattern (Arrange, Act, Assert)\n- Descriptive test names",
  "tools": ["fs_read", "fs_write"],
  "toolsSettings": {
    "fs_write": {
      "allowedPaths": ["**/*.test.ts", "**/*.spec.ts", "tests/**"]
    }
  }
}

Frontend Specialist

前端专家

json

{
  "name": "frontend-dev",
  "description": "React/Next.js development with TypeScript",
  "prompt": "Frontend expert in React, Next.js, and TypeScript.\n\n## Focus\n- Component architecture\n- Performance optimization\n- Accessibility (WCAG)\n- Responsive design",
  "tools": ["fs_read", "fs_write"],
  "toolsSettings": {
    "fs_write": {
      "allowedPaths": ["src/components/**", "src/app/**", "src/styles/**"]
    }
  }
}

json

{
  "name": "frontend-dev",
  "description": "React/Next.js development with TypeScript",
  "prompt": "Frontend expert in React, Next.js, and TypeScript.\n\n## Focus\n- Component architecture\n- Performance optimization\n- Accessibility (WCAG)\n- Responsive design",
  "tools": ["fs_read", "fs_write"],
  "toolsSettings": {
    "fs_write": {
      "allowedPaths": ["src/components/**", "src/app/**", "src/styles/**"]
    }
  }
}

Advanced Configuration

高级配置

MCP Servers

MCP服务器

json

{
  "mcpServers": {
    "database": {
      "command": "mcp-server-postgres",
      "args": ["--host", "localhost"],
      "env": {
        "DB_URL": "${DATABASE_URL}"
      }
    },
    "fetch": {
      "command": "mcp-server-fetch",
      "args": []
    }
  },
  "tools": ["fs_read", "db_query", "fetch"],
  "allowedTools": ["fetch"]
}

json

{
  "mcpServers": {
    "database": {
      "command": "mcp-server-postgres",
      "args": ["--host", "localhost"],
      "env": {
        "DB_URL": "${DATABASE_URL}"
      }
    },
    "fetch": {
      "command": "mcp-server-fetch",
      "args": []
    }
  },
  "tools": ["fs_read", "db_query", "fetch"],
  "allowedTools": ["fetch"]
}

Lifecycle Hooks

生命周期钩子

json

{
  "hooks": {
    "agentSpawn": ["git fetch origin", "npm run db:check"],
    "userPromptSubmit": ["git status --short"]
  }
}

json

{
  "hooks": {
    "agentSpawn": ["git fetch origin", "npm run db:check"],
    "userPromptSubmit": ["git status --short"]
  }
}

Resource Loading

资源加载

json

{
  "resources": [
    "file://.kiro/steering/api-standards.md",
    "file://.kiro/steering/security-policy.md"
  ]
}

json

{
  "resources": [
    "file://.kiro/steering/api-standards.md",
    "file://.kiro/steering/security-policy.md"
  ]
}

Workflow

工作流

Clarify Requirements
- What domain/task?
- What tools needed?
- What file paths?
- What standards to follow?
Design Configuration
- Choose appropriate pattern
- Set tool restrictions
- Write clear prompt
- Reference steering files

Create Agent File

bash

# Create in project
touch .kiro/agents/my-agent.json

# Or global
touch ~/.kiro/agents/my-agent.json

Test Agent

bash

kiro agent use my-agent
kiro "What can you help me with?"

明确需求
- 针对什么领域/任务？
- 需要哪些工具？
- 涉及哪些文件路径？
- 需要遵循什么标准？
设计配置
- 选择合适的模板
- 设置工具限制
- 编写清晰的提示词
- 引用引导文件

创建Agent文件

bash

# 项目内创建
touch .kiro/agents/my-agent.json

# 或全局创建
touch ~/.kiro/agents/my-agent.json

测试Agent

bash

kiro agent use my-agent
kiro "What can you help me with?"

Common Mistakes

常见错误

Mistake	Problem	Fix
Granting all tools	Security risk	Only grant necessary tools
Vague prompts	Ineffective agent	Be specific about domain and standards
No path restrictions	Agent can modify any file	Use `allowedPaths` for `fs_write`
Generic names	Hard to find/remember	Use descriptive names: `react-component-creator`
Missing description	Unclear purpose	Add one-sentence description
Multiple domains	Unfocused agent	Create separate specialized agents

错误	问题	修复方案
授予所有工具权限	安全风险	仅授予必要的工具
模糊的提示词	Agent效果不佳	明确指定领域和标准
无路径限制	Agent可修改任意文件	为 `fs_write` 配置 `allowedPaths`
通用名称	难以查找/记忆	使用描述性名称： `react-component-creator`
缺少描述	用途不明确	添加一句话描述
覆盖多个领域	Agent不够聚焦	创建独立的专业Agent

Best Practices

最佳实践

Naming

命名规范

Use kebab-case:
```
backend-specialist
```
, not
```
BackendSpecialist
```
Be specific:
```
react-testing-expert
```
, not
```
helper
```
Indicate domain:
```
aws-infrastructure
```
,
```
mobile-ui-designer
```

使用短横线命名法（kebab-case）：
```
backend-specialist
```
，而非
```
BackendSpecialist
```
保持具体：
```
react-testing-expert
```
，而非
```
helper
```
指明领域：
```
aws-infrastructure
```
,
```
mobile-ui-designer
```

Prompts

提示词编写

Define expertise area clearly
List specific focus areas
Specify standards/conventions
Provide pattern examples
Set clear expectations

清晰定义专业领域
列出具体聚焦方向
指定标准/约定
提供模板示例
设置明确预期

Security

安全规范

Grant minimum necessary tools
Restrict file paths with
```
allowedPaths
```
Whitelist commands with
```
allowedCommands
```
Use
```
allowedTools
```
for safe operations
Validate all configurations

授予最小必要工具权限
使用
```
allowedPaths
```
限制文件路径
使用
```
allowedCommands
```
白名单命令
为安全操作使用
```
allowedTools
```
验证所有配置

Troubleshooting

故障排除

Agent Not Found

Agent未找到

Check file is in
```
.kiro/agents/
```
Verify
```
.json
```
extension
Validate JSON syntax (use JSON validator)

检查文件是否在
```
.kiro/agents/
```
目录下
验证文件扩展名为
```
.json
```
验证JSON语法（使用JSON验证工具）

Tools Not Working

工具无法工作

Verify tool names (check spelling)
Check
```
allowedPaths
```
restrictions
Ensure MCP servers are installed
Review
```
allowedTools
```
list

验证工具名称（检查拼写）
检查
```
allowedPaths
```
限制
确保MCP服务器已安装
查看
```
allowedTools
```
列表

Prompt Ineffective

提示词效果不佳

Be more specific about tasks
Add concrete examples
Reference team standards
Structure with markdown headers

更具体地描述任务
添加具体示例
引用团队标准
使用Markdown标题结构化

Integration with PRPM

与PRPM集成

bash

undefined

bash

undefined

Install Kiro agent from registry

从注册表安装Kiro Agent

prpm install @username/agent-name --as kiro --subtype agent

Publish your agent

发布你的Agent

prpm init my-agent --subtype agent

Edit canonical format, then:

编辑标准格式后，执行：

prpm publish

undefined

prpm publish

undefined

Real-World Impact

实际业务价值

Effective agents:

Save time on repetitive tasks
Enforce team standards automatically
Reduce context switching
Provide consistent code quality
Enable workflow automation

Example: A

test-writer

agent that only writes to test files prevents accidental modification of source code while ensuring comprehensive test coverage.

Key Takeaway: Specialize agents for specific domains, restrict tools to minimum necessary, and write clear prompts with concrete standards.

高效的Agent能够：

节省重复任务的时间
自动执行团队标准
减少上下文切换
保证一致的代码质量
实现工作流自动化

示例：仅写入测试文件的

test-writer

Agent可防止意外修改源代码，同时确保全面的测试覆盖率。

核心要点：为特定领域专业化Agent，将工具权限限制在最小必要范围，并编写包含具体标准的清晰提示词。