Skills

A skill is a reusable instruction pack that the agent loads only when it is relevant. Each one is a folder with a SKILL.md file inside, so a procedure you would otherwise re-explain every time becomes something the agent picks up on its own at the moment it applies.

What is a skill?

The format is deliberately small. A folder, a SKILL.md, YAML front matter with a name and a description, then the procedure in Markdown. Optional scripts and templates can live alongside it in the same folder.

---
name: release-notes
description: Writes release notes from merged PRs. Use when preparing a release.
---

# Writing release notes

1. Group changes into Added / Changed / Fixed.
2. Lead each item with the user impact, not the implementation.
3. Link each item to its PR.

Kiro follows the open Agent Skills An open standard for portable agent instruction packages, built around a SKILL.md file with a name and description in front matter. standard, which means a skill written for Kiro is readable by other tools that support the same format.

Why it exists

Steering answers “what should the agent always know?” That question has a hard limit: everything you make always-on is paid for on every turn, and a project has far more procedures than it has universal truths. Your release-notes format, your incident write-up template, your data-modeling checklist, the way you write migrations. All valuable, none relevant most of the time.

Skills solve this with a two-stage load. Names and descriptions are cheap, so all of them are visible at session start. The body is expensive, so it only arrives when the request matches. You get a large library at the context cost of a small index.

How it works

Discovery and activation. At session start Kiro reads the name and description of every skill it can see. When your request matches a description, the full skill loads into the conversation. You can also invoke one directly as a slash command using its name, which is the reliable path when you know exactly what you want.

Scopes. Workspace skills live in .kiro/skills/ and personal skills in ~/.kiro/skills/. Kiro’s configuration documentation puts skills in the group that merges across scopes, so your personal library and the team’s both apply. Custom agents can reference a specific skill through a skill:// URI in their resources.

What belongs in the body. Steps, not background. A skill is read at the moment of doing, so it should look like a checklist a competent person could follow: numbered steps, concrete file names, the decision points that matter, and the mistakes to avoid. Save the reasoning for one line per step.

What belongs in the folder. If the procedure involves a template, ship the template. If it involves a script, ship the script. A skill that says “use the standard template” and then does not include it is a skill that will be followed differently every time.

Common mistakes

A vague description. The description is the entire activation mechanism. “Helps with databases” will never fire, because nothing a person types looks like that. The fix: name the subject and the trigger. “Guide for DynamoDB data modeling. Use when designing or analyzing DynamoDB schemas.” tells Kiro exactly when to reach for it.

Writing a steering file and calling it a skill. A document that describes your architecture is context, not procedure, and putting it in a skill means it loads late and only sometimes. The fix: if the agent should know it whether or not it is doing a specific job, it belongs in steering.

One giant skill covering a whole domain. Broad skills match broadly, load a lot of text, and mostly supply steps that do not apply. The fix: one job per skill, with the description written as the sentence you would say when handing that job over.

Skills that duplicate a spec. A skill is how to do a kind of work, repeatedly. A spec is what to build, once. The fix: if it has acceptance criteria, it is a spec.

Permissions and safety

Skill loading is governed by the skill capability in Kiro’s permission model, so the usual ranking applies: deny beats ask, which beats allow in every scope. Worth remembering when a skill you can see never seems to activate.

Where it fits

Skills and steering are the pair people mix up most, and the distinction is worth memorizing: steering is standing context about the project, a skill is a procedure for a job. Custom agents are the third member of that family, packaging identity and tool access rather than knowledge. A reviewer agent with a code-review skill and steering describing your conventions is all three layers doing exactly one thing each.

Powers are the technology-specific cousin: a bundle of MCP configuration plus steering, loaded on demand for a particular vendor or platform.

By surface: skills work in the IDE and the CLI from the same folders. Kiro Crew lists skills among its agent capabilities, and skills configured in Kiro Web sync down to local IDE and CLI sessions as read-only previews since September 1, 2026.

Learn more

• Write a skill is the ten-minute build.
• Steering covers the always-on half of the pair.
• Advanced Tutorial uses skills alongside specs and agents.
• Use Cases shows which recurring jobs are worth turning into skills.
• Cheat Sheet has the file layout in card form.