Kiro CLI Spec (Custom Agents, Skills, Steering, MCP, Settings)

Last verified: 2026-02-17

Primary sources

https://kiro.dev/docs/cli/
https://kiro.dev/docs/cli/custom-agents/configuration-reference/
https://kiro.dev/docs/cli/skills/
https://kiro.dev/docs/cli/steering/
https://kiro.dev/docs/cli/mcp/
https://kiro.dev/docs/cli/hooks/
https://agentskills.io

Config locations

• Project-level config: .kiro/ directory at project root.
• No global/user-level config directory — all config is project-scoped.

Directory structure

.kiro/
├── agents/
│   ├── <name>.json              # Agent configuration
│   └── prompts/
│       └── <name>.md            # Agent prompt files
├── skills/
│   └── <name>/
│       └── SKILL.md             # Skill definition
├── steering/
│   └── <name>.md                # Always-on context files
└── settings/
    └── mcp.json                 # MCP server configuration

Custom agents (JSON config + prompt files)

• Custom agents are JSON files in .kiro/agents/.
• Each agent has a corresponding prompt .md file, referenced via file:// URI.
• Agent config has 14 possible fields (see below).
• Agents are activated by user selection (no auto-activation).
• The converter outputs a subset of fields relevant to converted plugins.

Agent config fields

Example agent config

{
  "name": "security-reviewer",
  "description": "Reviews code for security vulnerabilities",
  "prompt": "file://./prompts/security-reviewer.md",
  "tools": ["*"],
  "resources": [
    "file://.kiro/steering/**/*.md",
    "skill://.kiro/skills/**/SKILL.md"
  ],
  "includeMcpJson": true,
  "welcomeMessage": "Switching to security-reviewer. Reviews code for security vulnerabilities"
}

Skills (SKILL.md standard)

• Skills follow the open Agent Skills standard.
• A skill is a folder containing SKILL.md plus optional supporting files.
• Skills live in .kiro/skills/.
• SKILL.md uses YAML frontmatter with name and description fields.
• Kiro activates skills on demand based on description matching.
• The description field is critical — Kiro uses it to decide when to activate the skill.

Constraints

• Skill name: max 64 characters, pattern ^[a-z][a-z0-9-]*$, no consecutive hyphens (--).
• Skill description: max 1024 characters.
• Skill name must match parent directory name.

Example

---
name: workflows-plan
description: Plan work by analyzing requirements and creating actionable steps
---

# Planning Workflow

Detailed instructions...

Steering files

• Markdown files in .kiro/steering/.
• Always loaded into every agent session's context.
• Equivalent to the repo instruction file used by Claude-oriented workflows; in this repo AGENTS.md is canonical and CLAUDE.md may exist only as a compatibility shim.
• Used for project-wide instructions, coding standards, and conventions.

MCP server configuration

• MCP servers are configured in .kiro/settings/mcp.json.
• Only stdio transport is supported — command + args + env.
• HTTP/SSE transport (url, headers) is NOT supported by Kiro CLI.
• The converter skips HTTP-only MCP servers with a warning.

Example

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-playwright"]
    },
    "context7": {
      "command": "npx",
      "args": ["-y", "@context7/mcp-server"]
    }
  }
}

Hooks

• Kiro supports 5 hook trigger types: agentSpawn, userPromptSubmit, preToolUse, postToolUse, stop.
• Hooks are configured inside agent JSON configs (not separate files).
• 3 of 5 triggers map to Claude Code hooks (preToolUse, postToolUse, stop).
• Not converted by the plugin converter for MVP — a warning is emitted.

Conversion lossy mappings

Overwrite behavior during conversion