Table of Contents
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
| Question | Steering doc | Skill |
|---|---|---|
| Does it mostly describe what the project is? | ✅ | |
| Does it describe how to do a multi-step process with tools? | ✅ | |
| Is it useful as passive context for any conversation? | ✅ | |
| Does it need MCP servers or external integrations? | ✅ | |
| Could you explain it in a README? | ✅ | |
| Would it break if a step was skipped or reordered? | ✅ |
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.