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

Code Reviewer

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

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

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

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

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

Resource Loading

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

2. Design Configuration

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

3. Create Agent File

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

4. Test Agent

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

Common Mistakes

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

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