Cursor rule

1---
2description: Kiro agent configuration patterns, JSON structure, tool permissions, and security best practices for creating specialized AI development assistants
3globs: ["**/.kiro/agents/**/*.json", "**/kiro-agent*.json"]
4alwaysApply: false
5---
6 
7# Kiro Agent Development
8 
9Patterns for creating specialized Kiro AI agents with proper configuration, tools, and security.
10 
11## Agent File Structure
12 
13```json
14{
15  "name": "agent-name",
16  "description": "One-line purpose",
17  "prompt": "System instructions",
18  "tools": ["fs_read", "fs_write"],
19  "toolsSettings": {},
20  "resources": [],
21  "mcpServers": {},
22  "hooks": {}
23}
24```
25 
26**Location:**
27- Project: `.kiro/agents/<name>.json`
28- Global: `~/.kiro/agents/<name>.json`
29 
30## Core Principles
31 
32### 1. Specialization
33✅ Create focused agents: `backend-api-specialist`
34❌ Avoid generic agents: `general-helper`
35 
36### 2. Least Privilege
37Only grant necessary tools and paths.
38 
39```json
40{
41  "toolsSettings": {
42    "fs_write": {
43      "allowedPaths": ["src/api/**", "tests/api/**"]
44    },
45    "execute_bash": {
46      "allowedCommands": ["npm test", "npm run build"]
47    }
48  }
49}
50```
51 
52### 3. Clear Prompts
53Be specific about domain, focus areas, and standards.
54 
55```json
56{
57  "prompt": "Backend API expert specializing in Express.js and MongoDB.\n\n## Focus\n- RESTful API design\n- Security (input validation, auth)\n- Error handling\n- Query optimization\n\n## Standards\n- Always use async/await\n- Implement proper logging\n- Validate all inputs"
58}
59```
60 
61## Common Patterns
62 
63### Backend Specialist
64```json
65{
66  "name": "backend-dev",
67  "description": "Node.js/Express API development with MongoDB",
68  "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",
69  "tools": ["fs_read", "fs_write", "execute_bash"],
70  "toolsSettings": {
71    "fs_write": {
72      "allowedPaths": ["src/api/**", "src/routes/**", "src/models/**"]
73    }
74  }
75}
76```
77 
78### Code Reviewer
79```json
80{
81  "name": "code-reviewer",
82  "description": "Reviews code against team standards",
83  "prompt": "You review code for:\n- Quality and readability\n- Security issues\n- Performance problems\n- Standard compliance\n\nProvide constructive feedback with examples.",
84  "tools": ["fs_read"],
85  "resources": ["file://.kiro/steering/review-checklist.md"]
86}
87```
88 
89### Test Writer
90```json
91{
92  "name": "test-writer",
93  "description": "Writes comprehensive Vitest test suites",
94  "prompt": "Testing expert using Vitest.\n\n## Requirements\n- Unit tests for all functions\n- Edge case coverage\n- Proper mocking\n- AAA pattern (Arrange, Act, Assert)",
95  "tools": ["fs_read", "fs_write"],
96  "toolsSettings": {
97    "fs_write": {
98      "allowedPaths": ["**/*.test.ts", "**/*.spec.ts", "tests/**"]
99    }
100  }
101}
102```
103 
104### Frontend Specialist
105```json
106{
107  "name": "frontend-dev",
108  "description": "React/Next.js development with TypeScript",
109  "prompt": "Frontend expert in React, Next.js, and TypeScript.\n\n## Focus\n- Component architecture\n- Performance optimization\n- Accessibility (WCAG)\n- Responsive design",
110  "tools": ["fs_read", "fs_write"],
111  "toolsSettings": {
112    "fs_write": {
113      "allowedPaths": ["src/components/**", "src/app/**", "src/styles/**"]
114    }
115  }
116}
117```
118 
119### DevOps Engineer
120```json
121{
122  "name": "devops",
123  "description": "Infrastructure and deployment automation",
124  "prompt": "DevOps expert specializing in Docker, Kubernetes, and CI/CD.\n\nFocus on automation, reliability, and security.",
125  "tools": ["fs_read", "fs_write", "execute_bash"],
126  "toolsSettings": {
127    "fs_write": {
128      "allowedPaths": [".github/**", "docker/**", "k8s/**", "terraform/**"]
129    },
130    "execute_bash": {
131      "allowedCommands": ["docker*", "kubectl*", "terraform*"]
132    }
133  }
134}
135```
136 
137## Tool Configuration
138 
139### Common Tools
140- `fs_read` - Read files
141- `fs_write` - Write files (requires `allowedPaths`)
142- `execute_bash` - Run commands (requires `allowedCommands`)
143- MCP server tools - Varies by server
144 
145### File System Tools
146```json
147{
148  "toolsSettings": {
149    "fs_read": {
150      "allowedPaths": ["src/**", "docs/**"]
151    },
152    "fs_write": {
153      "allowedPaths": ["src/generated/**"],
154      "excludePaths": ["src/generated/migrations/**"]
155    }
156  }
157}
158```
159 
160### Bash Execution
161```json
162{
163  "toolsSettings": {
164    "execute_bash": {
165      "allowedCommands": ["npm test", "npm run build"],
166      "timeout": 30000
167    }
168  }
169}
170```
171 
172### MCP Servers
173```json
174{
175  "mcpServers": {
176    "database": {
177      "command": "mcp-server-postgres",
178      "args": ["--host", "localhost"],
179      "env": {
180        "DB_URL": "${DATABASE_URL}"
181      }
182    },
183    "fetch": {
184      "command": "mcp-server-fetch",
185      "args": []
186    }
187  },
188  "tools": ["fs_read", "db_query", "fetch"],
189  "allowedTools": ["fetch"]
190}
191```
192 
193## Advanced Features
194 
195### Lifecycle Hooks
196```json
197{
198  "hooks": {
199    "agentSpawn": ["git fetch origin", "npm run db:check"],
200    "userPromptSubmit": ["git status --short"]
201  }
202}
203```
204 
205### Resource Loading
206```json
207{
208  "resources": [
209    "file://.kiro/steering/api-standards.md",
210    "file://.kiro/steering/security-policy.md"
211  ]
212}
213```
214 
215## Best Practices
216 
217### Naming
218- Use **kebab-case**: `backend-specialist`
219- Be **specific**: `react-testing-expert`, not `helper`
220- Indicate **domain**: `aws-infrastructure`
221 
222### Security
2231. Grant minimum necessary tools
2242. Restrict file paths with `allowedPaths`
2253. Whitelist commands with `allowedCommands`
2264. Use `allowedTools` for safe operations
227 
228### Prompts
2291. Define expertise area clearly
2302. List specific focus areas
2313. Specify standards/conventions
2324. Provide pattern examples
2335. Set clear expectations
234 
235## Anti-Patterns
236 
237### ❌ Don't: Grant All Tools
238```json
239{
240  "tools": ["*"]  // Security risk
241}
242```
243 
244### ❌ Don't: Vague Prompts
245```json
246{
247  "prompt": "You are a helpful assistant."  // Too generic
248}
249```
250 
251### ❌ Don't: No Path Restrictions
252```json
253{
254  "tools": ["fs_write"]  // Can modify any file
255}
256```
257 
258### ✅ Do: Be Specific
259```json
260{
261  "prompt": "Backend API expert in Express.js.\n\nFocus:\n- REST design\n- Security\n- Error handling",
262  "tools": ["fs_read", "fs_write"],
263  "toolsSettings": {
264    "fs_write": {
265      "allowedPaths": ["src/api/**"]
266    }
267  }
268}
269```
270 
271## Common Tasks
272 
273### Creating an Agent
274 
2751. **Clarify Requirements**
276   - What domain/task?
277   - What tools needed?
278   - What file paths?
279 
2802. **Create JSON File**
281```bash
282   touch .kiro/agents/my-agent.json
283```
284 
2853. **Design Configuration**
286   - Choose pattern (backend, frontend, etc.)
287   - Set tool restrictions
288   - Write clear prompt
289 
2904. **Test Agent**
291```bash
292   kiro agent use my-agent
293   kiro &quot;What can you help me with?&quot;
294```
295 
296## Troubleshooting
297 
298### Agent Not Found
299- File must be in `.kiro/agents/`
300- Extension must be `.json`
301- Validate JSON syntax
302 
303### Tools Not Working
304- Check tool name spelling
305- Verify `allowedPaths` restrictions
306- Ensure MCP servers installed
307- Review `allowedTools` list
308 
309### Prompt Ineffective
310- Be more specific about tasks
311- Add concrete examples
312- Reference team standards
313- Structure with markdown headers
314 
315## Integration with PRPM
316 
317```bash
318# Install Kiro agent from PRPM
319prpm install @username/agent-name --as kiro --subtype agent
320 
321# Publish your agent
322prpm init my-agent --subtype agent
323prpm publish
324```
325 
326## Summary
327 
328**Key Points:**
3291. Specialize agents for specific domains
3302. Restrict tools to minimum necessary
3313. Write clear, structured prompts
3324. Use kebab-case naming
3335. Reference steering files for standards
3346. Test agents before deployment
335 
336**Goal:** Create secure, focused agents that enforce team standards and improve development workflows.
337