Kiro IDE Training Guide

Spec-Driven Development with AI

What is Kiro?

Kiro is an AI-powered, agentic IDE from AWS for spec-driven development. It combines natural language with structured software development — from prototype to production. Based on Code OSS (VS Code compatible).

📝 Spec-Driven Development

Structured specifications: Requirements → Design → Tasks.

⚡ Vibe Mode

Conversational coding for rapid prototyping.

🔌 Agent Hooks

Event-driven automations running in the background.

🎯 Steering & Skills

Persistent project knowledge and reusable workflows.

🚀 Powers

Dynamically loadable tool bundles with MCP and best practices.

🔗 MCP Server

Model Context Protocol for external tools and knowledge sources.

Session Types & Modes

Vibe Sessions: Conversational Q&A, explorative coding, rapid prototyping.

Spec Sessions: Structured: Requirements → Design → Tasks. For production-ready features.

Autopilot: Kiro works autonomously. Changes are always visible and reversible.

Supervised: Kiro pauses after each change for approval.

Specs (Specifications)

Specs transform an idea into a detailed implementation plan. Three files form the foundation.

Three-Phase Workflow

  1. requirements.md — User stories with acceptance criteria (EARS notation)
  2. design.md — Technical architecture, sequence diagrams, interfaces
  3. tasks.md — Discrete, trackable tasks with dependencies

Spec Types

Feature Spec

For new features. Variants: Requirements-First, Design-First, Quick Plan.

Bugfix Spec

Systematic bug fixing. Uses bugfix.md (instead of requirements.md) for bug analysis, then design.md and tasks.md.

Example

Prompt: "Add a review system for products" — Kiro generates:

  • User stories (View, Create, Filter, Rate)
  • EARS acceptance criteria with edge cases
  • Design with TypeScript interfaces and Mermaid diagrams
  • Sequenced tasks including unit tests and accessibility

Parallel Task Execution

"Run all Tasks" analyzes dependencies and executes independent tasks in waves in parallel (Wave 1 → Wave 2 → Wave N).

.kiro/specs/feature-name/
├── requirements.md
├── design.md
└── tasks.md

Agent Hooks

Hooks are "if-then" rules: A workspace event triggers an AI action.

Event Types

TriggerDescriptionAvailable
PromptSubmitChat message sent (can block)IDE, CLI
StopAgent finished respondingIDE, CLI
SessionStartNew session startedIDE
PreToolUseBefore tool execution (can block)IDE, CLI
PostToolUseAfter tool executionIDE, CLI
PostFileCreateAgent creates a fileIDE
PostFileSaveAgent saves a fileIDE
PostFileDeleteAgent deletes a fileIDE
PreTaskExecutionBefore spec task (can block)IDE
PostTaskExecutionAfter spec taskIDE

Important: File triggers respond only to changes made by the agent, not to manual editor edits.

Actions

  • agent — Inject a prompt into the conversation (field prompt). Consumes credits.
  • command — Shell command in the project root (field command). Event data via STDIN, exit code controls behavior (0 = OK, 2 = block). Does not consume credits.

Additional Fields

  • matcher — Regex. Against tool name for tool events, against path for file events
  • Tool categories: read, write, shell, web, spec, *
  • Prefixes: @mcp, @powers, @builtin
  • timeout (command actions, default 60s), enabled, confirm (Stop trigger only)

Example: Lint on Save

// .kiro/hooks/lint-on-save.json
{
  "version": "v1",
  "hooks": [{
    "name": "Lint on Save",
    "trigger": "PostFileSave",
    "matcher": "\\.(ts|tsx)$",
    "action": { "type": "command", "command": "npm run lint" }
  }]
}

Example: Test Update via Agent

{
  "version": "v1",
  "hooks": [{
    "name": "TypeScript Test Updater",
    "trigger": "PostFileSave",
    "matcher": "src/.*\\.ts$",
    "action": {
      "type": "agent",
      "prompt": "Analyze the changes and update the corresponding test file."
    }
  }]
}

Location: .kiro/hooks/<name>.json (schema version v1) — shareable via Git with the entire team.

Agent Steering

Steering gives Kiro persistent workspace knowledge through Markdown files. Conventions don't need to be repeated in every chat.

Scopes

ScopePathDescription
Workspace.kiro/steering/This project only
Global~/.kiro/steering/All workspaces
Team~/.kiro/steering/Distributed via MDM/Group Policy

Inclusion Modes

always

---
inclusion: always
---

Always loaded. For core standards.

fileMatch

---
inclusion: fileMatch
fileMatchPattern: "**/*.tsx"
---

Only for matching files.

manual

---
inclusion: manual
---

Via #name or /slash-command.

auto

---
inclusion: auto
name: api-design
description: REST API patterns
---

Automatically on matching request.

Foundation Files (auto-generated)

  • product.md — Product purpose, target audience, features
  • tech.md — Frameworks, libraries, constraints
  • structure.md — File organization, naming, architecture

Example: API Standards

---
inclusion: fileMatch
fileMatchPattern: ["**/api/**/*.ts", "**/routes/**/*.ts"]
---

# REST API Standards
- Use kebab-case: /user-profiles
- Use plural nouns: /users
- Error format: { "error": { "code": "...", "message": "..." } }
- All endpoints require Bearer token

Kiro also supports AGENTS.md (open standard) — always included, in the workspace root or ~/.kiro/steering/.

Note: In the CLI, inclusion modes are not supported — all steering files are loaded automatically there. Custom agents do not load steering automatically; it must be specified in the resources field.

Agent Skills

Skills are portable instruction packages following the open Agent Skills Standard. They bundle instructions, scripts, and templates.

Progressive Disclosure

  1. Discovery: Only name + description loaded
  2. Activation: On matching request: full instructions
  3. Execution: Scripts/references loaded on demand

Structure & Example

my-skill/
├── SKILL.md           # Required
├── scripts/           # Optional
├── references/        # Optional
└── assets/            # Optional
---
name: pr-review
description: Review pull requests for code quality and security.
---

## Review Process
1. Check for security vulnerabilities
2. Verify error handling
3. Confirm test coverage
4. Review naming and structure

Scopes & Activation

ScopePath
Workspace.kiro/skills/
Global~/.kiro/skills/
  • Automatic: Kiro recognizes matching requests
  • Manual: /skill-name as slash command
  • Import: From GitHub URL or local folder

Powers

Powers give the AI agent instant access to specialized knowledge. They bundle MCP tools, workflows, and best practices — dynamically loaded via keyword matching.

How Powers Work

  1. Kiro reads the task description
  2. Evaluates installed Powers based on keywords
  3. Loads only relevant Powers into context
  4. Automatically deactivates on topic change

Content & Structure

Powers follow the open Agent Plugins specification. Older Powers in the POWER.md format still work.

my-power/
├── plugin.json     # Required manifest (keywords for activation)
├── skills/         # Agent Skills
│   └── setup/SKILL.md
├── mcp.json        # MCP server config (optional)
└── dev.kiro/       # Kiro extensions like steering (optional)

Installation

  • One-click install from the marketplace (kiro.dev/powers)
  • Directly from GitHub URLs
  • Available: IDE, CLI (v3+), Web. Creating: IDE and CLI v3 only

Available Partner Powers

Datadog, Dynatrace, Figma, Neon, Netlify, Postman, Supabase, Stripe, Strands SDK, and AWS Aurora.

The Agent Plugins spec is maintained by teams at Amazon, Cursor, Microsoft, OpenAI, and Vercel.

Comparison: Skills vs. Powers vs. Steering

PropertySkillsPowersSteering
PurposeReusable workflowsTool integrations + knowledgeProject conventions
FormatSKILL.md + scripts/plugin.json + skills/ + mcp.jsonMarkdown files
ActivationAuto or /slashDynamic by keywordalways / fileMatch / manual / auto
MCP ToolsNoYes (dynamic)No
PortabilityOpen standardKiro-specificKiro-specific
Ideal forTeam workflowsExternal servicesPersistent rules

Rule of thumb: MCP integration? → Power. Portable workflows? → Skill. Persistent rules? → Steering.

💡 Pro Tips from the Kiro Team

Official best practices from the Kiro documentation and AWS blogs for maximum productivity.

Specs: Working Effectively

  • Vibe → Spec: In chat simply say Generate spec — Kiro takes over the existing context
  • Reference #spec: Use #spec:feature-name in chat to include a spec as context
  • Multiple small specs: One spec per feature instead of one giant spec for the entire codebase
  • Sync Files: Click in tasks.md when tasks are already completed — Kiro marks them automatically
  • Quick Plan for familiar features (fast, no approval gates). Standard specs for unknown territory.
  • Analyze Requirements: Use after auto-generation — finds contradictions, ambiguities, and gaps
  • Import from JIRA/Confluence: Copy file to repo, then #file.md Generate a spec from it

Steering: Maximum Impact

  • 1 topic per file: api-standards.md, testing-patterns.md — not everything in one file
  • fileMatch over always: Saves context space. Only load when relevant.
  • Concrete examples: Code snippets and before/after comparisons instead of vague descriptions
  • Generate foundation files: Kiro Panel → Steering → "Generate Steering Docs" for product.md, tech.md, structure.md
  • Explain the why: Not just "Use kebab-case" but also why (consistency with API gateway)
  • File references: #[[file:api/openapi.yaml]] to link live workspace files

Hooks: Automate Safely

  • Exclusion patterns: Always exclude generated files: !**/*.test.ts, !**/node_modules/**
  • Share via Git: Commit hooks in .kiro/hooks/ — the whole team benefits immediately
  • userTriggered for risky tasks: Security scans, deployments, DB migrations triggered manually
  • Descriptive prompts: The more context in the hook prompt, the better the result
  • Test individually: Activate hooks one at a time, not all at once

Models: Save Credits

  • Auto for daily work: Best price-performance ratio (1.0x baseline)
  • Opus for hard tasks: Multi-file architecture, long sessions, complex bugs (2.2x credits)
  • Qwen3 Coder Next: Only 0.05x credits! Ideal for simple tasks and long coding sessions
  • Haiku for speed: Fast model, 0.4x credits, good for quick iterations
  • Track credit usage: Check Account Settings → Usage Dashboard regularly

General Workflow Tips

  • Commit often: Before and after agent actions — easy rollback on errors
  • Supervised Mode: For security code, prod config, infrastructure changes
  • New chat for new topics: Fresh context = better results
  • Use context providers: #File, #Folder, #Problems, #Terminal, #Git Diff
  • Use images: Architecture diagrams, whiteboard photos, screenshots via drag&drop into chat
  • MCP for current docs: AWS Docs MCP instead of outdated model knowledge
  • Powers over raw MCP: Powers load tools dynamically — saves 40%+ context tokens

MCP Server (Model Context Protocol)

MCP enables Kiro to communicate with external servers for specialized tools, prompts, and resources.

Configuration

LevelPath
User (Global)~/.kiro/settings/mcp.json
Workspace.kiro/settings/mcp.json

Example

{
  "mcpServers": {
    "aws-docs": {
      "command": "uvx",
      "args": ["awslabs.aws-documentation-mcp-server@latest"],
      "env": { "FASTMCP_LOG_LEVEL": "ERROR" },
      "disabled": false,
      "autoApprove": []
    },
    "supabase-local": {
      "command": "npx",
      "args": ["-y", "@supabase/mcp-server-supabase"],
      "env": {
        "SUPABASE_URL": "${SUPABASE_URL}",
        "SUPABASE_ANON_KEY": "${SUPABASE_ANON_KEY}"
      }
    }
  }
}

Popular MCP Servers

ServerFunction
AWS DocumentationSearch/read AWS docs
AWS MCP ServerAuthenticated AWS access
SupabaseDB operations, RLS
StripePayment integration
MemoryPersistent storage
SonarQubeCode quality

MCP alone loads all tools at startup (high token usage). MCP in a Power loads tools dynamically — more efficient.

Kiro as an IDE

Based on Code OSS. VS Code settings and Open VSX extensions work out of the box.

A single agent harness, accessed through multiple surfaces:

💻 IDE (Desktop)

Mac, Windows, Linux. Runs locally.

⌨️ CLI

Terminal, headless, CI/CD, custom agents.

🌐 Web

app.kiro.dev. Cloud sandbox, delivers changes as pull requests.

📱 Mobile

iOS (preview via TestFlight). Attaches to cloud sessions.

Kiro Crew: Orchestration of agent teams. ACP-compatible editors (JetBrains, Zed) can connect via the Agent Client Protocol.

Kiro Panel

  • Specs — Create and manage
  • Agent Hooks — Create, enable, disable
  • Steering & Skills — Manage
  • MCP Servers — Status and configuration
  • Powers — Installed Powers

Context in Chat

  • #File / #Folder — Reference file/folder
  • #Problems — Current errors/warnings
  • #Terminal — Terminal output
  • #Git Diff — Current changes
  • Images, PDFs, DOCX via drag&drop

Project Structure

my-project/
├── .kiro/
│   ├── settings/mcp.json
│   ├── steering/
│   │   ├── product.md
│   │   ├── tech.md
│   │   └── structure.md
│   ├── hooks/
│   │   └── test-sync.json
│   ├── skills/
│   │   └── pr-review/SKILL.md
│   └── specs/
│       └── feature-reviews/
│           ├── requirements.md
│           ├── design.md
│           └── tasks.md
└── src/

⚠️ Known Issues & Limitations

Kiro is powerful but has its limits. Here are the most common issues from the community and official troubleshooting tips.

Steering: Why It Sometimes Doesn't Work

Common causes:

  • Context window limit: In long conversations, steering falls out of context. The agent "forgets" rules.
  • Too many always files: Compete for context space and crowd each other out.
  • Conflicting instructions: Global vs. workspace — workspace wins, but the agent can get confused.
  • Vague wording: "Write good code" is too unspecific. Concrete rules needed.
  • Wrong fileMatch pattern: Glob doesn't match the file → steering never loads.
  • Frontmatter errors: Missing --- or YAML syntax errors = file ignored.

Workarounds:

  • Keep steering files short (1 topic per file)
  • fileMatch instead of always where possible
  • Include concrete code examples
  • For long sessions: start a new chat
  • Validate frontmatter with a YAML validator

Rate Limiting & Usage Limits

Problem: "Too many requests" or "Please return tomorrow to continue building" messages.

  • Unified credit pool: Vibe and Spec draw from the same pool
  • Auto (recommended): Kiro's model router, 1.0x baseline
  • Budget: Qwen3 Coder Next (0.05x), MiniMax M2.1 (0.15x), DeepSeek 3.2 & MiniMax M2.5 (0.25x), Haiku 4.5 (0.4x)
  • Premium: Claude Opus (4.5 to 5, each 2.2x), Claude Sonnet (4.0 to 5, 1.3x)
  • Others: GPT-5.6 (Luna 0.1x / Terra 1.0x / Sol 2.4x), GLM-5 (0.5x)
  • Multipliers relative to Auto. The model catalog changes frequently — check the Kiro docs for current values.

Workaround: Track credit usage in the account dashboard. Ask simple questions in Vibe mode (cheaper). Reserve specs for complex features.

Shell Integration & Terminal

Problem: Kiro gets stuck at "Working...", doesn't see terminal output, or shows strange characters.

  • Shell customizations (Oh My Posh, Powerlevel10k) interfere
  • Shell integration not correctly installed
  • Fish shell needs a manual patch

Workarounds:

  • Command Palette → "Kiro: Enable Shell Integration"
  • Powerlevel10k: POWERLEVEL9K_TERM_SHELL_INTEGRATION=true in .p10k.zsh
  • Disable shell themes in Kiro (TERM_PROGRAM check)
  • Manual integration in ~/.zshrc or ~/.bashrc

Prompt Injection & Security

AWS Security Bulletin (AWS-2025-019): Prompt injection vulnerabilities in Kiro and Q Developer plugins. Invisible control characters in files can obscure commands that execute without confirmation.

  • Affects: Open chat sessions + access to malicious files
  • Commands like find, grep, echo can run without HITL confirmation

Workaround: Always keep Kiro up to date (patches available). Use Supervised Mode for unknown repositories. Don't open files from untrusted sources.

Platform-Specific Issues

  • macOS: "Kiro is damaged" message → sudo xattr -d com.apple.quarantine /Applications/Kiro.app
  • Windows: "Updates disabled" when installed as admin → Disable admin checkbox in Properties
  • Windows OneDrive: Desktop path conflicts → Create symbolic link
  • WSL: Remote SSH and WSL connections partially unstable
  • PowerShell: Script execution blocked → Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

Context Window & Context Loss

  • Context is automatically compressed at limit → details are lost
  • Large files are only partially read
  • Earlier instructions can be "forgotten"

Workaround: Break complex tasks into smaller pieces, use specs, reference relevant files with #File, start new chat for new tasks.

File Writing Issues

  • Very large files (>500 lines) are written in parts (write + append)
  • Windows paths can cause issues
  • Multiple "Editing" entries for the same file appear in the editor

Workaround: Split large files, delete and regenerate on errors, use Supervised Mode.

Hooks: Unexpected Behavior

  • Infinite loops: Hook modifies file → triggers another hook → infinite loop
  • Too broad patterns: **/* also catches generated files

Workaround: Exclusion patterns (!**/*.test.ts), test hooks individually, userTriggered for risky actions.

MCP Server: Connection Issues

  • uvx or npx not installed or not in PATH
  • Missing/invalid environment variables (API keys)
  • JSON syntax errors in mcp.json
  • GitHub MCP: Rate limiting with too many API calls
  • Server timeout on slow connections

Workaround: Check logs (Output → "Kiro - MCP Logs"). Manually reconnect server. Validate mcp.json. Test uvx --version.

General Agent Limitations

  • Hallucinations: Agent can invent code patterns. Always review output.
  • Outdated knowledge: Without MCP, the agent may not know the latest API.
  • Non-determinism: Same prompt can yield different results.
  • Extensions: Only Open VSX, not VS Code Marketplace.
  • IAM Identity Center: Sessions expire after 8h, re-authentication required.

Best Practices:

  • Supervised Mode for critical changes
  • Specs for complex features instead of long chats
  • Frequent git commits for easy rollback
  • Always review agent output (especially security)
  • Use MCP servers for up-to-date documentation
  • Update Kiro regularly (security patches)

Sources: