Custom agents

Create purpose-built agents in minutes. Write a Markdown file, declare which tool categories the agent gets access to with simple tags like read, write, shell, embed MCP servers and permission rules inline, and share the file with your team via version control. Your agent appears in the agent selector the moment you save it.

Configuration lives in YAML frontmatter, your system prompt is the document body:

---
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}"
permissions:
  - capability: shell
    effect: allow
    match:
      - "npm *"
      - "node *"
---

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

The tools field accepts category tags that automatically include all tools in a category:

When new tools ship under a category, your agent picks them up automatically.

• .kiro/agents/: workspace-level agents (shared via version control)
• ~/.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.

Workspace agents only load if the workspace is trusted. The first time you open a workspace with .kiro/agents/, Kiro prompts you to trust it.

Embed permission rules directly in the agent profile:

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.

Define MCP servers so the agent profile is 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 for authenticated endpoints.

• Agent selector: switch between agents in the IDE
• Permissions: control what agents can do
• Hooks: automate workflows on agent events