Agent Skills

Skills are portable instruction packages that extend what Kiro knows how to do. Each skill contains instructions for a specific workflow, whether that's reviewing pull requests, deploying infrastructure, or following your team's coding standards.

Skills follow the open Agent Skills standard, making them shareable across tools and teams.

How skills work

When you start a chat session, Kiro discovers available skills by reading their names and descriptions. When your request matches a skill's description, Kiro automatically loads the full instructions and follows them.

> Review this PR for security issues

[skill: pr-review activated]

I'll review the PR using the security checklist...

Skills activate automatically based on your request. There's no slash command to invoke them. Kiro decides when a skill is relevant by matching your request against skill descriptions.

To see what skills are available in your current session, use the /context show command or ask Kiro directly:

> /context show

Skill locations

Skills can be stored in two places:

When skills share the same name, workspace skills take priority over global skills.

Default agent

The default agent automatically loads skills from both locations. No configuration required.

Custom agents

Custom agents don't load skills by default. You need to explicitly add them to the agent's resources field:

{
  "name": "my-agent",
  "resources": [
    "skill://.kiro/skills/*/SKILL.md",
    "skill://~/.kiro/skills/*/SKILL.md"
  ]
}

The skill:// URI scheme supports specific paths, glob patterns, and home directory expansion.

Creating a skill

A skill is a folder containing a SKILL.md file:

pr-review/
├── SKILL.md           # Required
└── references/        # Optional
    └── checklist.md

SKILL.md format

The file starts with YAML frontmatter followed by markdown instructions:

---
name: pr-review
description: Review pull requests for code quality, security issues, and test coverage. Use when reviewing PRs or preparing code for review.
---

## Review checklist

When reviewing a pull request:

1. Check for vulnerabilities, injection risks, exposed secrets
2. Verify edge cases and failure modes are handled
3. Confirm new code has appropriate tests
4. Ensure variables and functions have clear names

## Common issues to flag

- Hardcoded credentials or API keys
- Missing input validation
- Unhandled promise rejections
- Console.log statements left in production code

Frontmatter fields

The description field determines when Kiro activates the skill. Include specific keywords and actions that match how you'd phrase requests.

Reference files

For extensive documentation, use a references/ folder:

aws-deployment/
├── SKILL.md
└── references/
    ├── ecs-guide.md
    └── troubleshooting.md

Reference the files in your SKILL.md:

For ECS deployments, follow the guide in `references/ecs-guide.md`.

Kiro loads reference files only when the instructions direct it to.

Example

A CDK deployment skill:

cdk-deploy/
├── SKILL.md
└── references/
    └── stack-patterns.md

SKILL.md:

---
name: cdk-deploy
description: Deploy AWS CDK stacks with best practices. Use when deploying infrastructure, running cdk deploy, or troubleshooting CDK issues.
---

## Deployment workflow

1. Run `cdk synth` to validate templates before deploying
2. Use `cdk diff` to preview what will change
3. Run `cdk deploy` and review IAM changes

## Pre-deployment checks

- Verify AWS credentials are configured for the target account
- Check that the CDK version matches the project's requirements
- Review `references/stack-patterns.md` for environment-specific patterns

## Rollback procedure

If deployment fails:
1. Check CloudFormation console for the specific error
2. Run `cdk destroy` only if the stack is in a failed state
3. Fix the issue and redeploy

Usage:

> Deploy my CDK stack to staging

[skill: cdk-deploy activated]

I'll follow the deployment workflow. First, let me synthesize the templates...

Best practices

Write precise descriptions. The description determines when Kiro activates the skill:

• Good: Review pull requests for security vulnerabilities and test coverage. Use when reviewing PRs or preparing code for review.
• Vague: Helps with code review

Keep SKILL.md actionable. Put detailed reference material in references/ files.

Choose the right scope. Use global skills for personal workflows you use everywhere. Use workspace skills for team procedures and project-specific conventions.

Version control workspace skills. Commit .kiro/skills/ to your repository so the team shares the same workflows.

Troubleshooting

Related

• Steering - Project-specific context and conventions
• Custom Agents - Agent configuration and resources
• Agent Skills specification - Full format details