The only Kiro configurations you need for your first project

The difference between "Kiro wrote some code" and "Kiro built exactly what I wanted" comes down to how you set it up. This guide walks you through the configurations that matter most for your first project: agent skills, spec-driven development, steering files, and MCP servers. You'll configure each one and build a portfolio site in the process. Every setup here carries forward to your next project.

Saurabh

Developer Relations Engineer

Published Apr 21, 2026

Last modified Sep 10, 2026

Kiro Hands-On Workshop Guide

0. Install & Set Up Kiro

Download Kiro

Download and install for your OS. If you've used VS Code or Cursor, the layout will feel familiar.

Pricing

Kiro has a free tier and a Pro tier. If you have a Kiro Pro coupon code from a workshop, follow the steps below.

Free tier users can skip to the next section. Pro gives you access to the latest models.

Open Kiro and create a workspace

Launch Kiro
Open an existing project folder or create a new empty folder as your workspace

Redeem Kiro Credits (Workshop users only!)

Redeem the Kiro credit coupon by using the unique URL provided to you in the workshop. You will be required to log in using Google, Github, Builder ID, etc. Choose your preferred way of logging in.
Once you log in using the provided URL (from workshop), you can see your credits in your user account info in the Kiro app (see next step)
Click the accounts button in the bottom-left corner of the Kiro IDE

You will see something like the following showing you have Bonus credits.

Note: You may have to close and reopen your Kiro app to see the applied bonus credits.

Select your model

Back in the IDE, open a new chat session (located at right side bar). At the bottom of the chat panel, click the model selector dropdown. Choose Claude Opus 4.6 or above (preferred for this workshop/guide).

Key Concepts: Context window and chat sessions

Two concepts affect everything you do in Kiro:

Context window is the total information the agent can "see" at once: your files, conversation, skills, steering files, tool outputs. On Opus it's about 1M tokens. Not infinite. Kiro loads skills and references only when needed to keep the window from filling up with stuff that isn't relevant yet.

Chat sessions start fresh each time. The agent has no memory of previous sessions. Steering files fix this for recurring context (they get injected into every session). Specs fix it for project work (they're saved as files). If you catch yourself re-explaining the same thing in every chat, that belongs in a steering file. Long sessions slow down responses, so start a new one when you switch tasks.

1. Kiro's file system

Two .kiro directories matter:

Global: `~/.kiro`

Your personal toolkit, applies to all projects:

1
2
3
4
5
6
7
8
9
~/.kiro/
├── settings/mcp.json      # Global MCP server configs
├── skills/                 # Skills available everywhere
│   ├── react-best-practices/
│   ├── resume-builder/
│   ├── skill-creator/
│   └── ...
├── steering/               # Global steering files
└── powers/                 # Installed Kiro Powers

Workspace: `your-project/.kiro/`

Project-specific, commit to git for team sharing:

1
2
3
4
5
6
7
8
9
your-project/.kiro/
├── skills/                 # Project-only skills
├── steering/               # Project-only instructions
├── specs/                  # Spec-driven dev artifacts
│   └── feature-name/
│       ├── requirements.md
│       ├── design.md
│       └── tasks.md
└── settings/mcp.json       # Workspace MCP configs

Workspace configs override global when they conflict.

2. Agent skills

Skills are markdown files that give Kiro specialized knowledge. A generalist without them, a specialist with them. You stop repeating best practices in every prompt because the skill remembers for you.

Skill repos we'll use

Import some skills from GitHub:

React Best Practices (Vercel), 65 performance rules for React/Next.js
https://github.com/vercel-labs/agent-skills/tree/main/skills/react-best-practices
Web Design Guidelines (Vercel), guidelines for building correct UI interfaces
https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md
UI Design, guidelines for building better-looking UI interfaces
https://github.com/mblode/agent-skills/tree/main/skills/ui-design
Theme Factory (Anthropic), guidelines for incorporating proper and consistent UI themes
https://github.com/anthropics/skills/blob/main/skills/theme-factory/SKILL.md
Frontend Design (Anthropic), guidelines for building better-looking interfaces
https://github.com/anthropics/skills/blob/main/skills/frontend-design/SKILL.md

✅ Import both skills

In the left sidebar, click the ghost icon (Agent panel)

On the "Agent steering and skills" bar, click the + icon
Select Global agent skills

Select Import skill from GitHub

Paste the URL to the skill's SKILL.md file. Import each one:

React Best Practices:

1
https://github.com/vercel-labs/agent-skills/blob/main/skills/react-best-practices/SKILL.md

UI Design:

1
https://github.com/mblode/agent-skills/blob/main/skills/ui-design/SKILL.md

Repeat steps 2–5 for the second skill

Both skills now live in ~/.kiro/skills/ and work in every workspace.

What happened

Each skill has a SKILL.md with YAML frontmatter:

1
2
3
4
5
---
name: vercel-react-best-practices
description: React and Next.js performance optimization guidelines
  from Vercel Engineering...
---

The description is the trigger. Kiro reads it and decides whether the skill is relevant to your current task. The body has the instructions, rules, and references. Files in subdirectories (rules/, references/, assets/) load on demand, not all at once.

Skill anatomy

1
2
3
4
5
my-skill/
├── SKILL.md          # Required, YAML frontmatter + markdown
├── references/       # Optional, detailed docs loaded on demand
├── scripts/          # Optional, executable code
└── assets/           # Optional, templates and files

Global vs. workspace skills

~/.kiro/skills/ → available in every project (what we did above)
.kiro/skills/ → this project only (commit to git for team sharing)

3. Steering files

Persistent instructions that get injected into conversations. Live in .kiro/steering/ (workspace) or ~/.kiro/steering/ (global).

Three modes

Always (default):

1
2
3
4
5
6
---
inclusion: always
---
# Coding Standards
- Use TypeScript strict mode
- All API responses must include error handling

File-match (loaded when specific files are in context):

1
2
3
4
5
6
---
inclusion: fileMatch
fileMatchPattern: "*.test.ts"
---
# Testing Standards
- Use Vitest, not Jest

Manual (only when you reference it with # in chat):

1
2
3
4
5
---
inclusion: manual
---
# Deployment Checklist
- Run full test suite before deploying

✅ Try it

Create .kiro/steering/my-standards.md:

1
2
3
4
5
6
7
---
inclusion: always
---
# Project Standards
- Prefer functional components with hooks
- Use server components by default in Next.js
- Client components must have "use client" directive

Every conversation in this workspace now follows these rules.

File references in steering

Steering files can pull in other docs:

1
2
3
4
5
---
inclusion: always
---
# API Standards
Follow the contract in #[[file:docs/openapi.yaml]]

4. Spec-driven development

Kiro has two modes:

Vibe mode gives you a prompt box and writes code on the spot. Fast, freeform. Most AI coding tools work this way.

Spec mode generates structured documents (requirements, design, tasks) before writing code. You review and approve each phase. Catches architectural mistakes while they're still cheap to fix, not after 2,000 lines of implementation.

✅ Build your portfolio website

Use spec mode to build a personal portfolio site. The React and UI Design skills you imported will influence the design.

Open a new chat session
At the top of the chat, switch from Vibe to Spec mode
If you have a headshot or professional photo, drag it into the chat as an attachment
Paste this prompt (fill in the bracketed parts with your info):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
Build me a modern, responsive personal portfolio website using React and Tailwind CSS. It should be frontend only so that I can easily deploy to github pages once I am ready to publish the website.

About me:
- Name: [Your Name]
- Title: [Your Current Role, e.g. "Full Stack Developer"]
- Bio: [2-3 sentences about yourself, your background, and what you're passionate about]
- Skills: [List 5-8 of your key technical skills]
- Experience: [Brief summary — e.g. "3 years building web apps at startups"]

The site should include:
- A hero section with my name, title, and the attached photo
- An "About Me" section with my bio
- A skills/tech stack section with visual indicators
- A projects section with 3 placeholder project cards (I'll fill in real ones later)
- A contact section with links to my GitHub and LinkedIn
- Dark mode support
- Smooth scroll navigation
- Mobile-first responsive design

Make it look polished and professional — I want to be proud to share this website. It should load the main page at the "/" route.

Kiro generates requirements first. Read through them, edit anything that doesn't match what you want, then approve.
Next comes the design document. Before approving, ask the agent to check it against your imported skills:

1
2
3
use /vercel-react-best-practices and /ui-design skills to review the design document against the React best practices
and UI design skills. Are there performance or design patterns
we should incorporate? Anything else to improve this design? Incorporate that into the design document.

This checks your design against both imported skills and suggests improvements before any code gets written.

Approve the design. Kiro generates tasks, a numbered implementation plan.
Run the tasks. You can go one at a time or tell Kiro to run all of them.

All spec files live in .kiro/specs/{feature-name}/:

1
2
3
4
.kiro/specs/portfolio-website/
├── requirements.md
├── design.md
└── tasks.md

5. Custom skills

Your portfolio tasks are running. Don't wait. Open a new Kiro window (File → New Window) and create or open a different workspace folder. We'll look at two more skills that show how far the skill system can go.

✅ Download and install the skills

Download or clone this repo:
https://github.com/sdahal1/kiro_starter_guide
Open your ~/.kiro/skills/ folder in Finder (macOS) or File Explorer (Windows):
- macOS: In Finder, press Cmd+Shift+G and type ~/.kiro/skills/
- Windows: Open File Explorer and navigate to C:\Users\<YourUsername>\.kiro\skills\
From the downloaded repo, drag and drop the resume-builder folder and the skill-creator folder into ~/.kiro/skills/

Both skills are now installed and available in every workspace.

The resume-builder skill

A skill with templates, references, and decision trees. Lives at ~/.kiro/skills/resume-builder/:

1
2
3
4
5
6
7
8
9
10
11
resume-builder/
├── SKILL.md                              # Workflow + decision tree
├── assets/                               # Templates
│   ├── template-chronological.md         # Standard career progression
│   ├── template-functional.md            # Career changers
│   ├── template-combination.md           # Hybrid format
│   └── template-entry-level.md           # Recent graduates
└── references/                           # Deep docs, loaded on demand
    ├── ats-optimization.md               # ATS compliance
    ├── best-practices.md                 # Writing standards
    └── industry-career-guidance.md       # Industry-specific advice

The SKILL.md starts with a decision tree that routes the agent to the right workflow:

1
2
3
1. New resume from scratch? → "Creating New Resumes" workflow
2. Review/improve existing? → "Reviewing Existing Resumes" workflow
3. Tailor for specific job? → "Tailoring Resumes" workflow

The agent picks the matching path, then loads only the relevant templates and references. Nothing extra.

Three-level loading:

Always loaded: name + description (~40 words)
On trigger: full SKILL.md (decision tree, workflows, checklists)
On demand: the specific template from assets/ and the specific reference from references/

✅ Try it

In your new Kiro window, ask:

1
2
Review my resume. I'm a mid-career software engineer targeting
a senior role at a fintech company. Here's my current resume: [paste it]

Watch it load best-practices.md, ats-optimization.md, and industry-career-guidance.md as needed. Feedback comes back with ❌ for weak bullets and ✅ for improved versions.

The skill-creator skill

A meta-skill for building other skills. Lives at ~/.kiro/skills/skill-creator/:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
skill-creator/
├── SKILL.md                    # Main instructions
├── agents/                     # Subagent prompts
│   ├── grader.md
│   ├── comparator.md
│   └── analyzer.md
├── assets/eval_review.html     # Review UI template
├── eval-viewer/                # HTML review generator
├── references/schemas.md       # JSON schemas
└── scripts/                    # Benchmarking, packaging, eval loops
    ├── aggregate_benchmark.py
    ├── package_skill.py
    ├── run_eval.py
    └── run_loop.py

A production-grade skill with the full pattern: subagent instructions in agents/, deterministic scripts in scripts/, reference docs in references/, UI assets in assets/. When you want to build your own skills, this tool helps you draft, test, evaluate, and package them.

✅ Try it

In your new Kiro window, ask:

1
2
I want to create a skill that helps me write better Git commit messages
following the Conventional Commits format. Help me build it.

The skill-creator walks you through drafting the SKILL.md, writing test prompts, and iterating on the output.

6. MCP servers

MCP (Model Context Protocol) servers connect Kiro to external tools and data sources.

Set up AWS documentation MCP

Edit ~/.kiro/settings/mcp.json (global) and add:

1
2
3
4
5
6
7
8
9
10
11
12
{
  "mcpServers": {
    "aws-knowledge-mcp-server": {
      "url": "https://knowledge-mcp.global.api.aws",
      "disabled": false,
      "autoApprove": [
        "aws___search_documentation",
        "aws___read_documentation"
      ]
    }
  }
}

autoApprove lets Kiro use these tools without asking permission each time. Kiro reconnects after you save the file.

✅ Try it

1
How do I set up a VPC with public and private subnets using CDK?

Watch Kiro call aws___search_documentation and aws___read_documentation to answer from live AWS docs.

MCP config anatomy

1
2
3
4
5
6
7
8
9
10
{
  "server-name": {
    "command": "uvx",                  // or "url" for remote servers
    "args": ["package@latest"],
    "env": { "KEY": "${ENV_VAR}" },    // ${} pulls from system env
    "disabled": false,
    "autoApprove": ["tool_name"],
    "disabledTools": ["tool_to_hide"]
  }
}

7. GitHub MCP

Set up

Add to ~/.kiro/settings/mcp.json:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
  "mcpServers": {
    "github": {
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "${GITHUB_PERSONAL_ACCESS_TOKEN}"
      },
      "disabled": false,
      "autoApprove": [
        "get_file_contents",
        "search_repositories",
        "search_code",
        "list_commits",
        "get_me"
      ]
    }
  }
}

Set your token so it persists across terminal sessions and Kiro restarts:

macOS (zsh), add to ~/.zshrc:

1
2
echo 'export GITHUB_PERSONAL_ACCESS_TOKEN="ghp_your_token_here"' >> ~/.zshrc
source ~/.zshrc

macOS (bash), add to ~/.bash_profile:

1
2
echo 'export GITHUB_PERSONAL_ACCESS_TOKEN="ghp_your_token_here"' >> ~/.bash_profile
source ~/.bash_profile

Windows (PowerShell), set as a user-level environment variable:

1
[System.Environment]::SetEnvironmentVariable("GITHUB_PERSONAL_ACCESS_TOKEN", "ghp_your_token_here", "User")

Then restart Kiro for the change to take effect.

Linux, add to ~/.bashrc:

1
2
echo 'export GITHUB_PERSONAL_ACCESS_TOKEN="ghp_your_token_here"' >> ~/.bashrc
source ~/.bashrc

Replace ghp_your_token_here with your actual token. After setting it, restart Kiro so it picks up the new environment variable.

✅ Try it: Explore open source

1
Look at the shadcn/ui repo. How do they organize their component primitives?

1
2
Search GitHub for examples of using Zod with tRPC for input validation.
Show me a real-world example.

1
2
I need to implement a rate limiter. Find 2-3 popular Node.js rate
limiting libraries and compare their approaches.

Combine with specs

Research before you spec:

1
2
Search GitHub for how popular Next.js apps implement auth with middleware.
I want to understand patterns before I spec our auth feature.

Start your spec with that research fresh in context.

Quick reference

Feature	Location	Scope
Global skills	`~/.kiro/skills/`	All workspaces
Workspace skills	`.kiro/skills/`	This project only
Global steering	`~/.kiro/steering/`	All workspaces
Workspace steering	`.kiro/steering/`	This project only
Global MCP config	`~/.kiro/settings/mcp.json`	All workspaces
Workspace MCP config	`.kiro/settings/mcp.json`	This project only
Spec artifacts	`.kiro/specs/{feature}/`	This project only

Workspace configs override global when they conflict.

Any opinions in this article are those of the individual author and may not reflect the opinions of AWS.

Enjoyed reading this content? Let the author know!

Your likes, comments, shares, and saves help creators reach more builders.

Loading recommendations

Loading article

Builder Center

The only Kiro configurations you need for your first project

Saurabh

Kiro Hands-On Workshop Guide

0. Install & Set Up Kiro

Download Kiro

Pricing

Open Kiro and create a workspace

Redeem Kiro Credits (Workshop users only!)

Select your model

Key Concepts: Context window and chat sessions

1. Kiro's file system

Global: ~/.kiro

Workspace: your-project/.kiro/

2. Agent skills

Skill repos we'll use

✅ Import both skills

What happened

Skill anatomy

Global vs. workspace skills

3. Steering files

Three modes

✅ Try it

File references in steering

4. Spec-driven development

✅ Build your portfolio website

5. Custom skills

✅ Download and install the skills

The resume-builder skill

✅ Try it

The skill-creator skill

✅ Try it

6. MCP servers

Set up AWS documentation MCP

✅ Try it

MCP config anatomy

7. GitHub MCP

Set up

✅ Try it: Explore open source

Combine with specs

Quick reference

Global: `~/.kiro`

Workspace: `your-project/.kiro/`