Write a Skill

A skill is a written procedure the agent can load when it needs it. Put a SKILL.md in .kiro/skills/ and Kiro reads its description at session start, then pulls in the full instructions when a request matches.

When to use this

Write a skill the second time you explain the same procedure. Release notes, adding a new pipeline source, the deployment checklist, how your team writes migrations. Steering is for facts that always apply. Skills are for procedures that apply sometimes, which is why they load on demand instead of on every turn.

Steps

1. Pick one procedure with a clear start and end. “How we add a new API endpoint” is a skill. “How we write good code” is not.

2. Create the folder and file. Workspace: .kiro/skills/release-notes/SKILL.md. Personal: ~/.kiro/skills/release-notes/SKILL.md.

3. Write the front matter. The name identifies the skill and the description is what Kiro matches against, so describe the situation that should trigger it.

   .kiro/skills/release-notes/SKILL.md

   ---
   name: release-notes
   description: Use when preparing release notes or a changelog entry
     for a tagged version of this repository.
   ---
   
   # Release notes
   
   1. Collect merged pull requests since the previous tag.
   2. Group them under Added, Changed, Fixed, Removed.
   3. One line each, written for a user, not a committer.
   4. Link the pull request number at the end of each line.
   5. Put the result in CHANGELOG.md above the previous entry.

4. Keep the body actionable. Numbered steps, concrete file names, real commands. Push long reference material into other files in the same folder and mention them from SKILL.md.

5. Add scripts or templates alongside SKILL.md when a step is mechanical. The skill folder can carry them.

6. Commit workspace skills so the team shares them. Skills merge across the global and workspace scopes, so a personal skill and a team skill can both be available.

7. Reference a skill from a custom agent with a skill:// URI in the agent’s resources when a particular persona should always have it.

Check it worked

Start a new session and phrase a request the way your description says, without naming the skill. If it activates, the description works. Then invoke it explicitly as /release-notes and confirm the steps run in order. Kiro loads skill instructions through its disclose_context tool, so seeing that call is a sign the skill body reached the model.

Common problems

• The skill never activates. The description describes the skill instead of the situation. “Release note formatting rules” matches nothing. “Use when preparing release notes for a tagged version” matches.
• Two skills fight. Their descriptions overlap. Make each one narrower, or merge them.
• The skill is enormous. Only the name and description load at session start, but the body loads when it activates. Keep the body to the steps, and move the reference material to a companion file.
• It works for you and not the team. You wrote it in ~/.kiro/skills/. Move it to .kiro/skills/ and commit it.
• You wanted vendor knowledge. Third-party technology belongs in a Power, which bundles MCP configuration too.

Related

• Skills explains the standard and discovery.
• Add a Power covers the vendor-knowledge equivalent.
• Advanced Tutorial shows skills inside a team workflow.