How Specialized Skills Are Organized in the AWS Agent Toolkit: Directory Structure and Categories

Specialized skills in the AWS Agent Toolkit are organized into service-specific category folders under skills/specialized-skills/, with each skill containing a self-contained SKILL.md manifest and executable scripts that agents can discover and invoke at runtime.

The AWS Agent Toolkit for AWS organizes its automation capabilities into modular, reusable units called skills. While the toolkit includes general-purpose core skills bundled with the aws-core plugin, the specialized skills provide deep, service-specific workflows for complex AWS tasks. These specialized capabilities follow a strict directory taxonomy that enables AI agents to dynamically discover, load, and execute only the relevant automation scripts for a given task.

Directory Structure of Specialized Skills

Specialized skills reside in the top-level skills/specialized-skills/ directory, distinct from the core skills located in plugins/aws-core/skills/. This separation ensures that agents can load specialized capabilities on demand without pulling the entire repository.

The structure follows a three-level hierarchy:

1. Category folders – Top-level groupings by AWS service domain (e.g., database-skills/, serverless-skills/)
2. Skill directories – Individual workflow folders containing manifests and scripts
3. Skill artifacts – Executable files, Python scripts, and configuration templates

For example, the Kafka-to-MSK migration skill is located at skills/specialized-skills/analytics-skills/migrate-to-msk/, containing the SKILL.md manifest and associated assessment scripts.

Core Skills vs. Specialized Skills

The toolkit maintains a clear distinction between these two skill types:

Type	Location	Purpose
Core skills	plugins/aws-core/skills/	General-purpose guidance for common AWS services including SDK usage, IaC patterns, security, observability, and cost optimization
Specialized skills	skills/specialized-skills/	Service-specific, deep-dive workflows for complex operations like cluster migrations, advanced networking configurations, and modernization tasks

Service Category Breakdown

Specialized skills are organized into ten distinct AWS service categories, each represented as a sub-folder under skills/specialized-skills/ according to the repository's skill directory README.

The categories include:

• Analytics – analytics-skills/ (e.g., Kafka to MSK migrations)
• Database – database-skills/ (e.g., Amazon ElastiCache configurations)
• EC2 – ec2-skills/ (instance management and optimization)
• Migration & Modernization – migration-and-modernization-skills/ (workload transformation)
• Networking & Content Delivery – networking-and-content-delivery-skills/ (VPC, CloudFront, Route 53)
• Operations – operations-skills/ (monitoring, logging, incident response)
• Security & Identity – security-and-identity-skills/ (IAM, GuardDuty, encryption)
• Serverless – serverless-skills/ (Lambda, Step Functions, API Gateway)
• Storage – storage-skills/ (S3, EFS, FSx)
• Web & Mobile Development – aws-amplify/ (full-stack application development)

Each category folder contains one or more skill directories, with each skill functioning as a self-contained unit.

Skill Manifest and Components

Every specialized skill follows a standardized structure anchored by a SKILL.md manifest file. This manifest defines the skill's name, description, version, and usage flow.

Taking the Kafka-to-MSK Express migration skill as implemented in skills/specialized-skills/analytics-skills/migrate-to-msk/SKILL.md, the typical structure includes:

• Discovery phase – Assessment scripts to evaluate current state
• Compatibility checks – Python scripts like scripts/compatibility.py
• Sizing recommendations – Analysis tools like scripts/sizing.py
• Execution workflow – Step-by-step instructions for the migration process

This self-contained architecture allows new capabilities to be added by simply dropping a new folder under the appropriate category, immediately making the workflow available to agents.

Runtime Discovery and Execution

The organization enables agents to perform three critical operations at runtime:

1. Discover the appropriate skill by searching the category taxonomy (e.g., "search for AWS skills related to databases")
2. Load the skill on demand without pulling the entire repository, loading only the specific category folder required
3. Execute only the scripts belonging to that specific skill, such as running scripts/compatibility.py for the MSK migration assessment

Because each skill is self-contained and includes its own dependencies and scripts, agents avoid loading unnecessary code, improving performance and reducing context window usage.

Practical Code Examples

You can interact with the specialized skills structure programmatically or via CLI.

List all specialized skill categories using Python:

import pathlib

repo_root = pathlib.Path(__file__).parents[2]  # adjust to repo root

specialized_root = repo_root / "skills" / "specialized-skills"

categories = [p.name for p in specialized_root.iterdir() if p.is_dir()]
print("Specialized skill categories:", categories)

# Output: ['analytics-skills', 'database-skills', 'ec2-skills', ...]

Install a single specialized skill locally using the Toolkit CLI:

npx skills add aws/agent-toolkit-for-aws/skills/specialized-skills/database-skills/amazon-elasticache

Run the MSK migration assessment phase (Phase 2) from the skill's scripts:

uv run skills/specialized-skills/analytics-skills/migrate-to-msk/scripts/compatibility.py \
    --input migrate-to-msk-skill-artifacts/mycluster/cluster-config.json \
    --output migrate-to-msk-skill-artifacts/mycluster/compatibility.mycluster.json

Summary

• Specialized skills reside in skills/specialized-skills/ and are organized into ten service categories including Analytics, Database, Serverless, and Security.
• Each skill is self-contained with a SKILL.md manifest and executable scripts, enabling on-demand loading without fetching the entire repository.
• The category-based taxonomy (e.g., analytics-skills/migrate-to-msk/) allows AI agents to discover relevant workflows by service domain.
• Core skills in plugins/aws-core/skills/ provide general guidance, while specialized skills offer deep, service-specific automation.
• New capabilities can be added by creating new directories under the appropriate category, with the repository's tools/validate.py script ensuring manifest compliance.

Frequently Asked Questions

What is the difference between core skills and specialized skills in the AWS Agent Toolkit?

Core skills are bundled with the aws-core plugin in plugins/aws-core/skills/ and provide general-purpose guidance for common AWS services like SDK usage and security best practices. Specialized skills reside in skills/specialized-skills/ and contain deep, service-specific workflows for complex tasks such as database migrations or serverless deployments. Specialized skills are loaded on demand rather than being bundled with the core plugin.

How does the directory structure enable agents to load only specific skills?

The hierarchical structure organizes skills by category (e.g., database-skills/, serverless-skills/) with each skill in its own subfolder containing a SKILL.md manifest and isolated scripts. This self-contained design allows agents to traverse the taxonomy to discover relevant skills, then load only the specific folder required for that workflow without fetching unrelated code, significantly reducing memory usage and loading time.

Where can I find the manifest file for a specific specialized skill?

Each specialized skill includes a SKILL.md file at its root directory that serves as the skill manifest. For example, the Kafka-to-MSK migration skill manifest is located at skills/specialized-skills/analytics-skills/migrate-to-msk/SKILL.md. This file defines the skill's name, description, version, and step-by-step usage flow that agents follow to execute the workflow.

How do I validate that my custom skill follows the repository's organization standards?

The repository includes tools/validate.py, a helper script used by the CI pipeline to validate skill manifests. You can run this script against your skill directory to ensure the SKILL.md manifest is properly formatted and all required fields are present before submitting your contribution to the skills/specialized-skills/ tree.

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