AWS Agent Toolkit: The 17-Line File That Unlocks 20+ Agent Skills

The problem: AWS released the Agent Toolkit on May 6, 2026 with 20+ pre-built skills for common AWS operations. Many engineering teams configured the MCP server, confirmed their agents could invoke AWS APIs, and assumed they were done. In testing, the agents largely ignored the pre-built skills — not because of a bug, but because of a missing 17-line file.

The Framework

The AWS Agent Toolkit is built in three layers. Each layer depends on the ones below it, and the skills layer — the highest-value tier — is silent by default without the rules file:

Layer 1 — AWS MCP Server: Exposes 300+ AWS service APIs to any MCP-compatible agent (Claude Code, Codex, Amazon Kiro, others). The agent can call EC2, S3, IAM, Lambda, and most other AWS services directly.

Layer 2 — Skills (20+ pre-built workflows): Pre-composed multi-step operations like “deploy a Lambda function,” “diagnose an ECS service failure,” or “rotate an IAM access key.” Each skill chains multiple AWS API calls into a coherent operation so the agent doesn’t have to reason through the sequence from scratch.

Layer 3 — Rules File (AGENTS.md / CLAUDE.md): A 17-line context document that tells the agent: “Before starting any AWS-related task, check the available skills and use the appropriate one rather than composing raw API calls.” Without this file, agents treat the skills as “available on request” rather than “consult before starting.” They default to raw API composition and largely bypass the skill library.

Step 1 — Install the MCP Server

npm install -g @aws/aws-agent-toolkit
aws-agent-toolkit mcp configure

This installs the AWS MCP Server and authenticates it against your AWS credentials. Verify by running a test query through your agent: ask it to list your S3 buckets. If it returns results, the MCP layer is working.

Step 2 — Configure Skills

The skills configuration lives in your AWS Agent Toolkit config file (generated at ~/.aws-agent-toolkit/config.json on first run). Confirm the skills are registered:

aws-agent-toolkit skills list

You should see 20+ skills including deploy-lambda, ecs-diagnose, iam-rotate-key, cloudwatch-query, and others. If the list is empty, run:

aws-agent-toolkit skills sync

Step 3 — Create the Rules File

This is the step most setups miss. Create (or add to) your project’s AGENTS.md or CLAUDE.md:

## AWS Operations

Before starting any AWS infrastructure task:
1. Run `aws-agent-toolkit skills list` to see available pre-built skills
2. Check if an existing skill covers the task before composing raw AWS API calls
3. Prefer skills over direct API sequences — they handle error recovery and sequencing
4. For skills not in the list, compose from AWS MCP Server APIs directly

Available AWS operations via toolkit: Lambda deployment, ECS diagnostics,
IAM key rotation, CloudWatch querying, S3 operations, VPC management.

The exact wording matters less than the position: this rule needs to be in a file the agent reads at session start — either AGENTS.md (for Codex and Kiro) or CLAUDE.md (for Claude Code). Agents that don’t have this instruction treat the skill library as optional; agents with it check the library first.

Step 4 — Test the Skill Path

Run a task that has a pre-built skill: “Deploy the Lambda function in src/handlers/processor.js to the dev environment.” With the rules file in place, the agent should:

1. Check the skill list (triggered by the rules file instruction)
2. Select deploy-lambda
3. Execute the skill’s composed workflow rather than reasoning through the AWS CLI sequence manually

Without the rules file, the same agent typically responds by drafting AWS CLI commands from scratch — correct, but slower and more error-prone than the pre-built skill path.

Where It Doesn’t Apply

The rules file approach works for agents that read context documents at session start (Claude Code, Codex, Kiro). For one-off API agents or agents without a persistent context file mechanism, you’ll need to inject the skills-check instruction into the system prompt programmatically instead.

AWS Agent Toolkit v1 skills are optimized for common operational tasks. Highly custom AWS configurations (multi-account Organizations with complex SCPs, custom VPC topologies) may still require composing from raw API calls even with skills active — treat the skill as a starting point, not a complete solution.

Source: The New Stack

Content created with AI assistance and reviewed for accuracy.