feat(aws-serverless): add aws-serverless plugin by gunnargrosch · Pull Request #52 · awslabs/agent-plugins

gunnargrosch · 2026-02-24T15:23:50Z

Summary

Related RFC: #48

Add the aws-serverless plugin with three skills, MCP server configuration, SAM template validation hook, and marketplace entry
aws-lambda: Lambda runtime behavior, event sources, EventBridge, Step Functions, orchestration, observability, optimization, and troubleshooting
aws-serverless-deployment: SAM and CDK project setup, CDK constructs and patterns, CI/CD pipelines, and SAM/CDK coexistence
aws-lambda-durable-functions (by @bfreiberg): Getting started, checkpoint-replay model, testing guidance, advanced patterns, and error handling

Changes

Plugin infrastructure:

Add plugin.json and marketplace.json entry for the aws-serverless plugin
Add .mcp.json for awslabs.aws-serverless-mcp-server (SAM CLI tools, event source mappings, webapp deployment, metrics, schemas)
Add hooks/hooks.json + scripts/validate-template.sh for automatic sam validate on template edits

Skill — aws-lambda (9 reference files):

getting-started.md — project type decision tree, prerequisites, working with existing projects
event-sources.md — DynamoDB Streams, Kinesis, SQS, Kafka, S3, SNS configuration
event-driven-architecture.md — EventBridge bus setup, event patterns, Pipes, archive and replay
orchestration-and-workflows.md — orchestration approach comparison, durable functions vs Step Functions
step-functions.md — Standard vs Express, ASL, JSONata, SDK integrations, Distributed Map, testing
web-app-deployment.md — Lambda Web Adapter, API endpoints, CORS, authentication, custom domains
observability.md — structured logging, tracing, metrics, alarms, dashboards
optimization.md — cold starts, memory tuning, cost, streaming, Powertools
troubleshooting.md — common errors, debugging, deployment failures

Skill — aws-serverless-deployment (5 reference files):

sam-project-setup.md — SAM templates, deployment workflow, local testing, container images
cdk-project-setup.md — CDK setup, construct levels, IAM grants, stack separation, testing, pipelines
cdk-lambda-constructs.md — NodejsFunction, PythonFunction, base Function construct examples
cdk-serverless-patterns.md — API Gateway, Function URL, EventBridge, DynamoDB, SQS CDK patterns
sam-cdk-coexistence.md — incremental migration, using sam build with CDK templates

Skill — aws-lambda-durable-functions (9 reference files, by @bfreiberg):

getting-started.md — SDK installation, basic handler pattern, ESLint/Jest setup
replay-model-rules.md — determinism rules, non-deterministic code handling
step-operations.md — atomic operations, retry logic, step semantics
wait-operations.md — delays, callbacks, external system integration, polling
concurrent-operations.md — parallel execution, map operations, batch processing
error-handling.md — retry strategies, saga pattern, compensating transactions
testing-patterns.md — LocalDurableTestRunner, cloud testing, flaky test prevention
deployment-iac.md — CloudFormation, CDK, SAM deployment patterns
advanced-patterns.md — GenAI agents, completion policies, custom serialization

Origin

The aws-lambda and aws-serverless-deployment skills are based on https://github.com/gunnargrosch/aws-serverless-plugin

Test plan

Verify mise run lint:manifests passes for plugin.json, marketplace.json, and .mcp.json
Verify mise run lint:md passes for all SKILL.md and reference files
Verify mise run lint:cross-refs passes
Test plugin locally with claude --plugin-dir ./plugins/aws-serverless

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of the project license.

aws-serverless-deployment skills Add the aws-serverless plugin with two new skills, MCP server configuration, SAM template validation hook, and marketplace entry. - aws-lambda: Lambda runtime behavior, event sources, EventBridge, Step Functions, orchestration, observability, optimization, and troubleshooting - aws-serverless-deployment: SAM and CDK project setup, CDK constructs and patterns, CI/CD pipelines, and SAM/CDK coexistence Also adds the aws-serverless MCP server (.mcp.json), a SAM template validation hook, and updates the marketplace registry. Based on https://github.com/gunnargrosch/aws-serverless-plugin

Add the aws-lambda-durable-functions skill to the aws-serverless plugin with getting started guide, checkpoint-replay model, testing guidance, advanced patterns, and error handling references.

reedham-aws · 2026-02-24T21:54:41Z

plugins/aws-serverless/scripts/validate-template.sh

@@ -0,0 +1,35 @@
+#!/bin/bash


Would we want a validation tool to provide linting as well? --lint flag will use cfn-lint, which could be useful.

reedham-aws · 2026-02-24T21:58:15Z

plugins/aws-serverless/scripts/validate-template.sh

+
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+
+# Only validate SAM template files


sam validate also works on non-SAM templates as well, although that might not be important in the context of this tool.

The comment was more meant to clarify that it doesn't validate other types of files, such as Lambda handlers etc.

reedham-aws · 2026-02-24T22:41:08Z

plugins/aws-serverless/skills/aws-serverless-deployment/SKILL.md

+This skill requires AWS credentials configured on the host machine:
+
+1. **Install AWS CLI**: Follow the [AWS CLI installation guide](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)
+2. **Configure credentials**: Run `aws configure` or set up named profiles in `~/.aws/credentials`


Will the agent know what to do with aws configure?

reedham-aws · 2026-02-24T22:47:03Z

plugins/aws-serverless/skills/aws-serverless-deployment/SKILL.md

+### SAM CLI Setup
+
+1. **Install SAM CLI**: Follow the [SAM CLI installation guide](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-sam-cli.html)
+2. **Install Docker Desktop**: Required for `sam_local_invoke` and container-based builds


This isn't necessarily true, on Linux it's probably preferred to not have docker desktop. Also, we support container engines other than docker, Finch specifically.

Fully agree, rephrased to be vendor agnostic

reedham-aws · 2026-02-24T22:53:16Z

plugins/aws-serverless/skills/aws-serverless-deployment/references/sam-project-setup.md

+| Python 3.12  | Data processing, ML workloads, scripting             |
+| Node.js 22.x | Web APIs, real-time applications                     |
+| Java 21      | Enterprise applications, high-performance computing  |
+| Go 1.x       | Microservices, high-concurrency, low-latency         |
+| .NET 8       | Windows-centric applications, enterprise integration |


I'd be wary of keeping a list of runtimes like this; for all of these there are newer versions available, and .NET 8 is starting its deprecation cycle within the year. There's a couple places that reference Python 3.12, and I'm not sure what the standard practice is for having versions like this.

@gunnargrosch do you agree that we remove this table completely?

reedham-aws · 2026-02-24T23:25:51Z

plugins/aws-serverless/skills/aws-serverless-deployment/references/cdk-serverless-patterns.md

Should these patterns have descriptions so that the agent can better understand when to use them?

reedham-aws · 2026-02-24T23:29:02Z

plugins/aws-serverless/skills/aws-serverless-deployment/references/cdk-project-setup.md

+| ------------------------ | ------------------------------------- | --------------------------------------------------------- |
+| **Language**             | YAML/JSON (declarative)               | TypeScript, Python, Java, Go, C# (imperative)             |
+| **Learning curve**       | Lower — close to CloudFormation       | Higher — requires familiarity with a programming language |
+| **Local testing**        | `sam local invoke` built-in           | Requires external tools (Localstack, docker)              |


This is not true, as explained in sam-cdk-coexistence.md, sam local invoke works for any CFN template.

There are a couple things referencing this below that need to be cleaned up.

reedham-aws · 2026-02-24T23:29:42Z

plugins/aws-serverless/skills/aws-serverless-deployment/references/cdk-project-setup.md

+| **Language**             | YAML/JSON (declarative)               | TypeScript, Python, Java, Go, C# (imperative)             |
+| **Learning curve**       | Lower — close to CloudFormation       | Higher — requires familiarity with a programming language |
+| **Local testing**        | `sam local invoke` built-in           | Requires external tools (Localstack, docker)              |
+| **Abstraction level**    | Thin layer over CloudFormation        | Rich L2/L3 constructs handle wiring automatically         |


'Thin layer' might not be really true, SAM can handle a lot of wiring automatically for Serverless resources.

reedham-aws · 2026-02-24T23:43:23Z

plugins/aws-serverless/skills/aws-lambda/SKILL.md

+
+For topic-specific best practices, see the dedicated guide files in the reference table above.
+
+## Lambda Limits Quick Reference


I don't know off the top of my head, but I would make sure these limits are correct and up to date.

reedham-aws · 2026-02-24T23:49:13Z

plugins/aws-serverless/skills/aws-serverless-deployment/references/cdk-project-setup.md

+| **Local testing**        | `sam local invoke` built-in           | Requires external tools (Localstack, docker)              |
+| **Abstraction level**    | Thin layer over CloudFormation        | Rich L2/L3 constructs handle wiring automatically         |
+| **Code sharing**         | Template fragments only               | Full reuse via construct libraries (npm, PyPI)            |
+| **Loops and conditions** | Limited (`Fn::If`, no loops)          | Native language constructs (`for`, `if`, maps)            |


I think technically Fn::ForEach loops are supported by all CFN templates. The issue is that SAM CLI does not know how to read these, although support for this is coming soon actually.

- Remove sensitive data access flags from MCP server configuration - Add --lint flag to SAM template validation for stricter checks - Update validation messages to reflect linting improvements - Reorganize SKILL.md with clearer onboarding steps and prerequisites - Refine skill description to focus on core capabilities - Add advanced-error-handling.md reference guide for timeout and circuit breaker patterns - Update reference file routing to include advanced error handling scenarios - Consolidate guidelines into onboarding section for better user flow - Improve documentation structure for better discoverability

… requirements - Split Powertools documentation into dedicated reference file (powertools.md) - Update SKILL.md routing to direct Powertools queries to new dedicated reference - Update observability.md link to point to powertools.md instead of optimization.md - Clarify Python runtime requirements for durable functions (3.11+ minimum, 3.13+ for Lambda pre-installed SDK)

krokoko · 2026-02-27T20:29:06Z

My feedback (in addition to previous comments from other reviewers which need to be resolved):

Issue: version mismatch. marketplace.json sets version: "1.0.0" but plugin.json sets version:
"1.1.0". These should match. For a new plugin, 1.0.0 in both is appropriate.
The aws-lambda and aws-serverless-deployment skills include "Guidelines" sections that
say "Ask which IaC framework" and "Ask which programming language" — this is good for user
interaction but there are no explicit defaults specified (e.g., "Default: SAM for new
projects"). The design guidelines state: "Specify defaults clearly, then provide override
syntax" and "Agents need explicit guidance on what to do when users don't specify preferences."
Neither aws-lambda/SKILL.md nor aws-serverless-deployment/SKILL.md document what to do if
the aws-serverless-mcp MCP server is unavailable. The design guidelines require explicit error
scenarios: "Inform user: 'Cost estimation unavailable (awspricing MCP not responding)' ... DO
NOT continue without user confirmation."
The durable-functions/advanced-patterns.md contains a full section on "Advanced Error Handling"
(timeout handling with waitForCallback, local timeout with Promise.race) that overlaps
significantly with durable-functions/advanced-error-handling.md. Both files contain nearly
identical code examples for callback timeout handling and Promise.race patterns. This wastes
context tokens when both files are loaded.
Typos: In aws-serverless-deployment/SKILL.md:
- "prevents access to sensitve data" → "sensitive"
- "To grant accees" → "access"

- Move troubleshooting production executions content to dedicated troubleshooting-executions.md reference file - Set language and IaC framework defaults including override syntax - Add error scenario handling for unsupported languages and frameworks - Remove inline troubleshooting agent instructions from main SKILL.md for better modularity - Consolidate advanced error handling references to separate advanced-error-handling.md file - Update plugin version from 1.1.0 to 1.0.0

bfreiberg · 2026-02-27T21:29:01Z

Thanks for the feedback @krokoko, I've pushed adjustments for all of it

gunnargrosch and others added 2 commits February 24, 2026 16:19

feat(aws-serverless): add aws-lambda-durable-functions skill

0dacdc7

Add the aws-lambda-durable-functions skill to the aws-serverless plugin with getting started guide, checkpoint-replay model, testing guidance, advanced patterns, and error handling references.

gunnargrosch requested a review from a team February 24, 2026 15:23

krokoko added the new plugin label Feb 24, 2026

reedham-aws reviewed Feb 25, 2026

View reviewed changes

krokoko and others added 5 commits February 25, 2026 16:27

Merge branch 'main' into feat/serverless-agents

f5341c0

Merge branch 'main' into feat/serverless-agents

ad56632

Fix formatting

43b5a8b


		FILE_PATH=$(echo "$INPUT" \| jq -r '.tool_input.file_path // empty')

		# Only validate SAM template files


		For topic-specific best practices, see the dedicated guide files in the reference table above.

		## Lambda Limits Quick Reference

Conversation

gunnargrosch commented Feb 24, 2026 • edited by krokoko Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Origin

Test plan

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

krokoko commented Feb 27, 2026

Uh oh!

bfreiberg commented Feb 27, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

gunnargrosch commented Feb 24, 2026 •

edited by krokoko

Loading