What Is the SKILL.md File in AWS Agent Toolkit?

The SKILL.md file is the canonical definition document that tells the AWS Agent Toolkit how to discover, load, and execute a specific skill, encapsulating metadata, operational guidelines, and reference links in a single markdown file.

The SKILL.md file serves as the single source of truth for every skill in the aws/agent-toolkit-for-aws repository. Located in each skill directory under skills/ or plugins/*/skills/, this markdown document provides the Agent Toolkit with the identity, guardrails, and instructions needed to register capabilities and enforce best practices automatically.

Core Responsibilities of the SKILL.md File

The SKILL.md file fulfills six critical responsibilities that enable the Agent Toolkit to manage capabilities systematically.

Metadata and Identity

Every SKILL.md begins with a YAML front-matter block that defines the skill's identity. The front-matter includes the name, a brief description, and an optional version key for traceability. For example, in skills/core-skills/aws-sdk-python-usage/SKILL.md, the first five lines contain the metadata that the skill loader reads to register the skill in the catalogue.

Guidelines and Guardrails

The file embeds operational rules that agents must obey during execution. These guardrails appear as markdown warnings within the document body. In skills/core-skills/aws-sdk-python-usage/SKILL.md, line 7 explicitly states "Do not use emojis," and the runtime parses these constraints to enforce safety prompts and required confirmations automatically.

Instructional Content

Beyond metadata, SKILL.md contains detailed usage instructions organized under standard markdown headings. The body sections—such as # AWS SDK for Python (boto3) and ## Client vs Resource—provide indexed content that the Agent Toolkit serves to the LLM on demand when the skill is invoked.

Reference Linking

SKILL.md files link to supplemental technical documentation through relative paths. When a skill requires deeper detail, such as pagination guidance, the document references files like ../references/pagination.md. Line 75 of skills/core-skills/aws-sdk-python-usage/SKILL.md demonstrates this pattern, and the skill runtime loads these reference files lazily only when the user requests specific technical details.

How SKILL.md Powers Skill Discovery

The Agent Toolkit relies on a glob-based discovery mechanism to build the skill catalogue from these definition files.

Discovery Mechanism

At startup, the toolkit scans the repository using the glob pattern **/SKILL.md to locate all skill definitions. With approximately 100 such files distributed across the repository—including locations like skills/core-skills/aws-sdk-js-v3-usage/SKILL.md and plugins/*/skills/*/SKILL.md—the loader builds a complete registry by parsing each file's front-matter.

Runtime Loading

When an agent requires a specific capability, the loadSkill function reads the corresponding SKILL.md file, extracts the YAML front-matter, and returns a structured object containing the name, description, and operational rules. This ensures agents always use the latest guidance without hard-coding text elsewhere.

Working with SKILL.md Files

Listing Available Skills via CLI

You can discover all registered skills using the Agent Toolkit CLI, which walks every SKILL.md file to parse the metadata:

# Install the skill catalogue (once)

npx skills add aws/agent-toolkit-for-aws/skills

# Show the names of all discovered skills

npx skills list

The npx skills list command outputs a table of skill names by reading the front-matter from each SKILL.md file found in the repository.

Loading Skills Programmatically

Access skill metadata directly in your application code using the loadSkill function:

// Example: a custom agent that wants the Python SDK skill
const { loadSkill } = require('@aws/agent-toolkit');

// Load the skill metadata from its SKILL.md automatically
const pythonSdkSkill = await loadSkill('aws-sdk-python-usage');

// Access the description (used for UI tooltip, logging, etc.)
console.log(pythonSdkSkill.description);

This programmatic approach reads the SKILL.md file from skills/core-skills/aws-sdk-python-usage/SKILL.md and returns the configured metadata and guidelines.

Agent Execution Context

When the LLM processes a request involving boto3, the system constructs a prompt using the SKILL.md content:

You are using the skill "aws-sdk-python-usage".
Relevant excerpt from SKILL.md:
"AWS SDK for Python (boto3/botocore) development patterns. You MUST use this skill when writing Python code that uses AWS services via boto3 or botocore..."

This excerpt is pulled directly from the SKILL.md file, ensuring the agent follows current best practices without embedded static strings.

Summary

• SKILL.md is the canonical definition file for every skill in the AWS Agent Toolkit, residing in directories like skills/core-skills/aws-sdk-python-usage/.
• YAML front-matter provides metadata including name, description, and optional version keys that the skill loader uses for registration.
• Embedded guardrails such as "Do not use emojis" enforce safety constraints that the runtime parses and applies automatically.
• Reference linking allows lazy loading of supplemental documentation via relative paths like ../references/pagination.md.
• Glob discovery using **/SKILL.md enables the toolkit to find and catalog approximately 100 skills across the repository at startup.

Frequently Asked Questions

What happens if a skill directory lacks a SKILL.md file?

The Agent Toolkit cannot discover or load the skill without a SKILL.md file. The glob pattern **/SKILL.md specifically searches for this filename, so missing files result in the skill being excluded from the catalogue and unavailable to agents.

How does the SKILL.md file differ from the README.md?

While README.md explains the overall project and installation instructions, SKILL.md defines a specific capability's operational parameters. SKILL.md contains structured YAML front-matter and machine-readable guardrails that the loadSkill function parses, whereas README.md serves human readers with general documentation.

Can I version individual skills using SKILL.md?

Yes. The SKILL.md front-matter supports an optional version key that allows agents to report which skill version they are using. This traceability ensures that agents can embed version information into responses and logs, making debugging and auditing more precise.

Where are SKILL.md files located in the repository?

SKILL.md files appear in two primary locations: the core skills directory (skills/core-skills/*/SKILL.md) and plugin-specific skill directories (plugins/*/skills/*/SKILL.md). The aws-sdk-python-usage and aws-sdk-js-v3-usage skills reside in skills/core-skills/, while additional capabilities exist under various plugin paths.

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