Agent Toolkit for AWS

What It Does

The Agent Toolkit for AWS is Amazon's official collection of skills, plugins, and MCP server configuration for AI coding agents. It ships 43 skills (13 core, 30 specialized) covering everything from CDK and CloudFormation to Bedrock, EC2, VPC networking, and data analytics. Three plugin bundles (aws-core, aws-agents, aws-data-analytics) package the skills with MCP server config for one-command install in Claude Code and Codex. A managed AWS MCP server provides authenticated access to 300+ AWS services, documentation search, and sandboxed Python script execution. The repo replaces the older awslabs/mcp collection with enterprise features like IAM condition keys for agent-scoped policies and CloudTrail audit logging.

The Good

43 skills, all validated, zero errors. The repo includes a stdlib-only validation tool (tools/validate.py) that checks every SKILL.md for frontmatter (name, description, kebab-case naming, directory name match). Running it produces 43 lines of "Validating skill:" and exits clean. This is structural quality enforcement most skill packs skip.

Reference depth is exceptional. The Bedrock skill alone has 19 reference files totaling 2,947 lines covering API selection, model invocation, knowledge bases, guardrails, prompt caching, quota health, cost tracking, model migration, and AgentCore services. The CDK skill has separate reference files for bootstrap, construct patterns, compliance, imports, refactoring, and three troubleshooting categories (deployment, credentials, synth). Skills do not just summarize; they point agents to specific procedures and decision tables.

Multi-agent platform support from day one. Each plugin ships three manifests: .claude-plugin/plugin.json, .codex-plugin/plugin.json, and .mcp.json. The Claude Code marketplace, Codex marketplace, and generic MCP configurations are all present and validated. The skills/README.md includes path tables for Claude Code, Codex, Cursor, and Kiro skill directories. No other vendor pack does this breadth.

Progressive disclosure done right. The Bedrock SKILL.md is 362 lines with a table of contents, critical warnings, workflow tables, troubleshooting entries, and pointers to 19 deeper reference files. The agent loads a focused entrypoint and only reads references when the task requires them. This respects context window limits in a way that monolithic skill files do not.

Critical warnings save real time. The CDK skill's "deadly embrace" warning about cross-stack reference removal deadlocking deployment, and the Bedrock skill's maxTokens quota reservation pitfall, are the kind of gotchas that cost hours in production. Surfacing them at the top of the skill, not buried in a troubleshooting section, is good design.

The Bad

MCP server requires AWS account and a running uv/uvx setup. The MCP server uses uvx mcp-proxy-for-aws@latest to connect to https://aws-mcp.us-east-1.api.aws/mcp. Users without an AWS account configured locally can still use the skills for documentation search and skill discovery (no auth required), but call_aws and run_script need real credentials. This is inherent to the product, not a flaw, but it means the full value is locked behind AWS onboarding.

No test suite beyond structural validation. The validate.py tool checks frontmatter and JSON manifests. There are no integration tests, no mock AWS calls, no CI checks that skill content stays accurate against live AWS API changes. For a repo with 5,600 lines of skill content about fast-moving services like Bedrock, this is a real gap. A model ID or API parameter could drift between releases and the validation tool would not catch it.

Skills are doc-only. There are no scripts, no CLI tools, and no runnable code outside the validation tool and one asset file (powertools-handler.py). Agents rely on the MCP server or AWS CLI for execution. This is a reasonable architectural choice but means the skills are only as good as the agent's ability to follow the written instructions. No guardrails enforce that the agent actually reads the reference files before acting.

Specialized skills vary in depth. Core skills average 177 lines. The migration skill (aws-transform) is 845 lines with its own deep references. But some specialized skills are thin: debugging Lambda timeouts is 47 lines, creating a production VPC is 45 lines, and several others sit at 40-42 lines with minimal troubleshooting guidance. The quality gap between the deepest and shallowest skills is real.

Smoke Test Results

Tests run on macOS host against shallow clone at /tmp/aws-toolkit-r3.

Structural validation

$ cd /tmp/aws-toolkit-r3 && python3 tools/validate.py
Validating Claude Code marketplace: .claude-plugin/marketplace.json
Validating Codex marketplace: .agents/plugins/marketplace.json
Validating plugin: aws-agents
Validating plugin: aws-core
Validating plugin: aws-data-analytics
Validating skill: skills/core-skills/amazon-bedrock
... (43 skills total)
✅ All validations passed.

Pass rate: 1 of 1. Validation tool exits clean with zero errors across all 43 skills, 3 plugins, and 2 marketplace manifests.

$ wc -l skills/core-skills/*/SKILL.md skills/specialized-skills/*/*/SKILL.md
 2303 total (core) + 3295 total (specialized) = 5598 lines across 43 SKILL.md files
✅ All 43 SKILL.md files have valid YAML frontmatter with name + description.

$ find skills -type f -path "*/references/*" | wc -l
182 reference files across 38 skill directories
✅ 182 reference files present.

$ find skills -name "SKILL.md" | wc -l
43
✅ 43 skills total (13 core + 30 specialized).

$ cat plugins/aws-core/.mcp.json | python3 -m json.tool
{
 "mcpServers": {
 "aws-mcp": {
 "command": "uvx",
 "args": [
 "mcp-proxy-for-aws@latest",
 "https://aws-mcp.us-east-1.api.aws/mcp"
 ]
 }
 }
}
✅ MCP config is valid JSON with correct structure.

What the runs tell you

The structural validation confirms every skill has compliant frontmatter and every plugin manifest is well-formed JSON. The skills directory is clean and consistent. What could not be tested is whether the skill content matches current AWS API behavior. That requires an AWS account, credentials, and live service access.

Setup Walkthrough

1. For Claude Code, run /plugin install aws-core@claude-plugins-official to get the core plugin with MCP server config and 13 skills.
2. For Codex, run codex plugin marketplace add aws/agent-toolkit-for-aws in your terminal, then /plugins inside Codex.
3. For any other agent (Cursor, Kiro, etc.), run npx skills add aws/agent-toolkit-for-aws/skills to copy skill directories locally.
4. The MCP server needs uv installed (curl --proto '=https' --tlsv1.2 -LsSf https://astral.sh/uv/install.sh | sh) and AWS credentials configured. Without credentials, you get documentation search and skill discovery only.
5. Optional: copy rules/aws-agent-rules.md to your project as a rules file to nudge the agent toward MCP-first AWS interactions.

Post-install gotcha: the MCP server endpoint is us-east-1 by default. If your resources are in another region, pass --metadata AWS_REGION=us-west-2 in the MCP config args (the Kiro example in the README shows this pattern).

Alternatives

1. awslabs/mcp -- the predecessor project. Still works and accepts contributions, but lacks IAM condition keys, CloudWatch metrics, and CloudTrail audit logging. AWS recommends migrating to this toolkit.
2. Terraform/Sunodo MCP servers -- for teams using Terraform instead of CDK/CloudFormation. Different IaC paradigm, no overlap with this toolkit's CDK skills.
3. Custom cursor rules / Claude CLAUDE.md files -- rolling your own AWS guidance. Viable for narrow use cases but cannot match the reference depth here (182 files, 5,600+ lines).