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

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

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.

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

3. Clear, Structured Prompts

✅ Good:

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

## 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

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"]
}

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

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

Advanced Configuration

MCP Servers

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"]
  }
}

Resource Loading

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

Workflow

1. Clarify Requirements

• What domain/task?
• What tools needed?
• What file paths?
• What standards to follow?

1. Design Configuration

• Choose appropriate pattern
• Set tool restrictions
• Write clear prompt
• Reference steering files

1. Create Agent File

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

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

1. Test 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 |

Best Practices

Naming

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

Prompts

1. Define expertise area clearly
2. List specific focus areas
3. Specify standards/conventions
4. Provide pattern examples
5. Set clear expectations

Security

1. Grant minimum necessary tools
2. Restrict file paths with allowedPaths
3. Whitelist commands with allowedCommands
4. Use allowedTools for safe operations
5. Validate all configurations

Troubleshooting

Agent Not Found

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

Tools Not Working

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

Prompt Ineffective

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

Integration with PRPM

bash
# Install Kiro agent from registry
prpm install @username/agent-name --as kiro --subtype agent

# Publish your agent
prpm init my-agent --subtype agent
# Edit canonical format, then:
prpm publish

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.