Agent profiles are backward-compatible — existing configs continue to work. The unified agent harness adds new optional fields and a Markdown format option.
JSON — new fields to add to existing .kiro/agents/*.json configs:
{ "excludedTools": ["knowledge"], "includeMcpJson": true, "includePowers": false, "resources": ["file://./ARCHITECTURE.md", "skill://backend-patterns"], "permissions": { "rules": [ { "capability": "shell", "match": ["npm *", "node *"], "effect": "allow" } ] }, "welcomeMessage": "Ready to work on the backend. What do you need?" }
(All other fields — name, description, prompt, model, tools, mcpServers — are unchanged.)
Both formats support identical fields. Use Markdown when your system prompt is long or benefits from human readability; JSON works well for programmatic generation. Mixing formats across agents in the same workspace is supported.
Markdown (.kiro/agents/my-agent.md) — front matter for config, body for system prompt:
--- name: my-agent description: Specialized for backend work model: claude-sonnet-4-20250514 tools: ["read", "write", "shell", "web_fetch"] excludedTools: ["knowledge"] includeMcpJson: true includePowers: false mcpServers: db-server: command: npx args: ["-y", "@org/db-mcp"] env: DB_URL: "${DATABASE_URL}" resources: - file://./ARCHITECTURE.md - skill://backend-patterns permissions: rules: - capability: shell match: ["npm *", "node *"] effect: allow - capability: fs_write match: ["src/**"] effect: allow welcomeMessage: "Ready to work on the backend. What do you need?" --- You are a backend engineer focused on Node.js and TypeScript services. ## Guidelines - Use async/await, never callbacks - All database queries must be parameterized - Write tests for every new function
| Field | Type | New in 1.0 | Description |
|---|---|---|---|
name | string | Agent identifier | |
description | string | Shown in agent picker | |
prompt | string | System prompt — inline string or file:// URI (JSON only; in Markdown, use the body) | |
model | string | Model override (e.g., claude-sonnet-4-20250514) | |
tools | string[] | "*" | Allowed tools. "*" = all available | |
excludedTools | string[] | ✓ | Tools to exclude even if tools allows them |
includeMcpJson | boolean | ✓ | Include workspace .kiro/settings/mcp.json servers |
includePowers | boolean | ✓ | Include IDE-installed powers |
mcpServers | object | Embedded MCP server definitions (stdio or HTTP) | |
resources | string[] | ✓ | URIs to load into context: file://, skill:// |
permissions | object | ✓ | Inline policy rules (agent scope, supports all effects) |
welcomeMessage | string | ✓ | Custom greeting on session start |
hooks | object | ✓ | CLI only — inline hook definitions (same schema as .kiro/hooks/). IDE ignores agents containing this field. |
Stdio servers:
{ "command": "npx", "args": ["-y", "@org/server"], "env": {}, "timeout": 30000 }
HTTP/SSE servers:
{ "url": "https://api.example.com/mcp", "headers": { "Authorization": "Bearer ${TOKEN}" } }
Environment variables use ${VAR} syntax and are expanded at runtime.
The resources field loads context into the agent at session start:
| URI scheme | Example | Loads |
|---|---|---|
file:// | file://./docs/ARCH.md | File content relative to workspace root |
skill:// | skill://backend-patterns | Skill from .kiro/skills/backend-patterns/SKILL.md |
These fields work exactly as before — no behavior changes:
name, description, prompt, model, tools, mcpServersexcludedTools is useful when tools: "*" but you want to block specific toolspermissions embedded in an agent profile uses agent scope (supports deny, ask, and allow)resources replaces manually copying context into the prompt — the harness loads and refreshes them
Agent config changes