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.

What do I need before I 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.)

How do I install Kiro?

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: Kiro IDE is built on Code OSS, the open-source base of VS Code, so existing instincts transfer.
3. Wait for the first launch to finish. Kiro opens on a welcome page.

If you want the terminal instead of, or as well as, the desktop app, Kiro CLI installs separately and the CLI Guide covers it. The CLI needs Windows 11 specifically, which is narrower than the IDE’s Windows 10 and 11 support.

How do I sign in?

1. Sign in when Kiro prompts you. The options are Google, GitHub, AWS Builder ID, or your organization’s identity (SSO).
2. Answer the first-run 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.
3. Create an empty folder somewhere (call it tip-calculator) and open it via File → Open Folder.

How do I have my first conversation?

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.

Leave the model on Auto while you learn. Auto routes to a frontier model for you and carries the lowest credit multiplier. Change the default model explains when to move off it.

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.

How do I undo something the agent did?

Kiro takes a checkpoint automatically every time you send a prompt. If a change goes wrong, restore the checkpoint from before that prompt instead of un-picking edits by hand. Checkpoints cover files the agent changed with its own tools, not your manual edits, so commit to git before anything risky. Undo with checkpoints and rewind has the full picture.

How do I write my 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.

How do I make Kiro remember my project?

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.

Create your first steering file covers the three foundational files and the inclusion modes when you’re ready for them.

How do I keep secrets away from the agent?

Anything the agent reads goes into the model’s context, so keep the sensitive files out of reach from the start. Add a .kiroignore file to your project root with lines like .env, *.pem, and *.key. It uses the same syntax as .gitignore. This tutorial’s project has no secrets, but the habit is worth forming now, on a project where nothing can go wrong. Keep secrets out with .kiroignore has the details.

Where do I stand now?

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.