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

> Explore the AWS Agent Toolkit repository structure. Discover its plugin-first architecture with core plugins, skills directory, and platform configurations for Cursor and Claude agents.

- 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 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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/CONTRIBUTING.md), and [`CODE_OF_CONDUCT.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/.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:

```bash

# 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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/.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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/.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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/aws-agent-rules.md)
- Utility scripts in [`tools/validate.py`](https://github.com/aws/agent-toolkit-for-aws/blob/main/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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/.mcp.json) file. Specifically, you will find [`plugins/aws-core/.mcp.json`](https://github.com/aws/agent-toolkit-for-aws/blob/main/plugins/aws-core/.mcp.json), [`plugins/aws-agents/.mcp.json`](https://github.com/aws/agent-toolkit-for-aws/blob/main/plugins/aws-agents/.mcp.json), [`plugins/aws-data-analytics/.mcp.json`](https://github.com/aws/agent-toolkit-for-aws/blob/main/plugins/aws-data-analytics/.mcp.json), and [`plugins/aws-agents-for-devsecops/.mcp.json`](https://github.com/aws/agent-toolkit-for-aws/blob/main/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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/.cursor-plugin/marketplace.json) file indexes the available plugins, allowing installation through the IDE's marketplace interface.