Create Your First Steering File

A steering file is a Markdown file that gives Kiro permanent knowledge about your project. Put three of them in .kiro/steering/ and the agent stops guessing your stack, your folder layout, and your house rules in every new chat.

When to use this

Use this on any project you will work on more than once. If you have explained the same convention to the agent twice, it belongs in steering. Do this before you write hooks or custom agents, because those build on the same knowledge.

Steps

1. Create the folder .kiro/steering/ in the root of your project.

2. Create product.md and describe what the project is and who it is for. Keep it to one screen.

   .kiro/steering/product.md

   # Product
   
   Internal warehouse inventory service. Tracks stock levels and
   reservations. Correctness beats speed: a wrong count costs money.

3. Create tech.md and list the languages, frameworks, and versions you actually use, plus any rule about adding dependencies.

4. Create structure.md and describe the folder layout and where new code goes.

5. Add a fourth file only when a rule applies to part of the tree. Put the front matter at the very top, before any heading.

   .kiro/steering/api-conventions.md

   ---
   inclusion: fileMatch
   fileMatchPattern: "src/api/**"
   ---
   
   # API conventions
   
   Routers stay thin. Business logic lives in src/services/.
   Every endpoint returns a typed error body, never a bare string.

6. Choose the inclusion mode for each extra file. inclusion: always is the default. inclusion: manual loads only when you type #steering-file-name in chat. inclusion: auto needs a name: and a description:, and matches against what you ask for.

7. Commit .kiro/steering/ so the whole team shares it. Put personal preferences in ~/.kiro/steering/ instead, where they apply to every project you open.

Check it worked

Start a new chat session and ask for a small change that touches one of your rules. Ask for a new endpoint and see whether the agent puts the logic in src/services/. A second check: ask the agent which steering files are loaded. The CLI configuration panel (v2.21.0) also lists steering alongside agents, MCP servers, Powers, skills, and hooks.

Common problems

• The file is ignored. The YAML front matter must be the first content in the file. A blank line or a heading above it breaks the parse.
• fileMatchPattern never matches. The glob is relative to the workspace root, so write src/api/**, not /src/api/** or ./src/api/**.
• Rules conflict. Steering merges across the global and workspace scopes, and the workspace file wins. If a personal rule keeps overriding a team rule, move it out of ~/.kiro/steering/.
• The file is huge. One domain per file. A single 900-line steering file costs context on every turn and gets ignored in practice.
• Secrets leak in. Never put tokens, keys, or customer data in steering. Steering is loaded into the model’s context on every turn.

Related

• Steering explains the concept and every inclusion mode.
• Use AGENTS.md as steering covers the portable alternative.
• Beginner Tutorial walks through your first steering file inside a full project.