Core Concepts

Every Kiro feature you’ll ever touch is built from the eleven ideas on this page. Read it once top-to-bottom, then come back and use it like a dictionary. Each concept follows the same pattern: what it is → how to picture it → the common mistake → the short version.

Agentic development

Simple definition. Agentic development means working with an AI that acts rather than only suggesting. Given a goal, the agent plans steps, edits files, runs commands, checks results, and adjusts. Your role shifts from typing every line to directing and reviewing the work.

Analogy. A GPS navigator versus a paper map. A paper map (a chatbot) shows information; you make all the driving decisions. A navigator (an agent) plots the route, reroutes around problems, and tells you each turn, but you are still the driver, and you can override it at any time.

In Kiro specifically, you choose how much freedom the agent gets:

• Autopilot mode. The agent works end-to-end: creating files, modifying code, running commands. Everything stays viewable and revertible.
• Supervised mode. The agent pauses after each turn that edits files, and you accept or reject each change, hunk by hunk.

Kiro also keeps checkpoints, restore points you can roll back to when an agent session goes somewhere you didn’t want.

In short: the agent does multi-step work; you set direction, boundaries, and review. Autopilot = autonomous, Supervised = approve-each-change.

Specs

Simple definition. A spec is a written plan that Kiro creates with you before building. One spec produces three Markdown files that live in your repository:

File	Question it answers
requirements.md	What should this do? (user stories + acceptance criteria)
design.md	How will we build it? (architecture, sequence diagrams, strategy)
tasks.md	In what steps? (discrete, trackable implementation tasks)

For bug fixes there’s a variant, bugfix specs, where the analysis lands in bugfix.md instead of requirements.md.

Analogy. Building a house with an architect. You don’t tell a construction crew “make me a nice house” and hope; you approve blueprints first. Specs are blueprints for features: cheap to change while they’re still words, expensive to change once they’re concrete.

Small example. Requirements are written in EARS notation Easy Approach to Requirements Syntax, a structured way of writing testable requirements using patterns like WHEN / THE SYSTEM SHALL. , which turns wishes into testable statements:

WHEN the user submits the signup form with an empty email field
THE SYSTEM SHALL show the message "Email is required" and keep other fields filled

IF the email service is unreachable
THEN THE SYSTEM SHALL queue the welcome email and retry up to 3 times

Notice the shape: nominal behavior uses WHEN … THE SYSTEM SHALL …, error cases use IF … THEN …. Every line can become a test.

When to use specs vs. plain chat (“vibe” sessions): specs for complex features, risky bug fixes, and anything teammates need to understand later; plain chat for exploration and quick prototypes.

Two more facts worth knowing: Kiro can run an optional requirements analysis that flags ambiguity and contradictions in requirements.md before any code exists, and at execution time independent tasks run concurrently in “waves” to finish faster. Since GA, property-based testing can check that the implementation actually matches the spec.

Common mistake: rushing through the requirements phase (“yeah yeah, approve”) to get to code. The entire value of a spec is front-loading the thinking. Skim-approving requirements gives you vibe coding with extra paperwork.

In short: specs = requirements → design → tasks, written before code, stored in your repo, executable task-by-task.

Steering

Simple definition. Steering files are Markdown documents that give Kiro persistent knowledge about your project, so you stop re-explaining your stack, conventions, and goals in every session.

Kiro recognizes three foundational files, included in every interaction by default:

• product.md: what the product is, who it serves, business goals
• tech.md: frameworks, libraries, tools, technical constraints
• structure.md: file organization, naming conventions, architecture patterns

Where they live: .kiro/steering/ in your workspace (project-specific) or ~/.kiro/steering/ globally (all projects). Workspace files win when they conflict.

Inclusion modes. Not every rule belongs in every conversation. YAML front matter (which must be the very first content in the file) controls when it loads: always (default), fileMatch (only when matching files are involved), manual (only when you reference it with #steering-file-name), or auto (Kiro matches your request against the file’s description). The conditional form looks like this:

---
inclusion: fileMatch
fileMatchPattern: "src/api/**"
---

fileMatchPattern also accepts a list of globs, and auto mode adds name and description fields so Kiro knows when the file is relevant.

Small example. A focused steering file:

# API conventions

- Every endpoint validates input before touching the database.
- Errors return the shape { "error": { "code", "message" } }, never bare strings.
- New endpoints need an entry in docs/api.md. Why: our mobile team
  generates their client from that file.

Note the why: steering works best when the agent understands the reason, not just the rule.

In short: steering = permanent project memory in .kiro/steering/; three foundational files; inclusion modes control when each loads.

Hooks

Simple definition. Hooks are automations: when X happens, do Y, where Y is an agent prompt or a shell command. They turn “things you always forget to do” into things that happen by themselves.

Trigger types include file events (save, create, delete), prompt submission, agent-turn completion, before/after tool invocations, before/after spec tasks, and manual on-demand buttons.

Small example. A hook that fires on saving any file under src/api/ and prompts the agent: “Update the matching section in docs/api.md if this endpoint’s signature changed.” Save a file and the documentation stays honest automatically.

You create hooks in plain language (describe the automation; Kiro writes the config) or through a form in the IDE’s hook panel.

Common mistake: hooking heavy work to frequent events. A full test suite on every save will make you hate your own automation. Equally classic: a hook that edits files, which triggers the hook again. Scope triggers narrowly (specific folders or file patterns) and keep hook actions small.

In short: hooks = event-triggered prompts/commands; create them in natural language; scope them tightly.

MCP

Simple definition. MCP Model Context Protocol, an open standard that lets AI tools call external services and data sources through small add-on servers. is how Kiro talks to the world outside your code: documentation services, databases, ticket systems, search. Anything that exposes an MCP server becomes tools the agent can call.

Analogy. A universal power-strip standard. Kiro has the socket; any vendor can build a plug. You don’t wait for Amazon to integrate your favorite tool: if it speaks MCP, it plugs in.

Configuration is one JSON file: .kiro/settings/mcp.json in the workspace, or ~/.kiro/settings/mcp.json user-wide (workspace wins on conflict):

{
  "mcpServers": {
    "aws-docs": {
      "command": "npx",
      "args": ["-y", "example-aws-docs-server"],
      "env": { "API_TOKEN": "${API_TOKEN}" },
      "autoApprove": [],
      "disabled": false
    }
  }
}

Remote servers use url (plus optional headers / oauth) instead of command/args. The Kiro panel shows each server’s connection status, and the “Kiro - MCP Logs” output channel is the first place to look when one misbehaves.

In short: MCP = plug-in protocol for external tools; configured in mcp.json at workspace or user level; approve tools deliberately.

CLI

Simple definition. Kiro CLI brings the same agent into your terminal. Install it, then run kiro-cli to start a conversation in any directory:

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

# Windows 11 (PowerShell, not Command Prompt)
irm 'https://cli.kiro.dev/install.ps1' | iex

Note the CLI’s Windows support is narrower than the IDE’s: Windows 11 only. Inside a session you steer with slash commands: /context add "src/**" to include files, /chat save to export a session, /agent swap to switch personas. !command runs a shell command directly, no AI involved. Sessions resume with kiro-cli chat --resume.

The CLI matters beyond personal preference: it’s the surface that works over SSH, in containers, and in headless CI/CD automation with API-key authentication.

Lineage note: Kiro CLI is the evolution of Amazon Q Developer CLI. The q entry point still works and old configs migrate automatically (full story in the History chapter).

Common mistake: assuming the CLI is a lesser sidekick. It has the full primitive set: steering, hooks, MCP, custom agents, skills. Some workflows (server debugging, CI) only make sense there.

In short: kiro-cli = the agent in your terminal; slash commands steer sessions; the surface for automation and remote work.

IDE

Simple definition. The Kiro IDE is a desktop code editor built on Code OSS (the open-source core of VS Code) with the agent woven into it. If you’ve used VS Code, your hands already know the layout, and you can import your settings and extensions on first run.

What the IDE adds over the raw editor: the agentic chat panel (with Autopilot/Supervised modes), the specs experience, steering and hook panels, MCP server management, and visual diff review of agent changes.

Platform support: macOS (Intel + Apple silicon), Windows 10/11 64-bit (ARM not supported), Linux with glibc ≥ 2.39. Sign-in works with Google, GitHub, AWS Builder ID, or organization SSO.

Common mistake: ignoring the context system and pasting code into chat by hand. The # providers (#file, #folder, #codebase, #terminal, #problems, #git diff and friends) feed the agent precise, current context far better than copy-paste.

In short: familiar VS Code-style editor + agent panels; use # context providers instead of pasting code.

Web

Simple definition. Kiro Web (app.kiro.dev) runs the agent in your browser against repositories on GitHub or GitLab, with no local installation. You chat about a change, the cloud agent implements it, and the result arrives as a pull request / merge request you review.

It also has an autonomous mode, where the agent owns a task end-to-end, and since June 2026 you can run specs entirely in the browser and even start sessions without connecting a repository first.

Status to know about: Kiro Web launched in May 2026 and is still labeled preview. It requires a paid subscription and is currently US-region.

Common mistake: treating Web output differently from local output. A pull request from a cloud agent deserves exactly the same review rigor as code from your own machine (arguably more, since you didn’t watch it being written).

In short: browser agent → real pull requests; GitHub + GitLab; preview, paid plans, review everything.

Custom agents

Simple definition. A custom agent is a scoped version of Kiro you design: its own instructions, its own allowed tools, its own context. Think of them as job descriptions (“reviewer”, “docs writer”, “data-pipeline helper”) instead of one generalist doing everything.

Small example. A read-only code reviewer (JSON in .kiro/agents/ for the workspace, or ~/.kiro/agents/ globally):

{
  "name": "reviewer",
  "description": "Reviews code critically; cannot modify anything",
  "tools": ["read"],
  "allowedTools": ["read"],
  "resources": ["file://README.md"],
  "prompt": "You are a strict senior reviewer. Find problems; do not fix them."
}

Create one with /agent create reviewer -D "strict code reviewer" (or kiro-cli agent create), switch with /agent swap, or launch straight into one: kiro-cli --agent reviewer.

Why restrict tools? Fewer permissions means fewer interruptions (pre-approved safe tools) and a hard ceiling on damage: a reviewer that physically cannot write files can be trusted in autopilot.

Common mistake: giving every custom agent every tool “to be safe.” That recreates the generalist you were trying to scope, and throws away the safety property that makes custom agents worth having.

In short: custom agents = scoped personas in JSON; restrict tools to match the job; switch with /agent swap.

Skills

Simple definition. A skill is a reusable instruction pack the agent loads when relevant. Each skill is a folder with a SKILL.md file: YAML front matter (name + description) followed by the know-how. The folder can also bundle scripts and templates. Kiro follows the open Agent Skills standard, so skills are portable across tools that support it.

Small example:

---
name: release-notes
description: Writes release notes from merged PRs. Use when preparing a release.
---

# Writing release notes

1. Group changes into Added / Changed / Fixed.
2. Lead each item with the user impact, not the implementation.
3. Link each item to its PR.

At session start Kiro reads only names and descriptions; when your request matches a description (or you invoke /release-notes as a slash command), the full skill loads. Workspace skills live in .kiro/skills/, personal ones in ~/.kiro/skills/.

Skills vs. steering is the distinction that confuses everyone: steering is always-on context about your project (“we use PostgreSQL 16”); a skill is on-demand procedure for a task (“how to write our release notes”). Steering describes the project; a skill tells the agent how to do a job.

Common mistake: vague descriptions. The description is how Kiro decides to activate the skill. “helps with databases” never triggers; “Guide for DynamoDB data modeling. Use when designing or analyzing DynamoDB schemas.” does.

In short: skills = SKILL.md instruction packs; activate by description match or slash command; describe them precisely.

Powers

Simple definition. A power is a one-click bundle that makes the agent good at a specific technology. Inside: a POWER.md steering file (telling the agent what tools it now has and when to use them), an MCP server configuration, and optionally extra steering or hooks.

Analogy. Downloading a city pack into your GPS before a trip: maps, traffic rules, and local quirks, installed together and activated when you enter the city. Powers load on demand when your conversation mentions relevant keywords, instead of stuffing every tool into every session.

That on-demand loading is the technical win: a pile of always-on MCP servers bloats the agent’s context all the time; powers keep specialized tools dormant until needed.

Launch partners at the December 2025 introduction included Stripe, Supabase, Figma, Neon, Netlify, Datadog, Dynatrace, and Postman. You can also install community powers from GitHub repositories or build your own.

Common mistake: installing third-party powers without reading what’s inside. A power configures tools and instructions for your agent. That’s exactly the kind of thing to skim before trusting, the same way you’d skim a shell script before piping it to bash.

In short: powers = POWER.md + MCP + steering bundles; load on demand; read before you install.

How the pieces fit together

A useful mental model for the whole system:

• Specs decide what gets built.
• Steering shapes how the agent thinks about your project.
• Hooks decide when the agent acts without being asked.
• MCP and powers extend what the agent can reach.
• Custom agents and skills package who the agent is and what it knows how to do.
• IDE, CLI, and Web are just where all of this happens.