RFC: Work With AWS plugin

[iddv]

Is this related to an existing feature request or issue?

No response

Summary

This RFC proposes a work-with-aws plugin that gives coding agents authenticated access to AWS services through the AWS MCP Server — enabling real-time documentation search, execution of 15,000+ AWS APIs, and guided workflows via Agent SOPs.

The existing plugins in the marketplace focus on building new things: deploying apps, creating Amplify projects, building serverless applications. None provide general-purpose access to AWS for operational tasks like configuring VPCs, troubleshooting CloudWatch logs, managing IAM, or provisioning databases. work-with-aws fills that gap by bundling the AWS MCP Server with a discovery skill and a small number of standalone skills for the highest-value workflows.

Use case

A developer working in Claude Code or Cursor needs to interact with their AWS environment — configuring infrastructure, troubleshooting issues, querying documentation, or executing API calls.

Without this plugin: The developer must manually configure the AWS MCP Server in their .mcp.json, know which tools are available, and understand how to prompt the agent to use them. For complex tasks like VPC setup or S3 security hardening, the agent improvises from general knowledge rather than following tested workflows.

With this plugin: The developer installs work-with-aws with a single command and gets:

• Real-time AWS knowledge — the agent can search AWS documentation, API references, best practices, and regional availability information
• Authenticated AWS API execution — the agent can execute AWS APIs through the user's existing IAM roles with SigV4 authentication and CloudTrail audit logging
• Guided workflows via Agent SOPs — for complex multi-step tasks, the agent follows tested, production-hardened procedures that implement AWS Well-Architected best practices
• Troubleshooting capabilities — the agent can analyze CloudWatch logs, investigate permission problems, debug application failures, and diagnose performance issues
• Slash-command discoverability — the most common workflows show up as /create-production-vpc, /secure-s3-buckets etc., and /aws-operations provides a catch-all entry point

The plugin makes the full AWS MCP Server accessible without requiring users to understand MCP configuration, and adds skill-based discovery so the agent knows when and how to use its AWS capabilities.

Proposal

Architecture

The plugin bundles the AWS MCP Server (Preview) — providing authenticated AWS API execution, real-time documentation search, and Agent SOP retrieval — with a discovery skill + promoted standalone skills pattern for agent guidance:

• 1 discovery skill (aws-operations) — tells the agent to use search_documentation to find matching SOPs dynamically. Includes example SOP categories so the agent knows what's possible, but relies on search for actual discovery. Loads one description at startup (~100 tokens).
• 2-3 standalone skills (e.g., create-production-vpc, secure-s3-buckets) — for the highest-traffic SOPs. Each loads its own description at startup (~100 tokens each) and calls retrieve_agent_sop directly with the known SOP name.

Total startup context: ~300-400 tokens across all skills.

This follows the pattern established by vercel-labs/agent-skills/react-native-skills — one top-level skill with progressive disclosure, rather than N separate skills polluting the context window.

Plugin structure

plugins/work-with-aws/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   ├── aws-operations/              # Discovery skill
│   │   ├── SKILL.md                 # Examples + search_documentation workflow
│   │   └── references/              # OPTIONAL: extended guidance for specific SOPs
│   │       └── lambda-timeout-debugging.md   # Only when extra context is needed
│   ├── create-production-vpc/       # Standalone skill
│   │   └── SKILL.md
│   └── secure-s3-buckets/           # Standalone skill
│       └── SKILL.md
├── .mcp.json                        # AWS MCP Server (Preview) config
└── README.md

The references/ directory is optional. Most SOPs don't need one — search_documentation finds them dynamically and retrieve_agent_sop delivers the full execution plan. Reference files are only added when a specific SOP benefits from extended guidance — for example, common pitfalls, prerequisite checks, or disambiguation. No SOP content is duplicated.

MCP Server

The plugin bundles the AWS MCP Server (Preview), which consolidates AWS Knowledge MCP and AWS API MCP into a single remote service:

• Agent SOPs — tested, multi-step workflows via search_documentation and retrieve_agent_sop
• AWS documentation search — real-time docs, API references, best practices
• Authenticated API execution — 15,000+ AWS APIs with SigV4 via call_aws
• CloudTrail audit logging — all API calls are logged automatically

{
  "mcpServers": {
    "aws-mcp": {
      "command": "uvx",
      "args": [
        "mcp-proxy-for-aws@latest",
        "https://aws-mcp.us-east-1.api.aws/mcp",
        "--metadata", "AWS_REGION=us-west-2"
      ]
    }
  }
}

Users must have AWS credentials configured and appropriate IAM permissions. See Setting up your AWS MCP Server.

Proposed Discovery skill (aws-operations/SKILL.md) -

---
name: aws-operations
description: |
  Configure and operate AWS infrastructure using tested Agent SOPs.
  Triggers on: AWS infrastructure, VPC, S3, Aurora, CloudWatch, EC2,
  Lambda, IAM, EFS, Route53, CloudTrail, Secrets Manager, budgets.
metadata:
  tags: aws, infrastructure, operations, sops
---

# AWS Operations

Tested Agent SOPs are available for common AWS infrastructure tasks.
Use `search_documentation` to find the right SOP for the user's request,
then use `retrieve_agent_sop` to get the full execution plan.

## Example SOPs

These are examples of available SOPs — not an exhaustive list.
New SOPs are added regularly. Always search first.

- **Networking:** VPC creation, VPC peering, VPC endpoints, Lambda VPC internet access
- **Compute:** EC2 launch, EC2 instance profiles, EFS mounting, Lambda API Gateway
- **Security:** S3 bucket security, secrets management, CloudTrail setup
- **Databases:** Aurora cluster creation
- **Monitoring:** CloudWatch alarms, application failure troubleshooting
- **Cost:** Budget creation
- **DNS/CDN:** Route53 CloudFront routing
- **Debugging:** Lambda timeout debugging

## Workflow

### Step 1: Search for SOP

Use `search_documentation` with the user's request as the search phrase
and topics=["agent_sops"] to find matching Agent SOPs.

- DO NOT skip this step — SOPs are regularly added and updated
- DO NOT rely only on the examples above

### Step 2: Retrieve and Execute

If a matching SOP is found, use `retrieve_agent_sop` with the
SOP name returned by the search. Follow the SOP's steps using `call_aws`.

- DO NOT skip validation steps
- DO NOT modify constraints without user confirmation

### Step 3: No SOP Available

If no SOP matches:
- Inform user: "No pre-built SOP found for this task."
- Use `call_aws` and `suggest_aws_commands` with AWS best practices
- DO NOT proceed without user confirmation

Standalone skill example (create-production-vpc/SKILL.md)

---
name: create-production-vpc
description: |
  Create a production-ready VPC with multi-AZ subnets, NAT gateways,
  route tables, and security groups following AWS best practices.
  Triggers on: create VPC, production VPC, multi-AZ subnets, set up
  networking, AWS VPC, private subnets, public subnets.
metadata:
  tags: aws, vpc, subnets, networking, nat-gateway, multi-az
---

# Create Production VPC

## Workflow

### Step 1: Retrieve SOP

Use `retrieve_agent_sop` with sop_name `create-production-vpc-multi-az`.

- DO NOT attempt this task without retrieving the SOP first
- The SOP contains tested, security-reviewed steps

### Step 2: Execute SOP

Follow the retrieved SOP's steps exactly.

- Use `call_aws` for all AWS CLI commands
- DO NOT skip validation steps
- DO NOT modify constraints without user confirmation

## Error Scenarios

### SOP Retrieval Fails

- Inform user: "Unable to retrieve the VPC creation SOP."
- Ask: "Proceed with AWS best practices instead?"
- DO NOT continue without user confirmation

### AWS CLI Command Fails

- Report the specific step and error message
- Ask user whether to retry, skip, or abort
- DO NOT continue past a failed step without user confirmation

User experience

Before: User must manually configure AWS MCP Server, know SOPs exist, and prompt the agent to search for them. No slash-command discoverability.

After: User installs plugin, types "create a production VPC" or /create-production-vpc, and the agent retrieves and follows the tested SOP automatically. For general AWS tasks, the agent has full access to AWS documentation, API execution, and troubleshooting capabilities via the bundled MCP server.

Out of scope

• Embedding SOP content in skills. Skills steer to retrieve_agent_sop; they don't duplicate SOP content. The SOP registry remains the single source of truth.
• Hooks and guardrails. IaC validation hooks can be added in v2 after validating the core flow.
• MCP Prompts. Exposing SOPs as MCP prompts (for slash-command without skill wrappers) is a server-side enhancement for v2.
• Auto-generation of skills from the SOP registry. A build step that generates reference files from SOP frontmatter is a future optimization.

Potential challenges

1. MCP server overlap. The deploy-on-aws plugin bundles awsknowledge, awspricing, and aws-iac-mcp servers. This plugin bundles the AWS MCP Server (aws-mcp-server). If a user installs both, there may be duplicate or conflicting MCP server instances. AWS MCP also covers deploy-on-aws and amplify use cases which has standalone plugins right now. Mitigation: Replace Knowledge MCP with AWS MCP (AWS MCP bundles Knowledge MCP)

2. Discovery skill activation breadth. The aws-operations discovery skill has a broad description covering all AWS infrastructure tasks. It may activate on requests that would be better handled by other AWS plugins (e.g., deploy-on-aws, aws-serverless). Mitigation: tune the description to focus on operational/configuration tasks and exclude deployment/build language.

3. Standalone skill selection. Choosing which 2-3 SOPs get standalone skills requires usage data we may not have at launch. Mitigation: start with S3 and VPC creation (commonly requested), iterate based on feedback.

Dependencies and Integrations

• AWS MCP Server (Preview) — remote managed MCP server providing SOP retrieval, AWS documentation search, and authenticated API execution via SigV4. Connected via mcp-proxy-for-aws to https://aws-mcp.us-east-1.api.aws/mcp. Consolidates the previous AWS Knowledge MCP and AWS API MCP servers. See https://docs.aws.amazon.com/aws-mcp/latest/userguide/what-is-mcp-server.html
• mcp-proxy-for-aws — local proxy handling SigV4 authentication between MCP client and remote AWS MCP Server. Installed automatically via uvx.
• Claude Code >= 2.1.29 or Cursor >= 2.5 — required for plugin support.
• AWS CLI and credentials — must be configured on the user's machine. Supports aws login (recommended), aws configure sso, or aws configure. See https://docs.aws.amazon.com/aws-mcp/latest/userguide/getting-started-aws-mcp-server.html
• IAM permissions — users need appropriate permissions for target AWS services. Administrator roles work out of the box; scoped roles need explicit permissions.
• uv — Python package runner for mcp-proxy-for-aws. Install via curl -LsSf https://astral.sh/uv/install.sh | sh (macOS/Linux) or powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" (Windows).

Alternative solutions

1. **19 separate skills (one per SOP).** Rejected due to context pollution — 19 descriptions loading at startup (~1,900 tokens) even in non-AWS conversations. Violates the design guidelines' "minimize context usage" principle.

2. **4 broad domain skills (infrastructure, security, databases, monitoring).** Rejected because broad descriptions trigger unreliably and still load ~400 tokens unnecessarily. Doesn't follow the single-responsibility principle from the design guidelines.

3. **MCP server only (no plugin).** The current state — SOPs are available via the AWS MCP Server but require manual configuration and offer no slash-command discoverability. The plugin adds the install experience and skill-based discovery layer.

4. **MCP Prompts.** Exposing SOPs as MCP prompts would give them slash-command visibility without skill wrappers. This is a promising v2 approach but requires server-side changes and depends on client support for MCP prompts, which varies across tools.

5. **Pure steering/rules.** Steering files can prime the agent to look for SOPs, but they don't provide slash-command visibility and only work when the MCP server is already configured. Steering is best shipped as part of the plugin, not as a standalone distribution path.