Skip to content
mif-docs

Skill reference: kiro-design

Skill reference: kiro-design

Section titled “Skill reference: kiro-design”

The kiro-design skill authors one document genre: the design.md of an AWS Kiro three-document spec set. This reference describes what that document type is, how the skill produces one, when it earns its place, and the provenance and sources behind it.

PropertyValue
AuthorsThe design.md of a Kiro spec set
Purpose groupKiro spec set
MIF conceptTypesemantic
Target MIF level3
Primary sourceKiro — Specs

What this document type is

Section titled “What this document type is”

design.md is the second of the three linked Kiro artifacts. Where kiro-requirements states what the feature must do, design.md states how it will be built — the technical design that turns numbered requirements into an implementable shape. It typically covers the architecture and components, data models and interfaces, the sequence of interactions, error handling, and the testing strategy, at whatever depth the feature warrants. Its defining discipline is traceability backward: every design element cites the requirement number it satisfies, so a reviewer can confirm that the design covers all requirements and introduces nothing the requirements do not justify.

This document is not the requirements themselves — the what lives in requirements.md. It is not the build plan — the ordered, checkbox implementation steps live in kiro-tasks, which trace forward from this design. design.md is the hinge of the set: it consumes requirement numbers and emits design decisions that the task list then sequences into work.

How the skill produces one

Section titled “How the skill produces one”

kiro-design is a genre skill: it carries the Kiro design pattern as durable instructions plus exemplars, and writes the artifact over a MIF floor so the result is at once a readable design and a machine-conformant unit.

  • Pattern, made operational. The skill encodes the design sections — architecture, components, data, sequencing, error handling, testing — and enforces that each design choice references the requirement number it serves, refusing anti-triggered work (the what belongs in kiro-requirements; the task list belongs in kiro-tasks).
  • Traceability. Because design elements bind to requirement IDs, the set stays coherent: missing coverage and orphan design both become visible by comparison against requirements.md.
  • Exemplars set the bar. Like every genre in the suite it ships good-l1.md (the MIF Level-1 floor), good.md (the target level — Level 3 here), bad.md (a counter-example), and evals/evals.json. The check-exemplars gate proves good-l1.md validates at L1 and good.md at its target level.
  • MIF projection. The document is authored with MIF frontmatter (via the shared mif-frontmatter substrate) and a conceptType of semantic, reflecting that a design asserts structural facts rather than performed steps. mif-validate proves the Markdown to JSON-LD round-trip is lossless before the document is considered done.

When it is beneficial

Section titled “When it is beneficial”

Reach for kiro-design once requirements are agreed and you need to settle the technical approach before generating work. Its value is that it makes the design reviewable against the requirements: a stakeholder can check coverage and a coding agent can read a structured design rather than inferring one from prose.

Do not use it before requirements exist — the design has nothing to trace back to. Do not use it to enumerate the build steps; that is kiro-tasks. For a one-off architectural narrative outside the Kiro workflow, a Google-style design doc or an arc42 document is a better fit. The cost of the genre is the upkeep of the traceability links as requirements shift.

Example

Section titled “Example”

A design.md for a password-reset feature opens with an overview, then an architecture section describing the reset-token service and the mail dispatcher, a data-model section defining the token record and its expiry, and a sequence section walking the request-link-redeem flow. Each subsection annotates which requirement it satisfies — “satisfies Requirement 1 and Requirement 2” — and an error-handling section maps the unwanted-behaviour EARS criteria from requirements.md onto concrete failure responses.

Provenance & citations

Section titled “Provenance & citations”