AWS Agent Toolkit for AWS: Rules Files, MCP, Skills, and Safe Setup

The short answer

AWS’s Agent Toolkit for AWS is an official bundle of an AWS-managed Model Context Protocol (MCP) server, curated agent skills, rules files, and installable plugins for coding agents. The important production lesson is easy to miss: configuring tools does not guarantee that an agent will use them. A rules file can turn passive tool availability into an explicit workflow: check for a relevant skill, retrieve current AWS documentation, and verify uncertain API details before proposing or executing a change.

That distinction matters for teams using Claude Code, Codex, Kiro, Cursor, or another MCP-compatible agent to change cloud infrastructure. Without a deliberate tool-use policy, an agent may produce plausible AWS guidance from model training data while ignoring the current documentation, organization rules, or available skills. The toolkit provides the components; your harness still needs to define when they are mandatory.

This guide targets intermediate developers and platform engineers. It explains the toolkit’s architecture, a safe setup path, the rules-file pattern, permissions, troubleshooting, and when to use the toolkit instead of configuring individual MCP servers.

What AWS Agent Toolkit actually includes

AWS announced the Agent Toolkit on May 6, 2026, as the successor to the MCP servers, plugins, and skills previously distributed through AWS Labs. The official announcement describes three core layers:

• AWS MCP Server: a managed MCP endpoint for interacting with AWS services, documentation search, and sandboxed multi-step execution.
• Agent skills: on-demand workflow guidance for areas such as infrastructure as code, serverless, containers, storage, analytics, observability, billing, SDK usage, and deployment.
• Plugins: installable packages that bundle MCP configuration with a curated collection of skills.

The official AWS Agent Toolkit product page also documents a one-command setup through aws configure agent-toolkit. AWS says the command requires AWS CLI 2.35 or newer, detects supported agents, installs skills, and configures the MCP server. The toolkit itself has no additional charge; normal AWS resource and service charges still apply.

The current AWS documentation lists these plugin families:

The plugin documentation is the authoritative source for supported installation paths and what a plugin contains: a manifest, skills directory, and MCP configuration. Treat repository README examples as implementation guidance, but re-check commands against the AWS User Guide before automating them.

The architecture: capability is not policy

The most useful mental model is to separate what the agent can do from what the agent must do before answering.

Visual credit: original architecture diagram by Essa Mamdani, based on the official AWS announcement and AWS Agent Toolkit documentation.

The failure mode is subtle. An MCP server may be connected and a skill may be installed, yet the model can still answer from its general knowledge if the client does not discover or retrieve those resources at the right time. AWS contributor Esin Saribudak documented this behavior in an independent, hands-on article: adding a rules file made the agent check the toolkit before answering instead of treating the skills as optional reference material. That is not a benchmark claim; it is a workflow observation, so use it as a design warning rather than a universal performance guarantee.

Install the toolkit without widening permissions

Start with a disposable development account or a sandboxed AWS profile. Do not begin by giving an agent administrator access to a production account.

Option 1: AWS CLI setup

Use the official setup flow after confirming the AWS CLI version and the agent clients you intend to use:

1aws --version
2aws configure agent-toolkit

The command is convenient because it discovers supported clients and configures the managed MCP endpoint. Review every generated file before allowing write operations. Pin versions where the client or package manager permits it, and record the toolkit commit or plugin version in your repository’s developer setup documentation.

Option 2: Claude Code or Codex plugin installation

For Claude Code, the AWS documentation shows the official marketplace installation pattern:

1/plugin install aws-core@claude-plugins-official
2/reload-plugins

For Codex, add the AWS repository as a plugin marketplace, then launch the client and select aws-core from /plugins:

1codex plugin marketplace add aws/agent-toolkit-for-aws

The official AWS repository contains the current plugin manifests, skills, rules, and setup instructions. Do not copy a third-party plugin manifest into a privileged environment without reviewing its executable hooks and network behavior.

Option 3: direct MCP plus standalone skills

If your client does not support plugins, configure the AWS MCP Server directly and install only the skills your project needs. This is more manual, but it can reduce the amount of capability exposed to a narrowly scoped agent. It also makes configuration drift more likely, so add a startup check that confirms the endpoint, skill directory, and expected version.

Add a rules file so the agent uses current AWS knowledge

A rules file should be short, explicit, and testable. Its job is not to repeat every AWS service rule. Its job is to establish the order of operations.

A practical project-level policy can look like this:

1Before answering an AWS implementation question:
21. Check whether an installed Agent Toolkit skill matches the task.
32. Retrieve the matching skill before proposing architecture or commands.
43. Use the AWS MCP Server for AWS resource inspection and documentation lookup.
54. Verify uncertain API parameters, service limits, IAM actions, and pricing assumptions against current AWS documentation.
65. Treat production writes, destructive actions, IAM changes, and secret operations as approval-gated.
76. Report which skill, documentation pages, and AWS account/profile were used.

The exact filename and placement depend on the agent client, so follow the client-specific rules-file guidance in the AWS User Guide. The key design principle is portable: “available” should not be confused with “automatically consulted.”

For higher assurance, make the policy observable. Require the agent to emit a compact evidence block in its task output containing the retrieved skill name, documentation URLs, AWS account identifier, region, read/write intent, and checks performed. This does not prove that every statement is correct, but it gives reviewers a way to detect an agent that skipped the intended workflow.

Security model and approval boundaries

The toolkit improves the control surface, but it does not make cloud automation safe by itself.

Use IAM to constrain the agent separately from the human

Create an agent-specific role or profile with the smallest useful permission set. For a planning assistant, begin with read-only access to the resources and documentation it needs. Add write permissions one workflow at a time, ideally through separate roles and explicit approvals.

AWS’s announcement highlights IAM-based controls, CloudTrail logging, CloudWatch observability, and sandboxed execution. Those are valuable primitives, but the policy still needs to answer:

• Which account and regions may the agent access?
• Which services and actions are allowed?
• Which actions always require human approval?
• Can the agent pass user-supplied values into shell commands or templates?
• Where are tool inputs, outputs, and generated artifacts retained?
• What happens after repeated failures or a suspicious tool response?

Protect against prompt injection and stale instructions

Treat repository instructions, issue text, tickets, documentation, and retrieved web content as untrusted input. A skill can guide a workflow, but it should not override IAM, approval requirements, branch protection, or secret-handling policy. Keep secrets out of agent-visible files and use short-lived credentials where possible.

This is where the toolkit connects to broader harness engineering for AI coding agents: the reliable unit is not the model prompt alone, but the combination of context, tools, permissions, tests, telemetry, and stop conditions. Teams using the OpenAI Agents SDK sandbox and harness pattern can apply the same separation between agent capability and execution policy.

A safe request-to-deployment workflow

For a new AWS service change, use this sequence:

1. Classify the request. Separate architecture advice, read-only inspection, code generation, and infrastructure mutation.
2. Select the skill. Ask the agent to identify and retrieve the matching toolkit skill before it writes code.
3. Confirm the account and region. Never infer these from a stale terminal or copied configuration.
4. Plan without writes. Generate the CDK, CloudFormation, or SDK plan and inspect IAM changes.
5. Validate locally. Run formatting, type checks, unit tests, template validation, and security scans.
6. Review the diff. A human should inspect identity policies, network exposure, data retention, encryption, and cost-sensitive resources.
7. Apply through an approval gate. Use a constrained role and a separate deployment step.
8. Collect evidence. Keep the plan, tool-call audit trail, CloudTrail events, test results, and deployed resource identifiers.

For teams already building agents, compare the toolkit with a custom MCP stack in this way:

The practical recommendation is to start with aws-core in read-only mode, add the rules file, and measure whether the agent actually retrieves skills and current documentation. Expand only after the workflow is auditable.

Troubleshooting: when the agent ignores the toolkit

The MCP server is connected, but answers still look generic. Check that the rules file is installed in the client’s actual project scope, not only in a repository directory the client does not load. Then ask for the retrieved skill and documentation URLs explicitly.

The agent discovers skills but never loads them. Confirm that the client supports the toolkit’s skill-discovery mechanism. A plugin installation can succeed while a client-specific loader remains disabled. Test with a task whose correct answer depends on a current service limit or documented configuration choice.

The agent can read resources but cannot deploy. That is normally the safer starting state. Inspect the active IAM identity, region, and approval policy before adding write permissions.

A command from a blog post fails. Prefer the current AWS User Guide and repository instructions. Verify CLI, plugin, and client versions; the toolkit is evolving quickly and third-party tutorials can preserve obsolete names or setup paths.

The skill gives confident but conflicting advice. Stop before applying changes. Capture the skill version, documentation pages, account context, and generated diff, then resolve the conflict against the service’s current official documentation.

FAQ

Is the Agent Toolkit an AI model?

No. It is a developer-tooling layer: MCP access, skills, rules, plugins, and related guidance for coding agents working with AWS.

Does installing it make AWS usage free?

No. AWS states that the toolkit has no additional charge, but the agent can provision or interact with billable AWS resources. Add budget alerts and cost review to the deployment gate.

Should every agent get the full AWS API surface?

No. Start with the smallest client, skill set, account, region, and IAM role that can complete the task. Broad capability is useful for discovery but increases the consequences of a mistaken or manipulated tool call.

Do I still need tests and human review?

Yes. The toolkit can provide current guidance and controlled access; it cannot decide whether a production change is appropriate for your business, privacy, compliance, or reliability requirements.

Conclusion

The AWS Agent Toolkit is most valuable when treated as part of an agent harness rather than as a magic prompt upgrade. Its managed MCP server, curated skills, and plugins reduce setup work, while IAM, audit logs, and sandboxed execution provide useful control points. The missing piece is often procedural: explicitly tell the agent when it must retrieve a skill and verify current AWS documentation.

Install conservatively, add a short rules file, make evidence visible, keep writes approval-gated, and test the workflow with read-only tasks before trusting it with infrastructure. That is the difference between an agent that merely knows AWS and one that can participate in a governed AWS engineering process.

Sources and visual credits

• AWS announcement: Agent Toolkit for AWS
• AWS Agent Toolkit product page
• AWS User Guide: Plugins
• Official AWS Agent Toolkit repository
• AWS contributor hands-on article: why the rules file matters
• Visual credit: original architecture diagram by Essa Mamdani