---
name: aws-kiro-spec-ide
description: "Drive Kiro's spec-first gate — EARS requirements, design, tasks — for traceable AWS-native migrations. Work inside Kiro's three-doc spec workflow: requirements.md in EARS format (WHEN/WHILE/THE SYSTEM SHALL), design.md with architecture and data flows, and tasks.md with traceable, checkbox task lists linked back to requirements. Covers steering files for project conventions, agent hooks for event-triggered automation, and vibe-vs-spec mode tradeoffs for production AWS migrations."
license: MIT
---

# AWS Kiro Spec IDE

Kiro is AWS's agentic IDE built around a spec-first workflow: before code is written, the agent produces three living documents that gate the work. This skill drives that gate end to end — turning a vague migration ask into EARS-formatted requirements, a reviewed design, and a traceable task list — so teams moving workloads onto AWS keep an auditable line from "what we asked for" to "what shipped." It's aimed at engineers and architects running AWS-native migrations or greenfield builds who want structure instead of vibe-coding.

## When to use it

- You're migrating a service to AWS (Lambda, DynamoDB, ECS, Step Functions) and need design and acceptance criteria captured before implementation.
- A stakeholder handed you an ambiguous brief and you want it pinned down as testable requirements.
- You want each code task to trace back to a specific requirement for review or compliance.
- You're enforcing team conventions across multiple Kiro contributors.

## How it works

The skill operates inside Kiro's `.kiro/specs/<feature>/` directory and the three-document flow:

- **requirements.md** — user stories plus acceptance criteria in EARS notation: `WHEN <trigger>`, `WHILE <state>`, `IF <condition>`, each paired with `THE SYSTEM SHALL <response>`. The agent drafts these from your prompt and iterates until you approve.
- **design.md** — architecture, component breakdown, data flow, and interface decisions, with the AWS services named explicitly.
- **tasks.md** — an ordered, checkbox task list where each item references the requirement IDs it satisfies. Kiro executes tasks one at a time on request.

It also wires up **steering files** (`.kiro/steering/*.md`) for persistent project conventions, and **agent hooks** that trigger actions on IDE events (e.g., regenerate tests when a source file is saved).

## Example

```bash
curl -fsSL --create-dirs -o ~/.claude/skills/aws-kiro-spec-ide/SKILL.md https://claudeskil.com/skills/aws-kiro-spec-ide/SKILL.md

# In Kiro, start a spec for a migration
> Create a spec to migrate the orders API from EC2 to Lambda + DynamoDB
```

```markdown
# requirements.md (excerpt)
### Requirement 2
**User Story:** As a client, I want order reads to stay fast during migration.
#### Acceptance Criteria
1. WHEN a GET /orders/{id} request arrives THE SYSTEM SHALL return the order within 200ms p99.
2. IF the DynamoDB item is absent THE SYSTEM SHALL return HTTP 404.
```

```markdown
# tasks.md (excerpt)
- [ ] 2.1 Implement DynamoDB GetItem handler (_Requirements: 2.1, 2.2_)
- [ ] 2.2 Add p99 latency assertion to integration test (_Requirements: 2.1_)
```

## Tips & gotchas

- Approve **requirements.md** before letting the agent touch design — skipping the gate is the most common way specs drift.
- Keep steering files small and scoped; broad steering docs bloat every prompt's context. Use front-matter inclusion modes (always / file-match / manual) to control when they load.
- Execute tasks individually from `tasks.md` rather than asking Kiro to "do everything" — that's what preserves traceability.
- Hooks fire on IDE events, not on a schedule; don't use them for long-running batch jobs.

## FAQ

**Do I have to write EARS by hand?** No — the agent drafts the EARS criteria from your description; you review and refine. EARS just keeps each criterion atomic and testable.

**Can I retrofit a spec onto existing code?** Yes. Point Kiro at the codebase and ask it to generate requirements and design from what exists, then add tasks for the changes you want.

**Are specs tied to AWS only?** The workflow is general, but this skill emphasizes AWS-native targets and names concrete services in design.md and tasks.md.