Beginner Tutorial

This tutorial takes you from nothing to a working mini-project. Plan for about an hour. Every step tells you what to do, what you should see, and what it means.

Before you start

You need three things:

1. A computer Kiro supports: macOS (Intel or Apple silicon), Windows 10/11 (64-bit only; ARM isn’t supported), or Linux with glibc 2.39+ (Ubuntu 24+, Fedora 40+, Debian 13+, Mint 22+, Arch).
2. An account to sign in with: any of Google, GitHub, AWS Builder ID, or your organization’s identity.
3. No credit card. Kiro has a free tier, and this small tutorial fits comfortably inside it. (Plans and limits change over time, so kiro.dev/pricing is always the current source.)

Part 1: Install and sign in

1. Go to kiro.dev and download the installer for your operating system.
2. Run it and launch Kiro. It looks like VS Code on purpose: same editor core, so existing instincts transfer.
3. Sign in when prompted (Google / GitHub / AWS Builder ID / organization).
4. First-run setup asks a few questions:
   • Import VS Code settings and extensions? Yes if you use VS Code; otherwise skip.
   • Theme: pick what’s comfortable; you can change it later.
   • Shell integration: authorize it. This is what lets the agent run commands (like starting your app) with your knowledge.
5. You’ll land on a welcome page. Create an empty folder somewhere (call it tip-calculator) and open it via File → Open Folder.

Part 2: Meet the agent (in Supervised mode)

Open the chat panel (the conversation icon in Kiro’s side area). Before typing anything, find the Autopilot toggle in the chat interface and make sure you’re in Supervised mode.

Why this matters: in Supervised mode the agent must show you its file changes and wait for your approval, hunk by hunk. In Autopilot it acts end-to-end on its own. Autopilot is great, but only after you’ve built judgment about what the agent does well. Learn in Supervised.

Now try three conversations, in order:

1. Ask for information (nothing changes):

What would be a sensible file structure for a one-page
tip calculator website with no frameworks?

You get advice, no action. Kiro detects from your phrasing whether you want explanation or modification.

2. Ask for action (something changes):

Create index.html, style.css, and script.js for an empty
page titled "Tip Calculator" that links them together.

Watch what happens: the agent proposes file creations, and because you’re in Supervised mode, you review and accept each change. Open the files afterward and read them. Always read them.

3. Point at context with #:

Explain #file index.html line by line, for a beginner.

The # symbol opens Kiro’s context menu: #file, #folder, #codebase, #problems, #terminal and friends. This is how you point the agent at exactly the right material instead of pasting code into the chat box.

Part 3: Your first spec

So far this resembles other AI tools. Specs are what make Kiro different.

A spec turns an idea into three reviewed documents before code gets written: requirements.md (what), design.md (how), tasks.md (the work list). Let’s build the actual calculator with one.

1. Start a spec session for this feature: open the Kiro panel (or the Command Palette) and create a new Feature Spec. When asked to pick a workflow, choose Requirements-First. That’s the flow this tutorial follows.

2. Describe the feature plainly:

   A tip calculator: the user enters a bill amount, picks a tip
   percentage (10/15/20 or custom), and optionally a number of
   people to split between. Show tip amount, total, and per-person
   total, updating live. Handle silly inputs gracefully.

3. Review requirements.md. Kiro drafts user stories with acceptance criteria in EARS notation Easy Approach to Requirements Syntax: requirement sentences shaped like WHEN <condition> THE SYSTEM SHALL <behavior>. . Expect lines shaped like:

   WHEN the user enters a bill amount and selects a tip percentage
   THE SYSTEM SHALL display the tip amount and total immediately
   
   IF the bill amount is not a positive number
   THEN THE SYSTEM SHALL show an inline error and clear the results

   Read them like a checklist of promises. Wrong promise? Say so in chat now: changing a sentence is free; changing shipped code isn’t. (Notice what you’re doing here: this is requirements review, a senior-engineer skill, and Kiro just made you practice it on day one.)

4. Review design.md. For a project this small it will be short: structure, how values flow, edge cases. Skim it; ask about anything surprising.

5. Open tasks.md and execute the first task. Stay in Supervised mode and accept changes one by one. Continue task by task until the list is done.

6. Try the result. Open index.html in your browser (or ask the agent to serve it). Enter a bill, change the tip, split between 3 people. Then test a promise from the requirements: type -50 as the bill. Does the error behavior match what requirements.md said? That’s spec-driven development in one sentence: the documentation and the behavior agree.

Part 4: Make it remember (your first steering file)

New chat sessions start fresh unless you give the project memory.

1. In the Kiro panel, find the Steering section and create a workspace steering file (it lives in .kiro/steering/ inside your project).

2. Write something true and useful:

   # Project: Tip Calculator
   
   - Plain HTML/CSS/JS only: no frameworks, no build step.
   - All money values are rounded to 2 decimals at display time only.
   - Keep functions small and commented for a beginner to read.

3. Test it: start a new chat session and ask for a small change (“add a 25% tip button”). The agent should respect your no-frameworks rule without being told. That’s steering working.

Part 5: Where you stand

You’ve now done, in miniature, the loop professionals use: describe → review requirements → review design → execute tasks → verify against requirements → encode conventions in steering. Everything after this is the same loop applied to bigger projects.

Next steps, in order of usefulness: the Core Concepts chapter if you skipped it, then Use Cases to see this loop applied to real situations, then the Practice Exercises to build muscle memory.