AWS Agent Toolkit: Why Your Agent Is Ignoring 20+ Skills Without This One File

AWS shipped a toolkit that packages 20+ domains of AWS expertise into a form coding agents can actually use. Most teams installing it are quietly getting none of it — because the critical configuration step is a 17-line file that ships in the repo and is almost universally skipped.

What Happened

The Agent Toolkit for AWS, released May 2026, is a three-layer system for coding agents working with AWS infrastructure. Layer one is an MCP server providing access to 300+ AWS APIs through a single endpoint, plus sandboxed Python execution and real-time documentation search. Layer two is the skills library: 20+ packages of domain expertise including architecture decision tables, service comparison matrices, deployment workflows, and troubleshooting guides. Layer three is the rules file — and this is the one most developers miss.

The rules file is a 17-line configuration in rules/aws-agent-rules.md that tells the agent how to work with AWS: use the MCP Server for API calls, check for relevant skills before starting a task, load skills via retrieve_skill, and prefer infrastructure-as-code over direct CLI commands.

For Claude Code, its contents are added to CLAUDE.md. For Cursor, it goes in .cursor/rules/aws.mdc. For Codex, to AGENTS.md.

Why It Matters

The distinction the rules file creates is not subtle. Without it, the toolkit author found their agent “answered confidently from training data instead of touching its new tools” — offering generic architecture guidance (e.g., “use API Gateway + Lambda + DynamoDB”) rather than checking the available skills for current service-specific guidance (e.g., “use HTTP API specifically, because REST API is overkill unless you need WAF”). The agent had the tools installed; it just never decided to use them.

The core issue is that MCP tools and skills are available if an agent chooses to use them, but models default to answering from training knowledge unless explicitly instructed to check specialized sources first. A commenter in the original post noted the real problem: “missing rules file should error, not quietly answer from model memory.” The silent fallback is what makes this dangerous for production-SLA-governed workflows — the agent produces plausible AWS guidance that may be outdated, sub-optimal, or incorrect for the specific service variant in question.

For teams already using Claude Code or Kiro with AWS infrastructure, the rules file changes the agent’s default behavior from “I know AWS from training” to “I should check current skills and documentation before answering.” The AWS Agent Registry pattern this toolkit supports is most valuable when agents are actually using authoritative skills rather than training-data approximations.

What This Means for Platform Engineers

The practical steps are short. Install the toolkit, locate rules/aws-agent-rules.md in the repo, and add its contents to the appropriate configuration file for your agent (CLAUDE.md, AGENTS.md, or .cursor/rules/). From that point forward, the agent will proactively check for relevant skills before attempting AWS tasks.

The broader lesson is about tool installation versus tool activation. Many agentic infrastructure enhancements follow this same pattern: the capability is available through a protocol or a plugin, but agents only use it when the rules layer explicitly routes them there. Installing the MCP server without the rules file installs a reference book the agent never opens.

Source: DEV Community (AWS)

Content created with AI assistance and reviewed for accuracy.