Agent config

Agent profiles in v3 are self-contained and portable. Write a Markdown file with your system prompt as the body, declare tool categories with tags, embed MCP servers and permissions inline, and share the file across your team via version control. When new tools ship under a category, your agent picks them up automatically.

Your system prompt becomes the document body. Configuration lives in YAML frontmatter:

---
description: Backend development agent
model: claude-sonnet-4
tools: [read, write, shell, web]
mcpServers:
  postgres:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-postgres"]
    env:
      DATABASE_URL: "${DATABASE_URL}"
resources:
  - file://./ARCHITECTURE.md
  - skill://backend-patterns
permissions:
  - capability: shell
    effect: allow
    match:
      - "npm *"
      - "node *"
welcomeMessage: "Ready to work on backend code."
---

You are a backend developer focused on Node.js and TypeScript.
Always use async/await. All database queries must be parameterized.

JSON format is equivalent. Use Markdown when your system prompt is long; JSON when generating configs programmatically.

The tools field accepts category tags. Each tag groups related capabilities so you don't need to enumerate individual tools:

The permissions field provides capability-based rules:

permissions:
  - capability: builtin
    effect: allow
  - capability: shell
    effect: deny
    match:
      - "rm *"
      - "sudo *"
  - capability: filesystem
    effect: deny
    match:
      - ".env"
      - "secrets/**"

When no rule matches a tool call, the default is ask. Effects resolve as deny > ask > allow. For the full permissions model, see Permissions →.

Define MCP servers directly in the agent profile so it's fully self-contained:

mcpServers:
  local-server:
    command: npx
    args: ["-y", "@org/mcp-server"]
    env:
      API_KEY: "${API_KEY}"
    requestTimeout: 180000
  remote-server:
    url: https://api.example.com/mcp
    headers:
      Authorization: "Bearer ${TOKEN}"

Environment variables use ${VAR} syntax and expand at runtime. Stdio servers support timeout (connection handshake, default 60s) and requestTimeout (per-call, default 120s). HTTP servers support headers and oauth for authenticated endpoints.

• .kiro/agents/ -- workspace-level agents (shared via version control, loaded only if workspace is trusted)
• ~/.kiro/agents/ -- user-level agents (available across all projects)

Nested directories are supported. The agent name is the path relative to the agents directory without the extension: ~/.kiro/agents/team/planner.md becomes team/planner.

• Permissions -- full capability and scope reference
• Hooks -- standalone hooks format and trigger mapping