Gunnar Grosch

Posted on Feb 21

Turning AWS Serverless Experience into a Claude Code Plugin

#aws #ai #serverless #productivity

In the previous posts, I covered how to set up Claude Code with Bedrock, use it in your IDE, teach it your conventions with CLAUDE.md, enforce them with hooks, connect it to your services with MCP servers, and extend it with plugins and skills. This post puts all of that into practice.

The Knowledge Gap

Claude Code can write a Lambda handler and generate a SAM template. But ask it to troubleshoot why your DynamoDB stream iterator age is climbing, and you'll hit the gap between general knowledge and practical experience. The documentation tells you what the parameters are. Experience tells you which ones matter and what to check first when something breaks.

That experience comes from building systems and from the broader serverless community: practitioners sharing production lessons, AWS engineers explaining the reasoning behind the services, hallway conversations at re:Invent. I wanted to see if I could encode that collective knowledge into a format Claude Code could actually use.

The AWS Serverless Plugin is the result. Here's a concrete example of the difference it makes.

Without the plugin, you might tell Claude "set up a Kinesis stream processor." It'll generate a Lambda function and a SAM template with default settings. It works, but the batch size is wrong for your throughput, there's no error handling for partial failures, the iterator age alarm is missing, and the IAM policy is broader than it needs to be. You'll find out about some of these when the stream backs up in production.

With the plugin, Claude knows to ask about your expected throughput before choosing a batch size. It configures BisectBatchOnFunctionError and MaximumRetryAttempts. It sets up an iterator age alarm with a threshold that makes sense. It generates a scoped IAM policy from a pre-approved template. Not because it read the documentation, but because the skill guides encode the judgment calls that come from experience.

What the Plugin Covers

The plugin gives Claude three things: knowledge (skill guides that encode serverless expertise), tools (the AWS Serverless MCP Server), and guardrails (a validation hook). The Kinesis example above shows one area. Here's the full scope.

Application lifecycle: Initialize SAM or CDK projects, build locally, test with Docker, deploy through CloudFormation. The MCP server provides tools like sam_init, sam_build, sam_deploy, and sam_local_invoke, so the agent works through structured APIs rather than shelling out to the CLI.

Event-driven architecture: Event source mappings for DynamoDB Streams, Kinesis, SQS, Kafka/MSK, S3, SNS, MQ, and DocumentDB. The skill guides cover batch sizes, error handling, and retry strategies. EventBridge gets its own guide: event bus design, routing patterns, Pipes, and the schema registry for type-safe event handling.

Orchestration: Step Functions for complex workflows with 220+ AWS service integrations. Lambda Durable Functions for a different approach: your orchestration logic lives in your Lambda code, with the ability to checkpoint progress, suspend execution for up to a year, and replay from where it left off, with no idle compute charges while waiting. The guide covers the judgment call between the two: Step Functions when you need visual workflow design, parallel branching, and deep AWS service integrations. Durable Functions when the orchestration is simpler and you'd rather keep the logic in code than in a state machine definition.

Observability: Structured JSON logging with Powertools, X-Ray distributed tracing, CloudWatch Application Signals for APM, custom metrics via Embedded Metric Format. The guide is a strategy for what to log, what to trace, and what to alarm on, not a list of AWS services.

Security: Least-privilege IAM policies generated from pre-approved templates, scoped to specific resources. Not LLM-generated policies that might be too broad.

Web applications: Full-stack deployment using Lambda Web Adapter. Standard web frameworks (Express, FastAPI, Next.js, Spring Boot) run on Lambda without modification.

Template validation: A PostToolUse hook runs sam validate automatically after Claude edits template.yaml or template.yml. If you read the hooks post, this is that pattern in practice: the agent writes a template, the hook catches syntax errors immediately, before you try to deploy and wait three minutes for CloudFormation to reject it.

How It's Structured

The plugin bundles all three components, so there's no separate MCP server setup.

aws-serverless-plugin/
├── .claude-plugin/
│   └── plugin.json                        # Plugin manifest
├── .mcp.json                              # MCP server configuration
├── hooks/
│   └── hooks.json                         # Template validation hook
├── scripts/
│   └── validate-template.sh               # Hook script
├── skills/
│   └── aws-serverless/
│       ├── SKILL.md                       # Main skill: tool reference, best practices
│       ├── getting-started.md             # Decision tree and first project setup
│       ├── sam-project-setup.md           # SAM initialization and workflow
│       ├── cdk-project-setup.md           # CDK constructs, testing, pipelines
│       ├── web-app-deployment.md          # Full-stack deployment patterns
│       ├── event-sources.md               # Event source mapping configuration
│       ├── event-driven-architecture.md   # EventBridge, Pipes, schema registry
│       ├── orchestration-and-workflows.md # Step Functions, Durable Functions
│       ├── optimization.md                # Performance, cost, cold starts
│       ├── observability.md               # Logging, tracing, metrics, dashboards
│       └── troubleshooting.md             # Symptom-based diagnosis
├── README.md
├── CHANGELOG.md
└── LICENSE

The SKILL.md is the entry point. It contains tool documentation with parameter tables, best practices, and a troubleshooting quick reference. The supporting guides provide deeper workflow knowledge and get loaded when the agent needs them.

The plugin activates automatically when you mention serverless-related topics: Lambda, SAM, CDK, API Gateway, DynamoDB, Kinesis, SQS, Kafka, EventBridge, Step Functions, cold starts, and others. You can also invoke it explicitly with /aws-serverless.

Design Decisions

I got a lot of things wrong before landing on the current design. Here's what I learned.

Encode decisions, not documentation

The first version of the skill files read like rewritten AWS documentation. Full YAML templates, parameter listings, step-by-step instructions. I thought more content meant better results. The opposite happened. The MCP tools already generate templates and handle the mechanical steps. Duplicating that in the skill files wasted context tokens and sometimes confused the agent when the skill's example slightly diverged from what the tool actually produced.

The version that worked focused on something the tools can't provide: judgment. When to use which deployment type. How to choose batch sizes for your throughput. What metrics to alarm on and what thresholds to set. What to check first when something breaks. This is the knowledge that's hard to find in documentation because it depends on context.

The first SKILL.md was way too long

I started with everything in a single file. Tool reference, workflow guides, troubleshooting, best practices. It hit the context budget and Claude started ignoring parts of it. The fix was splitting into a focused main file (tool reference, best practices, quick reference) with supporting guides that load on demand. Context usage dropped, and the agent actually started using the deeper guides when they were relevant instead of skimming past them.

Tool parameter names have to be exact

This one cost me real debugging time. If the skill says a parameter is called function_identifier but the tool actually expects resource_name, the agent fails silently or hallucinates parameters. It looks confident while doing the wrong thing. I ended up validating every parameter against the actual MCP server schemas. Tedious, but there's no shortcut.

Bundle the MCP server, don't assume it's there

I could have shipped this as a standalone skill directory that users drop into .claude/skills/. But the skill is most useful when the MCP server is available: the tools give Claude the ability to act on the knowledge. Packaging them together as a plugin means one install step gives you both. The hook comes along for free.

Make the security surface explicit

The MCP server configuration includes two flags that control what the agent can do:

--allow-write: Enables write operations like creating SAM projects, deploying stacks, and modifying AWS resources.
--allow-sensitive-data-access: Enables access to Lambda function logs and API Gateway logs.

Both are enabled by default because the full lifecycle workflow needs them. But you can edit .mcp.json to remove either flag. If you want the agent to help with architecture decisions without touching your account, remove --allow-write and it becomes read-only.

Distribution

Claude Code uses a marketplace model for plugin distribution. I set up a marketplace repo that acts as a catalog pointing to plugin repos on GitHub. Each plugin gets its own repo and a new entry in the marketplace. This means I can add more plugins later without cramming everything into one repository.

Users add the marketplace once, then install any plugin it lists:

/plugin marketplace add gunnargrosch/gunnargrosch-plugins
/plugin install aws-serverless@gunnargrosch-plugins

Not Just Claude Code

The skill files follow the open Agent Skills standard. The SKILL.md and supporting markdown files work in any AI coding tool that supports the standard: Cursor, Gemini CLI, GitHub Copilot, and others. Copy the skills/aws-serverless/ folder into your tool's skill directory and configure the MCP server separately. The serverless knowledge is the same. The plugin packaging is the delivery mechanism for Claude Code, but the knowledge isn't locked to it.

If you invest time encoding expertise into skill files, you shouldn't have to redo that work when you switch tools or when different team members use different editors.

Getting Started

Prerequisites

You'll need:

AWS CLI configured with credentials
AWS SAM CLI installed
Docker Desktop (for local testing)
Python 3.10+ with uv package manager (required to run the MCP server, regardless of what language you're coding in. Python 3.13+ or Node.js 22+ needed for Lambda Durable Functions)

Installation

/plugin marketplace add gunnargrosch/gunnargrosch-plugins
/plugin install aws-serverless@gunnargrosch-plugins

Try It Out

The plugin activates automatically when you mention serverless topics. You don't need special syntax:

> I need a Python API on Lambda with DynamoDB behind it
> the iterator age on my kinesis stream keeps climbing, help me figure out why
> set up an EventBridge bus for order events with routing to three downstream services
> my cold starts are killing me, what can I do

Claude uses the MCP tools to scaffold, build, test, and deploy, following the patterns in the skill guides.

Making the Knowledge Better

The hardest part of building this plugin wasn't the packaging or the MCP server configuration. It was deciding what knowledge to encode and how to express it so an agent could apply it well. I'm sure some of the guidance is wrong, or at least incomplete. The skill guides reflect how I think about serverless architecture today, shaped by the community I've learned from. That will evolve.

The plugin is open source. If the agent makes a bad recommendation, if there's a pattern the guides don't cover, or if you disagree with a design decision, I want to hear about it. Open an issue or a PR at github.com/gunnargrosch/aws-serverless-plugin. The best way to improve practitioner knowledge encoded in skill files is to test it against real projects.

Additional Resources

Have you hit a serverless pattern where the agent's recommendations fell short? I'd like to hear about it in the comments.

DEV Community