Kiro CLI

Kiro CLI

by AWS

Terminal surface for Kiro — spec-driven development, agent skills, steering and hooks without the VS Code IDE.

Install:

curl -fsSL https://cli.kiro.dev/install | bash  

Since CLI 3.0 (early access in 2.8.0, Jun 2026) the CLI runs on the same unified agent harness as the Kiro IDE and Kiro Web. The practical consequence is the one thing to internalise about this tool: .kiro/ is portable across all three surfaces. Skills, steering, specs, hooks and MCP config written for the IDE work unchanged in the terminal, and vice versa. There is no CLI-specific config format.

<repo>/.kiro/  
├── specs/<spec-name>/    # requirements.md, design.md, tasks.md  
├── skills/<skill-name>/  # SKILL.md (+ scripts/, references/, assets/)  
├── steering/             # product.md, tech.md, structure.md, custom *.md  
├── hooks/<name>.json     # v1 schema, one hook file each  
└── settings/mcp.json     # MCP servers  

~/.kiro/ mirrors this for global scope (skills, steering, hooks since 2.13.0). Workspace wins on name conflicts, so a project can override a personal default.

---

Agent Skills — how they are actually implemented

Kiro implements the open Agent Skills standard (same shape as Claude Code skills), not a proprietary format.

Layout

.kiro/skills/pr-review/  
├── SKILL.md           # required  
├── scripts/           # optional executable code  
├── references/        # optional docs, loaded only when SKILL.md points at them  
└── assets/            # optional templates  

Two scopes: .kiro/skills/ (workspace, committed with the repo) and ~/.kiro/skills/ (personal, all projects).

Gotcha: a bare SKILL.md dropped directly in .kiro/skills/ is not recognised. It must sit in its own subfolder, and the folder name must match name: in the frontmatter.

SKILL.md frontmatter

---  
name: pr-review  
description: Review pull requests for code quality, security issues, and test coverage.  
---  
  
# PR Review  
[instructions the agent follows]  

Field	Required	Notes
name	yes	lowercase, digits, hyphens; ≤64 chars; must equal the folder name
description	yes	≤1024 chars — this string is what triggers activation, so write it in the user’s vocabulary
license	no	license name or file reference
compatibility	no	environment requirements
metadata	no	author, version, arbitrary key-values

Three-stage progressive disclosure

1. Discovery — at startup Kiro loads only name + description of every skill.
2. Activation — when the request matches a description, the full SKILL.md body is pulled into context.
3. Execution — scripts/, references/ and assets/ load only when the instructions reach for them.

This is why description quality matters more than body quality for retrieval: a skill nobody’s phrasing matches never gets to stage 2.

Invocation

• Automatic — description matching against the conversation.
• Explicit slash command — since CLI 2.1 (24 Apr 2026) every skill in .kiro/skills/ is exposed as /<skill-name>, which bypasses model-side matching entirely. Use this when a skill must fire deterministically.

Custom agents do not inherit skills

The single biggest CLI footgun. Custom agents load no skills by default — they must declare them via the skill:// URI scheme in resources:

{  
  "resources": [  
    "skill://.kiro/skills/*/SKILL.md",  
    "skill://~/.kiro/skills/*/SKILL.md"  
  ]  
}  

Historically the inverse was also true: kiro_default in the CLI failed to auto-load skills while custom agents worked (issue #4993, open since Jan 2026, CLI 1.24.0). Current docs state the default agent auto-loads from both skill directories with no configuration — if skills appear inert, check which agent is active before debugging the skill itself.

Skills can be imported from a GitHub URL or a local folder through the Agent Steering & Skills panel; the import is a copy into the skills directory, so imported skills are ordinary files you can edit and commit.

Skills vs Steering vs Powers

Three overlapping extension mechanisms; picking the wrong one is the usual source of confusion.

	What it is	Loading	Use when
Skills	Portable open-standard packages; can carry scripts	On-demand, description-matched	Reusable workflows you want to share or import
Steering	Kiro-specific persistent project context	always / auto / fileMatch / manual modes	Project standards, conventions, always-on facts
Powers	Plugin bundling MCP tools + skills + steering	Keyword-activated, dynamic	Integrations needing both tools and guidance

A Power is a directory with a required plugin.json manifest:

my-power/  
├── plugin.json          # required manifest, declares activation keywords  
├── skills/setup/SKILL.md  
├── mcp.json             # MCP server config  
└── dev.kiro/steering/   # Kiro-specific extensions  

Powers are now documented as a shared capability across IDE/CLI/Web rather than IDE-only — the early-2026 limitation (powers unusable from the CLI, no shell scripts or JSON allowed inside them) reflected the pre-3.0 split and no longer describes the unified harness.

---

Spec-driven development setup in the CLI

SDD is the reason Kiro exists, and CLI 3.0 is what brought it to the terminal via a built-in Spec agent that plans before it writes.

Commands

Command	Behaviour
/spec new <name>	Switches to the Spec agent and prompts you to describe the scope before drafting requirements (guided flow added in 2.15.0, 27 Jul 2026)
/spec <name>	Reopens an existing spec in the Spec agent
/spec run <name>	Validates that tasks.md exists, then executes autonomously — the agent works each task without further prompting, streaming progress
/spec run <task-number>	Runs a single task from the plan

The three artefacts

Everything lands in .kiro/specs/<spec-name>/:

• requirements.md — user stories with acceptance criteria in EARS notation:
  WHEN a user submits a valid email on the reset form THE SYSTEM SHALL send a one-time reset link valid for 30 minutes.
  EARS is the point — it makes acceptance criteria machine-checkable rather than prose.
• design.md — architecture, sequence diagrams, component breakdown, technical decisions.
• tasks.md — ordered implementation plan, discrete and trackable, with dependency tracking and per-task state.

Bugfix specs substitute bugfix.md for requirements.md and drive root-cause → fix → regression-validation instead.

Choosing an entry point

• Requirements-First — behaviour known, architecture open. Product-driven work.
• Design-First — existing technical design or hard non-functional constraints; requirements are derived and validated back against the design.
• Quick Spec — runs all three phases in one pass with no approval gates. Fast, and correspondingly unsupervised.

Recommended practice is many small specs per repo, scoped by feature domain (user-authentication, product-catalog, payment-processing), never one monolith. Run Analyze Requirements on complex features before design — it surfaces logical inconsistencies, ambiguities, conflicting constraints and gaps while they are still cheap to fix.

Execution model — waves

Kiro analyses inter-task dependencies in tasks.md and groups them into waves: waves run sequentially, tasks within a wave run concurrently. No configuration required. Verification runs between steps, and task state updates live in the terminal.

Steering: the context layer specs sit on

.kiro/steering/ holds the persistent project context. The three defaults are loaded into every interaction:

• product.md — purpose, users, business objectives
• tech.md — frameworks, libraries, technical constraints
• structure.md — file organisation, naming, architectural decisions

Custom files control their own inclusion via frontmatter:

---  
inclusion: fileMatch  
fileMatchPattern: "components/**/*.tsx"  
---  

Modes are always, fileMatch, manual (pull in with #steering-file-name), and auto (needs name + description, matched like a skill). Steering files can embed live workspace files with #[[file:api/openapi.yaml]] rather than duplicating their contents.

Practical setup order for a new repo: steering first, then specs, then skills. Steering makes the generated requirements and design match your stack instead of a generic one; skills only matter once tasks start executing.

Hooks around spec execution

Hooks are standalone .kiro/hooks/<name>.json files ("version": "v1"), auto-registered at session start. Two spec-specific lifecycle triggers exist:

• PreTaskExec — before a spec task starts; can block (command action exiting with code 2)
• PostTaskExec — after a spec task completes

Other triggers: PostFileSave, PostFileCreate, PostFileDelete, PreToolUse, PostToolUse, UserPromptSubmit, SessionStart, Stop, Manual. Note v3 renamed triggers from camelCase (agentSpawn) to PascalCase (SessionStart).

{  
  "version": "v1",  
  "hooks": [{  
    "name": "Lint on save",  
    "trigger": "PostFileSave",  
    "matcher": "\\.(ts|tsx)$",  
    "action": { "type": "command", "command": "npx eslint --fix" }  
  }]  
}  

Two action types: command (real subprocess, gets session context as JSON on STDIN) and agent (appends a prompt string to model context, no subprocess — cheap guardrails and steering nudges).

Permissions

CLI 3.0 replaced the trust model with capability-based permissions in permissions.yaml — one rule can allow or deny a whole category across every tool, which matters when /spec run executes unattended:

permissions:  
  - capability: shell  
    effect: allow  
    match: "npm *"  
  - capability: shell  
    effect: exclude  
    match: "npm publish*"  
  - capability: fs_write  
    effect: allow  
    match: "src/**"  

Capabilities: shell, fs_read, fs_write, mcp. Compound commands (;, &&, ||, |) are split before pattern matching, so npm test && npm publish cannot smuggle a denied command past an allow rule.

---

Other CLI surface

• kiro-cli subcommands — chat, agent (list/create/edit/validate/migrate/set-default), mcp, crew, translate (natural language → shell), doctor, settings, update, login/logout/whoami, inline, integrations, theme, diagnostic, issue
• Slash commands — /context, /model, /agent, /tools, /prompts, /code (code intelligence: init, overview, status, logs), /todos, /mcp, /hooks, /compact, /usage, /tangent, /goal
• /tangent (2.16.0, 31 Jul 2026) — named, nestable side-conversations that inherit full history, then return to the branch point. The idiomatic way to explore an alternative without polluting a spec run.
• /goal (2.7.0, 12 Jun 2026) — iterative task loop with verification
• /upgrade-agent (2.14.0) — migrates v2 custom agent configs to the universal format
• Headless mode and ACP (Agent Communication Protocol) for automation and editor embedding
• Tool search — kiro-cli settings toolSearch.enabled true loads MCP tool definitions on demand instead of stuffing every one into each request; worth enabling once you run several MCP servers

v3 breaking changes worth knowing

• aws_tool removed — use MCP servers
• v2 session format is incompatible
• Tool IDs standardised to snake_case
• Sub-agent multi-monitor UI (Ctrl+G) replaced by single-agent background execution

---

Assessment

The CLI is no longer a stripped-down companion to the IDE — since 3.0 it is a peer surface, and for spec-driven work it is arguably the better one: /spec run with PreTaskExec hooks and a permissions.yaml allowlist is a genuinely unattended implementation loop, which the click-driven IDE flow is not. The skills implementation being the open standard rather than a bespoke format is the other significant call — Claude Code skills port with little more than a directory move, and the remaining friction is agent-resource wiring, not format translation.

See Also

• Kiro — the IDE and overall product
• Kiro Autonomous Agent — the frontier-agent / background execution layer
• Obsidian Kiro Agent OS Setup — using an Obsidian vault as the skill library
• Claude Code — the reference implementation of the Agent Skills standard
• spec-driven-development — the methodology
• MCP — tool layer used by Powers

Sources:

• Agent Skills — Kiro Docs
• Specs — Kiro Docs · Feature Specs · Best practices
• What’s new in CLI 3.0 — Kiro Docs
• Steering — Kiro Docs · Hooks · Powers
• CLI Changelog — Kiro · CLI 2.1 release
• Kiro CLI V3: Specs, Permissions, and Hooks in the Terminal — byteiota
• kirodotdev/Kiro issue #4993 — default agent skill loading