creating-kiro-agents

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

Minimal Agent Structure

```json

{

"name": "agent-name",

"description": "One-line purpose",

"prompt": "System instructions",

"tools": ["fs_read", "fs_write"]

}

```

File Location

• Project: .kiro/agents/.json
• Global: ~/.kiro/agents/.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)

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.

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

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

```

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

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

}

}

}

```

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"

]

}

```

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

```

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

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

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

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

```

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.