How to Use Kiro: The Beginner's Guide (First Install, Steering Files, Your First Spec, and the Hook That Runs Your Tests)

CodexFuse Team · 2026-10-31T03:57:27.257Z · 16 min read

How to Use Kiro: The Beginner's Guide (First Install, Steering Files, Your First Spec, and the Hook That Runs Your Tests)

Learning how to use Kiro starts with one idea: in Kiro, the spec is the unit of work, and code follows it. Kiro is an agentic IDE — an AI coding partner built into your editor — that takes you from prototype to production through spec-driven development instead of free-form prompting. If you have tried vibe-coding and watched a promising prototype collapse into unmaintainable code, Kiro is built for exactly that frustration: you write down what to build, approve the design, and only then let the agent write code, one reviewed task at a time.

This Kiro for beginners tutorial walks the complete arc in one sitting: install the IDE and sign in, generate steering files so Kiro learns your project's conventions, create your first spec (requirements, design, tasks — each with your approval), add an agent hook that runs your tests automatically, and connect one MCP server. If you already draft requirements documents before coding, an AI PRD generator is a fast way to turn a rough feature idea into the structured requirements text your first Kiro spec will be built from.

How Do You Use Kiro? The 30-Second Version

You use Kiro by installing the IDE, teaching it your project with steering files, describing a feature as a spec, approving each phase, and letting it implement tasks while you review every diff. The full beginner loop looks like this:

1. Download and install Kiro from kiro.dev for macOS, Windows, or Linux, then sign in with Google, GitHub, AWS Builder ID, or your organization's identity provider.
2. Open your project folder and click the Kiro Ghost icon in the activity bar to open the Kiro panel, which holds Specs, Agent Hooks, Steering, and MCP Servers.
3. Generate steering docs from the Steering section so Kiro learns your product, tech stack, and project structure before it writes a line of code.
4. Start a spec with the Spec button, describe your feature in plain language, and approve the requirements, then the design, then the task list — one gate at a time.
5. Run the tasks from tasks.md, reviewing every diff the agent produces; independent tasks run in parallel waves.
6. Add one agent hook — for example, a hook that runs your test suite every time a source file is saved — so quality checks happen without you remembering them.

That is the whole shape of Kiro: context in, spec out, code last. The rest of this guide fills in each step.

What Is Kiro, and When Should You Use It?

Kiro is an agentic IDE from AWS that pairs an AI agent with your codebase and develops features through written specifications. A spec is a set of versioned documents — requirements, design, and a task list — that you read, comment on, and approve before the agent implements anything. The agent can also work in free-flow chat for quick questions, and Kiro ships the same engine as a CLI, a web app, an iOS app, and a personal AI agent called Crew, all sharing your .kiro configuration.

Use specs when you are building a complex feature or fixing a bug where regressions are costly; stay in free-flow chat for quick exploratory work. That is Kiro's own rule of thumb from the official docs, and it is the right mental model: the spec workflow costs you a few minutes of reading and approving up front, and it pays you back in code that matches a design you actually agreed to. If you already use another AI coding tool, the comparison section near the end of this guide draws the line between Kiro, Cursor, Cline, and OpenCode.

How Do You Install Kiro?

Installing Kiro takes about five minutes: download the installer from kiro.dev, run it, and sign in when it opens. The desktop IDE runs on macOS (Intel and Apple Silicon), Windows 10/11 (x64 or ARM64), and Linux (Ubuntu 24+, Debian 13+, Fedora 40+, Arch, and Mint 22+ on x86_64 or ARM64). Prefer the terminal? The Kiro CLI runs on macOS, Windows 11 (PowerShell), and Linux. There is also a web app that needs no local installation at all, an iOS app distributed through TestFlight during early access, and Crew, the personal-agent surface for macOS, Linux, and Windows.

The first launch walks you through a short onboarding flow. Sign in with Google, GitHub, AWS Builder ID, or your organization's identity provider; optionally import your VS Code settings and extensions (Kiro is built on the VS Code foundation, so your setup carries over — our VS Code beginner guide covers the editor it is based on); pick the Kiro Dark or Kiro Light theme; and allow shell integration so the agent can execute commands on your behalf. Kiro downloads updates automatically in the background, and you can check manually from the Kiro menu (or the Command Palette on Windows and Linux) at any time.

What Are Kiro Steering Files, and How Do You Write Them?

Steering files are markdown documents in .kiro/steering/ that give Kiro persistent knowledge about your project — your conventions, libraries, and standards — so you never have to re-explain them in every chat. Three foundation files establish the baseline: product.md (what your product is and who it serves), tech.md (your frameworks, libraries, and constraints), and structure.md (file organization, naming, and architecture). You can also keep global steering files in ~/.kiro/steering/ that apply to every workspace; when global and workspace files conflict, the workspace version wins.

The fastest way to start is the Generate Steering Docs button in the Steering section of the Kiro panel: Kiro analyzes your repository and writes the three foundation files for you. Then add your own specialized files with the + button — one domain per file, such as api-standards.md for REST conventions or testing-standards.md for your test patterns. Each file can carry YAML front matter that controls when it loads:

• always — loaded into every interaction. Use it for core standards like your tech stack and coding conventions.
• fileMatch — loads only when you work with matching files, e.g. fileMatchPattern: "components/**/*.tsx" for React component rules.
• manual — loads on demand when you reference it as #testing-standards in chat or pick it from the / command menu.
• auto — loads when your request matches the file's name and description, like a skill that activates itself.

A minimal steering file looks like this:

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

# API standards

- All routes return JSON with a error field on failure.
- Validate request bodies with the shared schema helper.
- Never expose internal error details to clients.

Kiro also reads AGENTS.md files — at your workspace root, in subdirectories, or in ~/.kiro/steering/ — as steering that is always included. Two rules keep steering healthy: never put API keys, passwords, or secrets in steering files (they are part of your codebase, and the official docs call this out explicitly), and treat steering changes like code changes — review them when your architecture changes.

How Do You Create Your First Spec in Kiro?

You create a spec by clicking the Spec button in the chat pane or the + button in the Kiro panel's Specs section, then describing your feature in natural language. Kiro first asks whether you are developing a feature or fixing a bug: feature specs produce requirements.md, bugfix specs produce bugfix.md with current, expected, and unchanged behavior. For features you then choose a workflow — Requirements-First or Design-First — and Kiro walks you through three phases.

In the requirements phase, Kiro structures your idea as user stories with acceptance criteria written in EARS notation (a precise "when/then" style that removes ambiguity). In the design phase, it documents the technical architecture, component design, sequence diagrams, and testing strategy in design.md. In the tasks phase, it generates discrete, trackable implementation steps in tasks.md. Every phase ends at an approval gate: a floating Review button opens Markdown Review, where you comment on exact passages and send your feedback to Kiro at once.

Once the spec is approved, run tasks individually or all at once. Kiro specs are ordinary markdown files in your repository, so they work with git history, pull requests, and code review like any other artifact — the spec is documentation that happens to be executable. Kiro builds a dependency graph of your task list and executes independent tasks concurrently in waves — Wave 1 runs everything with no dependencies, Wave 2 runs what Wave 1 unblocked, and so on. The spec files live in .kiro/specs/<feature-name>/ and are versioned artifacts: read them, edit them, commit them. Never accept generated spec text blindly — the whole point of the workflow is that a human signs off on the plan. (If you want the speed without the gates for a throwaway prototype, the Quick Spec workflow auto-generates all three artifacts — but do not use it for anything you will maintain.)

How Do You Make an Agent Hook Run Your Tests?

Agent hooks are small JSON files in .kiro/hooks/ that run a shell command or inject an agent prompt automatically when something happens — a file is saved, a tool is used, a task completes. The beginner-friendly way to create one: open the Agent Hooks section of the Kiro panel, click +, choose Ask Kiro to create a hook, and describe what you want in plain language, like "run the test suite every time a TypeScript file is saved."

Kiro writes a file such as .kiro/hooks/run-tests-on-save.json:

{
  "version": "v1",
  "hooks": [{
    "name": "Run tests on save",
    "trigger": "PostFileSave",
    "matcher": "\\.(ts|tsx)$",
    "action": { "type": "command", "command": "npm test" }
  }]
}

The trigger is a PascalCase event name (PostFileSave here); the matcher is a regex against the file path; the action runs a shell command in your project root (the command receives session context as JSON on STDIN). Kiro agent hooks activate automatically when a session starts — no registration step. Because hooks execute shell commands, review the generated file before it runs for the first time: check the matcher is narrow enough and the command is one you would run yourself. You can also disable a hook without deleting it ("enabled": false), and command hooks time out after 60 seconds by default.

Beyond tests, the same mechanism enforces standards (lint or type-check after agent file changes), generates companion files (a test file when a new source file appears), gates dangerous operations, and validates code before the agent finalizes changes. One well-chosen hook replaces a dozen reminders you would otherwise type into chat.

How Do You Add an MCP Server to Kiro?

MCP (Model Context Protocol) servers give Kiro access to specialized tools, APIs, and knowledge bases beyond its built-in capabilities. To add one, open the Kiro panel, enable MCPs, and click the pencil icon to edit the JSON configuration. Kiro ships with a fetch MCP server you can activate by setting disabled to false; any other server is added to the mcpServers object with its launch command, arguments, and environment:

{
  "mcpServers": {
    "web-search": {
      "command": "uvx",
      "args": ["mcp-server-brave-search"],
      "env": { "BRAVE_API_KEY": "your-api-key-here" },
      "disabled": false,
      "autoApprove": ["search"]
    }
  }
}

Keep API keys in the env block or your shell environment — never in chat prompts or steering files. Once configured, reference MCP tools by asking questions that need them, by using the #MCP context provider, or by combining MCP with hooks and specs for automated workflows. Kiro MCP support is one of the four pillars in the Kiro panel, alongside specs, hooks, and steering, and learning all four is what turns Kiro from a chatbot into a development environment.

Kiro vs Cursor vs Cline vs OpenCode: Which AI Coding Tool Should You Pick?

These four tools answer the same question — "how should an AI help me write code?" — with four different units of work. None of them is a rival of the others; they are four lanes, and knowing which lane you are in saves you from comparing them on the wrong axis.

The practical way to choose: if your pain is prototypes that rot, Kiro's spec lane is the fix. The Kiro vs Cline decision is the simplest of the four — it is really "a new IDE with specs built in" versus "your current VS Code with an agent extension." If your pain is slow iteration inside one editor, read our Cursor AI beginner guide for the in-editor agent lane. If you want to stay in VS Code with an explicit plan-then-act split, our Cline beginner guide covers that lane. And if you live in the terminal or over SSH, our OpenCode beginner guide is the terminal-agent lane. Many developers end up using two of these: Kiro for the big features, something faster for the small ones.

How Much Does Kiro Cost?

Kiro is genuinely usable for free and scales to heavy professional use through credit-based paid tiers. The Free tier costs $0 per month and includes 50 credits, with access to open-weight models (Qwen3 Coder Next, DeepSeek 3.2, and MiniMax M2.1) plus Claude Sonnet 4.5 when you sign up with a social login or AWS Builder ID — subject to rate limits. That is enough to complete this entire guide: install, steering, a first spec, a hook, and an MCP server.

Kiro pricing is credit-based across all five tiers. The paid plans are Pro ($20/user/month, 1,000 credits), Pro+ ($40, 2,000 credits), Pro Max ($100, 5,000 credits), and Power ($200, 10,000 credits), all with access to premium models including Auto, Claude Sonnet 5, and Claude Opus 5, plus add-on credits at $0.04 each. Kiro credits $20 toward your subscription when you first upgrade using social login or AWS Builder ID. Prices exclude taxes, and not every premium model is available in every region — check the pricing page for the current list before you commit to a tier.

Sources

Every fact in this guide was verified on Kiro's official documentation on 2026-10-30 — making this Kiro tutorial current as of October 30, 2026: the installation page (desktop IDE platforms for macOS, Windows, and Linux; CLI, web, iOS TestFlight, and Crew surfaces; the four-step install flow; automatic updates) at kiro.dev/docs/getting-started/installation/; the IDE 1.x setup page (sign-in providers Google, GitHub, AWS Builder ID, and organization identity; VS Code settings import; Kiro Dark/Light themes; shell integration; the Kiro Ghost panel; the "Let's build" screen with Spec, Plan, Bug Fix, and Quick Spec workflow agents; the specs-vs-free-flow rule of thumb) at kiro.dev/docs/ide/setup/; the first-project walkthrough (Generate Steering Docs; the spec phases requirements, design, tasks; hook creation from natural language; the MCP JSON configuration with the fetch server and autoApprove) at kiro.dev/docs/getting-started/first-project/; the steering reference (workspace .kiro/steering/ vs global ~/.kiro/steering/; foundation files product.md, tech.md, structure.md; inclusion modes always, fileMatch, manual, auto; AGENTS.md support; the no-secrets rule) at kiro.dev/docs/steering/; the specs reference (requirements.md/bugfix.md, design.md, tasks.md; Requirements-First vs Design-First; Quick Spec without approval gates; the Review button and Markdown Review; dependency waves with parallel task execution) at kiro.dev/docs/specs/; the hooks reference (.kiro/hooks/*.json, schema version v1, PascalCase triggers like PostFileSave, regex matchers, command vs agent actions, the 60-second default timeout, "Ask Kiro to create a hook") at kiro.dev/docs/hooks/; and the pricing page (Free $0/50 credits; Pro $20/1,000; Pro+ $40/2,000; Pro Max $100/5,000; Power $200/10,000; $0.04 add-on credits; the $20 first-upgrade credit; open-weight and premium model lists) at kiro.dev/pricing. The steering/specs/hooks framing cross-checks AWS's October 2026 Kiro solution posts and the eliteai.tools Kiro skill reference; the Kiro-vs-Cursor-vs-Cline-vs-OpenCode comparison table is an original synthesis for this guide.

Frequently Asked Questions

Is Kiro really free to use?

Yes, for real work — not just a trial. The Free tier is $0 per month with 50 credits, and signing up with a social login or AWS Builder ID unlocks Claude Sonnet 4.5 plus open-weight models like Qwen3 Coder Next, DeepSeek 3.2, and MiniMax M2.1, subject to rate limits. Everything in this beginner guide fits inside the free tier. You only need a paid tier (starting at $20/month for 1,000 credits) when your usage outgrows it.

Does Kiro work with my existing VS Code setup?

Yes. Kiro is built on the VS Code foundation, and the first-run onboarding offers to import your VS Code settings and extensions. Your keybindings, theme preferences, and installed extensions carry over, so the editor feels familiar from the first minute. If you have never used VS Code, our VS Code beginner guide walks through the editor basics Kiro inherits.

Do I have to write a spec for every small task?

No. Kiro's own rule of thumb: reach for specs when you are building complex features or fixing bugs where regressions are costly, and stay in free-flow chat for quick exploratory work. A one-line fix or a "what does this function do" question does not need requirements, design, and tasks — but anything you will maintain for months probably does.

Can I use Kiro without installing the desktop IDE?

Yes. Kiro runs as a web app in any modern browser with no local installation, as a CLI on macOS, Windows 11, and Linux, and on iOS through TestFlight during early access. Your .kiro configuration — steering files, specs, hooks, and MCP servers — is shared across all of these surfaces, so you can start a spec on the web and finish it in the IDE.

Kiro vs Cursor — which should a beginner choose?

Choose based on your pain, not on hype. If your code keeps rotting because you prompted your way to a prototype with no plan, Kiro's spec-first workflow (approve the requirements, approve the design, then code) directly fixes that. If you iterate fast inside one editor and want an agent that edits on demand, Cursor's in-editor lane fits better — our Cursor AI beginner guide covers it. They are different lanes, not rivals, and many developers use both.