# What Information Is Stored in the YAML Frontmatter of a SKILL.md File? > Discover what information is stored in the YAML frontmatter of a SKILL.md file including name, description, and version. Learn how the Agent Toolkit uses this metadata. - Repository: [Amazon Web Services/agent-toolkit-for-aws](https://github.com/aws/agent-toolkit-for-aws) - Tags: how-to-guide - Published: 2026-06-27 --- **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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/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: ```yaml --- name: signing-in-to-aws description: | Gets AWS credentials for CLI/SDK access via `aws login`. --- ``` With version from the IAM skill: ```yaml --- 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: ```yaml --- 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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/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.