Kiro Steering Docs vs Skills — When to Use Which

I just spent the evening setting up my blog’s deployment workflow in Kiro, and at the end I had a choice: do I save this as a steering doc or a skill? They both let you give Kiro persistent context, but they work differently and solve different problems.

Here’s how I think about it after going through the decision myself.

What steering docs do

A steering doc is a markdown file that lives in .kiro/steering/. It’s essentially a note you leave for future Kiro conversations: “here’s how this project works, here’s what to keep in mind.”

When you start a chat, Kiro can automatically include relevant steering files (or you can pull one in manually with #filename). The agent reads it, absorbs the context, and then proceeds with that knowledge.

What a steering doc is good for:

• Project conventions and patterns (“we use Hugo page bundles, not standalone markdown files”)
• Reference info the agent needs repeatedly (“here are the valid categories, here’s the deploy command”)
• Style guides and tone (“write like a human, never sound corporate”)
• Architecture overviews (“S3 bucket → CloudFront → Namecheap DNS”)

What it’s NOT:

• It doesn’t execute anything. It’s pure context.
• It doesn’t have tools, servers, or steps that run automatically.
• It’s just words that inform how the agent behaves.

What skills do

A skill is more structured. It can include:

• Detailed multi-step instructions for complex workflows
• MCP server integrations (external tools the agent can call)
• Logic that goes beyond “know this” into “do this sequence”

What a skill is good for:

• Complex, repeatable processes with many steps (“run the test suite, check coverage, update the changelog, create a PR”)
• Workflows that need external tool access (database queries, API calls, CI/CD pipelines)
• Tasks where the order of operations matters and mistakes are costly

The decision framework

Here’s the question I ask myself:

Is this “things to know” or “things to do”?

If it’s mostly context, conventions, and reference info → steering doc.
If it’s a multi-step procedure that needs precise execution with tools → skill.

For my blog, the answer was obvious: it’s “things to know.” The agent needs to understand the folder structure, front matter format, valid categories, writing style, and deploy command. That’s all context. It doesn’t need to orchestrate a complex multi-tool workflow — it just needs to know what conventions to follow when I say “write a post about my soldering session.”

A few more decision points

What I actually created

For my blog, I made a steering doc with inclusion: manual — meaning I pull it in with #imadestuff-blog only when I’m actually working on the blog. It doesn’t pollute unrelated conversations.

It contains:

• The folder structure
• How to create a post (front matter template, slug rules, image handling)
• Writing style guidelines
• Available shortcodes
• How to deploy
• The color palette
• A “things NOT to do” list

That’s all an agent needs to help me publish content correctly. No tools, no orchestration, no MCP servers. Just context.

If I later build something more complex — say, an automated pipeline that pulls from my Obsidian vault, formats it for Hugo, generates an OG image, deploys, and tweets about it — that would be a skill. Because now there’s a sequence of tool calls that need to happen in order, with external services involved.

The takeaway

Start with a steering doc. It’s simpler, faster to create, and solves 80% of cases. You’re basically writing a good README and putting it where Kiro can find it. Only graduate to a skill when you genuinely need multi-step tool orchestration that goes beyond “know the rules and follow them.”

For most project context — conventions, structure, preferences, do’s and don’ts — a steering doc is the right tool. Save skills for when you’re building something that actually does things, not just knows things.