Directory Structure of the AWS Agent Toolkit Repository: A Complete Guide

The AWS Agent Toolkit repository follows a plugin-first architecture organized around four independent plugins (aws-core, aws-agents, aws-data-analytics, aws-agents-for-devsecops), a hierarchical skills directory, and platform-specific marketplace configurations for Cursor, Claude, and generic agents.

The aws/agent-toolkit-for-aws repository implements a modular design that enables AI coding agents to discover and execute AWS functionality. Understanding the directory structure is essential for developers who want to install specific capabilities, contribute new skills, or integrate the toolkit into agent workflows.

Top-Level Organization and Root Files

The repository root contains standard open-source documentation alongside AWS-specific configuration files. The README.md serves as the primary entry point, providing quick-start instructions and mapping the four main plugins to their specific use cases.

Key root-level entries include:

• LICENSE, CONTRIBUTING.md, and CODE_OF_CONDUCT.md for legal and contribution guidelines
• .github/ housing workflow definitions, issue templates, and CODEOWNERS for CI/CD automation
• tools/ containing utility scripts such as tools/validate.py used by CI pipelines to verify skill and plugin definitions

The Plugins Directory (plugins/)

The plugins/ directory contains four self-contained plugin packages according to the source code analysis. Each plugin bundles an MCP Server configuration, marketplace definition, and specialized skill sets that agents can install independently.

aws-core Plugin

Located at plugins/aws-core/, this plugin provides foundational AWS infrastructure capabilities. It includes skills for CDK, CloudFormation, Lambda, ECS, and IAM management. The plugins/aws-core/.mcp.json file configures the MCP Server, defining how agents communicate with AWS APIs.

aws-agents Plugin

Found under plugins/aws-agents/, this plugin focuses on AI agent development within the AWS ecosystem. It contains skills for Bedrock AgentCore, tool gateways, and distributed tracing. The plugins/aws-agents/.mcp.json file enables agent-to-agent communication protocols.

aws-data-analytics Plugin

The plugins/aws-data-analytics/ directory houses skills for data lake, ETL, and analytics workflows, including S3 Tables, Glue, Athena, and OpenSearch configurations. Its plugins/aws-data-analytics/.mcp.json provides the MCP configuration for data-oriented operations.

aws-agents-for-devsecops Plugin

Situated at plugins/aws-agents-for-devsecops/, this plugin delivers security-focused capabilities including threat modeling, penetration testing, release readiness checks, and cost analysis. The corresponding plugins/aws-agents-for-devsecops/.mcp.json configures secure execution environments.

Skills Hierarchy and Instructional Content

The skills/ directory implements a two-tier hierarchy for agent instructions that powers the plugin capabilities.

Core and Specialized Skills

• skills/core-skills/ contains foundational AWS operational instructions
• skills/specialized-skills/ holds domain-specific guidance for advanced use cases

The skills/README.md explains the discovery mechanism and loading patterns for these markdown-based instruction files.

Agent Guardrails and Best Practices

The rules/ directory contains project-level guardrails that constrain agent behavior. The rules/aws-agent-rules.md file defines IAM security boundaries and MCP usage policies that agents must respect when generating AWS commands, preventing unauthorized resource modifications.

Platform-Specific Marketplace Configurations

The repository supports three major coding-agent platforms through dedicated configuration directories:

• .cursor-plugin/marketplace.json declares the four plugins for Cursor IDE integration
• .claude-plugin/ contains Claude-specific marketplace metadata
• .agents/plugins/ provides generic agent marketplace definitions

These JSON configurations map the physical directory structure to installable plugin identifiers.

Installing Plugins Using the Directory Structure

Agents interact with the repository structure through platform-specific commands. For Claude Code, installation references the plugin directories directly:

# Install the core AWS plugin from plugins/aws-core/

/plugin install aws-core@claude-plugins-official

# Refresh marketplace index if plugins are not found

/plugin marketplace update claude-plugins-official

# Install DevSecOps plugin from plugins/aws-agents-for-devsecops/

/plugin marketplace add aws/agent-toolkit-for-aws
/plugin install aws-agents-for-devsecops
/reload-plugins

For Cursor, the .cursor-plugin/marketplace.json file defines the installation source, allowing the IDE to resolve plugins/aws-core/ and other directories as installable units.

Summary

• The AWS Agent Toolkit organizes functionality into four main plugins under plugins/: aws-core, aws-agents, aws-data-analytics, and aws-agents-for-devsecops
• Each plugin contains a .mcp.json configuration file that defines MCP Server communication protocols
• The skills/ directory uses a hierarchical structure with core-skills/ and specialized-skills/ subdirectories for agent instructions
• Platform-specific configurations in .cursor-plugin/, .claude-plugin/, and .agents/plugins/ enable IDE-specific installation
• The rules/ directory provides security guardrails through aws-agent-rules.md
• Utility scripts in tools/validate.py support CI validation of the directory structure

Frequently Asked Questions

Where are the MCP configuration files located in the AWS Agent Toolkit?

Each plugin directory contains its own .mcp.json file. Specifically, you will find plugins/aws-core/.mcp.json, plugins/aws-agents/.mcp.json, plugins/aws-data-analytics/.mcp.json, and plugins/aws-agents-for-devsecops/.mcp.json. These JSON files define the Model Context Protocol server settings that allow agents to invoke AWS APIs.

How does the skills directory organize agent instructions?

The skills/ directory implements a two-level hierarchy where skills/core-skills/ contains foundational AWS operational instructions and skills/specialized-skills/ holds domain-specific guidance. The skills/README.md file documents the discovery mechanism agents use to load these markdown instruction files on demand.

What is the purpose of the rules directory in the repository?

The rules/ directory contains constraint files like rules/aws-agent-rules.md that establish security guardrails and best practices. These rules advise agents on IAM boundaries and MCP usage patterns they must respect when generating AWS commands, preventing unsafe resource modifications.

How do I install a specific plugin from the repository structure?

Installation commands reference the plugin names mapped to their directories. For Claude Code, use /plugin install aws-core@claude-plugins-official to install the core plugin from plugins/aws-core/. For Cursor, the .cursor-plugin/marketplace.json file indexes the available plugins, allowing installation through the IDE's marketplace interface.

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