Creating a New Skill
Relevant source files
The following files were used as context for generating this wiki page:A "Skill" within the Kiro project is a structured set of instructions for an AI assistant, designed to guide it in performing specific, complex tasks. These skills are a core component of the repository's approach to spec-driven development, enabling consistent and high-quality AI collaboration for tasks like requirements engineering, design documentation, and task breakdown.
Skills are defined in SKILL.md files and follow the agentskills.io specification. They encapsulate best practices and methodologies, making them reusable and shareable. The repository contains a collection of pre-defined skills for various phases of software development, and provides a clear process for creating and contributing new ones.
Sources: skills/README.md:1-10, skills/spec-driven-development/SKILL.md:1-10
Skill Anatomy
A skill is defined by a single SKILL.md file located within its own directory under the skills/ folder. The structure consists of two main parts: a YAML frontmatter for metadata and a Markdown body for the instructions.
Sources: skills/README.md:31-34
This diagram shows the basic composition of a SKILL.md file.
Sources: skills/README.md:31-41
Frontmatter
The frontmatter is a YAML block at the top of the SKILL.md file that defines the skill's properties. It is essential for how the skill is identified and used by AI assistants.
Sources: skills/README.md:31-41, skills/design-documentation/SKILL.md:1-10
| Field | Type | Description |
|---|---|---|
name | string | A unique, machine-readable name for the skill. |
description | string | A human-readable summary of what the skill does (up to 1024 characters). |
license | string | The license under which the skill is distributed, typically "MIT". |
compatibility | list | A list of AI assistants or environments the skill is compatible with (e.g., Claude Code, Cursor). |
metadata | object | An object containing additional metadata, such as category, complexity, author, and version. |
Sources: skills/README.md:32-41, skills/design-documentation/SKILL.md:2-10, skills/spec-driven-development/SKILL.md:2-10
Below is an example of a typical frontmatter block.
---
name: design-documentation
description: Transform approved requirements into comprehensive technical designs. Define system architecture, component interactions, data models, and interfaces to create a blueprint for implementation.
license: MIT
compatibility: Claude Code, Cursor, VS Code, Windsurf
metadata:
category: methodology
complexity: intermediate
author: Kiro Team
version: "1.0.0"
---
Sources: skills/design-documentation/SKILL.md:1-10
Markdown Body
The body of the SKILL.md file contains the detailed instructions for the AI assistant. It is written in Markdown and should be structured logically with headings, lists, code blocks, and examples to guide the AI through the desired process. The content should be a comprehensive guide on "When to Use This Skill," the "Step-by-Step Process," "Common Pitfalls," and provide clear examples.
For instance, the requirements-engineering skill details how to use the EARS format to transform ideas into testable requirements, while the design-documentation skill provides a template and process for creating technical blueprints.
Sources: skills/requirements-engineering/SKILL.md:12-18, skills/design-documentation/SKILL.md:12-24
Contribution Process
Adding a new skill to the repository follows a simple, structured process designed to ensure quality and consistency.
This flowchart outlines the steps to contribute a new skill.
Sources: skills/README.md:47-52
-
Create a Directory: Start by creating a new directory for your skill under the
skills/folder. The directory name should match thenamefield in your skill's frontmatter.
Sources: skills/README.md:48 -
Add
SKILL.md: Inside the new directory, create aSKILL.mdfile. This file must start with the YAML frontmatter containing all required fields, followed by the instructional Markdown content.
Sources: skills/README.md:49 -
Validate the Skill: The repository includes a validation script to check for format compliance. Run this script from the root of the repository to ensure your skill meets the required standards.
./scripts/validate-skills.shSources: skills/README.md:43-45, skills/README.md:50
-
Submit a Pull Request: Once your skill is created and passes validation, submit a pull request for it to be reviewed and merged into the main repository.
Sources: skills/README.md:51
Special Skill Types: Steering Documents
A notable application of the skill system is the create-steering-documents skill. This skill doesn't just provide instructions; it generates a set of project guideline files within a .kiro/steering/ directory. These "steering documents" provide persistent, contextual guidance to AI assistants for a specific project, ensuring consistency in areas like code quality, Git workflow, and API design.
Sources: skills/create-steering-documents/SKILL.md:1-6, commands/create-steering-documents-standalone.md:13-16
The create-steering-documents skill generates a directory structure like the one below.
Steering Document Inclusion Logic
Steering documents use frontmatter to control when they are included in the AI's context. This allows for fine-grained control over the guidance provided.
inclusion Value | Description |
|---|---|
always | The document is included in every interaction. This is the default if no frontmatter is present. |
fileMatch | The document is included only when files matching the fileMatchPattern are in the current context. |
manual | The document is only included when explicitly referenced by the user. |
Sources: skills/create-steering-documents/SKILL.md:222-226, commands/create-steering-documents-standalone.md:245-250
Here is an example of frontmatter for a fileMatch steering document.
---
inclusion: fileMatch
fileMatchPattern: '*.tsx|*.jsx|*.vue|*.svelte'
---
Sources: skills/create-steering-documents/SKILL.md:99-102
Summary
Creating a new skill involves defining a structured set of AI instructions within a SKILL.md file, complete with standardized metadata. This modular approach allows for the encapsulation of best practices for various development tasks, from spec creation to generating project-wide standards with steering documents. The contribution process is straightforward, with validation checks in place to maintain high quality across the skill ecosystem.
Sources: skills/README.md, skills/create-steering-documents/SKILL.md