What Information Is Stored in the YAML Frontmatter of a SKILL.md File?

The YAML frontmatter of a SKILL.md file stores metadata including name, description, and optional version fields that enable the Agent Toolkit to discover, register, and index skills.

The AWS Agent Toolkit for AWS relies on SKILL.md files to define reusable capabilities across the ecosystem. Each skill file begins with a YAML frontmatter block that supplies essential metadata used by the toolkit to identify, route, and present the skill to users, keeping configuration strictly separate from behavioral content.

Required Frontmatter Fields

Every SKILL.md must include two core fields that drive the toolkit's registration system.

name: The unique identifier for the skill. This string becomes the canonical skill ID used for routing commands and displaying the skill title in listings. For example, the Sign-In skill uses name: signing-in-to-aws as defined in skills/core-skills/signing-in-to-aws/SKILL.md according to the source code.

description: A short, human-readable summary of the skill's purpose. This field supports multiline strings using the | YAML literal block scalar indicator. The description appears in skill listings and drives search indexing within the toolkit.

Optional Frontmatter Fields

Beyond the required fields, the schema supports optional metadata for version control and plugin extensions.

version: An integer specifying the skill definition revision. When omitted, the toolkit treats the skill as versionless. The IAM skill at skills/core-skills/aws-iam/SKILL.md demonstrates this with version: 1.

Custom keys: The schema permits additional plugin-specific keys such as applyTo, tags, or category. While the core skills in the repository do not currently utilize these extensions, the parser accepts them for custom loading logic.

How the Toolkit Uses Frontmatter Metadata

The Agent Toolkit parses the frontmatter at load-time to execute three critical functions:

• Skill registration: The name field becomes the canonical identifier used to register the skill within the system.
• Help and lookup: The description field populates help text and search indexes, enabling users to discover skills by purpose.
• Version handling: When version is present, the toolkit uses it to determine whether to overwrite existing skill definitions during updates.

YAML Frontmatter Examples from the Source Code

The repository contains several canonical examples demonstrating valid frontmatter configurations.

Minimal configuration from the Sign-In skill:

---
name: signing-in-to-aws
description: |
  Gets AWS credentials for CLI/SDK access via `aws login`.
---

With version from the IAM skill:

---
name: aws-iam
description: |
  Commands for managing AWS Identity and Access Management (IAM) resources.
version: 1
---

Standard configuration from the AWS SDK for Python skill:

---
name: aws-sdk-python-usage
description: |
  Best practices and code examples for using the AWS SDK for Python (Boto3).
---

All behavioral content—usage instructions, code snippets, and references—must reside below the closing --- delimiter, keeping the frontmatter strictly for metadata. The AWS SDK for JavaScript v3 skill at skills/core-skills/aws-sdk-js-v3-usage/SKILL.md follows this same pattern, separating the YAML block from implementation details.

Summary

• The YAML frontmatter in SKILL.md files contains name, description, and optional version fields.
• The name field serves as the unique skill identifier for routing and registration.
• The description field supports multiline text using the | indicator and powers search indexing.
• Optional version fields help manage skill updates and overwrites.
• Additional custom keys are permitted by the schema for plugin-specific extensions.
• All implementation details must appear below the frontmatter, separated by the --- delimiter.

Frequently Asked Questions

What is the purpose of the name field in SKILL.md frontmatter?

The name field provides the unique identifier that the Agent Toolkit uses to register and route to the skill. It appears in skill listings and becomes the canonical ID referenced by other tools and commands throughout the system.

Can I include multiline descriptions in the YAML frontmatter?

Yes. The description field supports multiline strings using the YAML literal block scalar indicator (|). This allows you to write detailed explanations that span multiple lines while maintaining proper YAML formatting, as seen in the core skills.

What happens if I omit the version field in my SKILL.md file?

If the version field is omitted, the Agent Toolkit treats the skill as versionless. The skill will still register and function normally, but the system cannot perform version-comparison logic when determining whether to update existing skill definitions during reloads.

Are custom fields allowed in the SKILL.md frontmatter?

Yes. While the core skills in the aws/agent-toolkit-for-aws repository use only name, description, and version, the schema permits additional custom keys such as applyTo, tags, or category. These enable plugins to implement custom loading and display logic without breaking the parser.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}