creating-kiro-agents

Creating Kiro Agents

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

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

Quick Reference

Minimal Agent Structure

{
  "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

Common Tools

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

Core Principles

1. Specialization Over Generalization

✅ Good: backend-api-specialist - Express.js REST APIs ❌ Bad: general-helper - does everything

2. Least Privilege

Grant only necessary tools and paths.

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

3. Clear, Structured Prompts

✅ Good:

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

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

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

Common Patterns

Backend Specialist

{
  "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/**"]
    }
  }
}