vybekiit 0.4.0 → 0.6.0

package/dist/global-skills/aws-cloudformation/references/lookup-resource-properties.script.md

@@ -0,0 +1,130 @@
+# Lookup CloudFormation Resource Properties
+
+## Overview
+
+Deterministic procedure for looking up the authoritative schema for a CloudFormation resource type: property names, types, which are required vs. optional, valid enum values, and return values for `!GetAtt`. Use when authoring or modifying a template and you need to avoid guessing at property names.
+
+## Parameters
+
+- **resource_type** (required): The full CloudFormation resource type (e.g., `AWS::Lambda::Function`, `AWS::S3::Bucket`, `AWS::DynamoDB::Table`).
+- **focus** (optional): Specific aspect to look up. One of:
+  - `properties` (default) — all properties with types
+  - `required` — only required properties
+  - `return-values` — what `!Ref` and `!GetAtt` return
+  - `property:<PropertyName>` — deep-dive on a single property including nested sub-properties
+
+**Constraints for parameter acquisition:**
+
+- You MUST ask for the resource type upfront if not provided
+- You SHOULD infer the resource type from the user's question when possible (e.g., "what properties does a Lambda function have" → `AWS::Lambda::Function`)
+- You MUST confirm the inferred resource type with the user before looking up if there is any ambiguity
+
+## Steps
+
+### 1. Verify Dependencies
+
+Check which lookup mechanism is available.
+
+**Constraints:**
+
+- You MUST check for web access (agent's web fetch or equivalent capability) to retrieve the public CloudFormation documentation
+- You MUST ONLY check for availability and MUST NOT execute lookups during this step
+- If web access is not available, You MUST inform the user that offline lookup requires a locally-cached schema (e.g., `cfn-lint`'s bundled schema via `cfn-lint --info`) and ask whether to use the local fallback or abort
+
+### 2. Construct the Documentation URL
+
+Derive the authoritative CloudFormation documentation URL from the resource type.
+
+**Constraints:**
+
+- You MUST use the URL pattern: `https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-<service>-<resource>.html`
+- Examples:
+  - `AWS::Lambda::Function` → `aws-resource-lambda-function.html`
+  - `AWS::S3::Bucket` → `aws-resource-s3-bucket.html`
+  - `AWS::DynamoDB::Table` → `aws-resource-dynamodb-table.html`
+- For some older resource types the pattern uses `aws-properties-` instead of `aws-resource-` (e.g., `aws-properties-ec2-securitygroup.html`). If the first URL returns a 404, You MUST try the `aws-properties-` variant
+- You MUST NOT guess at schemas from memory because CloudFormation schemas evolve; always consult the authoritative source
+
+### 3. Fetch and Extract the Schema
+
+Retrieve the documentation and extract the relevant sections.
+
+**Constraints:**
+
+- You MUST fetch the documentation page
+- You MUST extract, based on the `focus` parameter:
+  - **properties**: the "Properties" section with each property's name, required/optional status, type, allowed values, update requirements
+  - **required**: only properties marked "Required: Yes"
+  - **return-values**: the "Return values" section covering `!Ref` and `!GetAtt` attributes
+  - **property:`<Name>`**: the sub-sections describing that property's nested schema
+- You MUST preserve the exact property names (case-sensitive) because CloudFormation rejects misspelled property names
+- You MUST capture type information (String, Integer, Boolean, List, or a sub-type link) because type mismatches are a leading cause of deployment failures
+- You SHOULD capture the "Update requires" column because users often care whether a property change triggers replacement vs. modification
+
+### 4. Present the Results
+
+Return the schema information in a format that is directly usable for template authoring.
+
+**Constraints:**
+
+- You MUST present properties as a table or bullet list with columns/fields: Name, Required, Type, Default (if any), Allowed Values (if an enum), Update Requires
+- For the `required` focus, You MUST list ONLY required properties and explicitly state "the remaining properties are optional" rather than omitting them silently
+- For complex nested types, You MUST link to the nested type's documentation URL so the user can dig deeper
+- You SHOULD include a minimal YAML example using the looked-up properties, because examples save the user from assembling them manually
+- You MUST cite the source URL so the user can verify
+
+### 5. Recommend Next Steps
+
+Guide the user on how to use the information.
+
+**Constraints:**
+
+- If the user was authoring a template, You SHOULD offer to draft the resource block using the schema
+- You SHOULD recommend running cfn-lint and cfn-guard after authoring because they catch remaining schema and security issues
+- If the user asked about a specific property that has nested complex types, You SHOULD offer to recursively look up the nested types on request
+
+## Examples
+
+### Example Input
+
+```
+resource_type: AWS::Lambda::Function
+focus: required
+```
+
+### Example Output
+
+```
+Required properties for AWS::Lambda::Function
+Source: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-function.html
+
+| Name    | Type   | Update requires | Notes |
+|---------|--------|-----------------|-------|
+| Code    | Code   | No interruption | Either ZipFile, S3Bucket+S3Key, or ImageUri |
+| Role    | String | No interruption | IAM role ARN (must match ^arn:aws:iam::\d{12}:role/.+$) |
+
+Example:
+  MyFunction:
+    Type: AWS::Lambda::Function
+    Properties:
+      Role: !GetAtt MyLambdaRole.Arn
+      Code:
+        ZipFile: |
+          def handler(event, context):
+              return {'statusCode': 200}
+
+The remaining properties (Runtime, Handler, etc.) are conditionally required
+or optional depending on deployment type. Tell me if you want the full
+property list.
+```
+
+## Troubleshooting
+
+### Documentation URL returns 404
+Some resource types use `aws-properties-` instead of `aws-resource-` in the URL path (historical naming). Try both variants before falling back to search.
+
+### Property schema differs from what I see in the Console
+The Console sometimes exposes additional UI-only fields that do not exist in the CloudFormation schema. The documentation is authoritative for CloudFormation property names.
+
+### Ambiguous service name
+Some service names are not obvious (e.g., `AWS::IAM::Role` is `iam-role`, but `AWS::EC2::SecurityGroup` is `ec2-securitygroup` — CamelCase words are not split). If the URL derivation fails, search the CloudFormation User Guide for the resource type by its full name.

package/dist/global-skills/aws-cloudformation/references/troubleshoot-deployment.script.md

@@ -0,0 +1,200 @@
+# Troubleshoot CloudFormation Deployment
+
+## Overview
+
+Deterministic procedure for diagnosing a CloudFormation stack deployment failure. Pulls the stack status, failed events, and a filtered CloudTrail time window, then matches evidence against known failure patterns to produce a prioritized root cause and template-level fix.
+
+## Parameters
+
+- **stack_name** (required): The name or ARN of the failed CloudFormation stack. Accept the ARN if the stack has been deleted so the user can still investigate via `StackId`.
+- **region** (required): AWS region where the stack was deployed (e.g., `us-east-1`).
+- **include_cloudtrail** (optional, default: "true"): Whether to correlate with CloudTrail events. Set to "false" to skip CloudTrail lookup (faster but less context).
+
+**Constraints for parameter acquisition:**
+
+- You MUST ask for all required parameters upfront in a single prompt
+- You MUST support multiple input methods for the stack identifier:
+  - Stack name (if the stack still exists)
+  - Stack ARN (if the stack has been deleted and the user has the ARN)
+- You MUST confirm the region before any API calls because CloudFormation is a regional service and calling the wrong region returns "Stack not found"
+
+## Steps
+
+### 1. Verify Dependencies
+
+Check that AWS CLI and credentials are usable, and that the principal has required read permissions.
+
+**Constraints:**
+
+- You MUST check in this order of preference:
+  1. `call_aws` tool from the AWS MCP Server (preferred for sandboxed execution, audit logging, and observability)
+  2. AWS CLI (`aws`) available on the user's system (verify with `which aws` or `aws --version`)
+- You MUST verify the user has valid AWS credentials configured for the target region (e.g., `aws sts get-caller-identity --region <region>`). This read-only call is acceptable because it does not modify anything
+- You MUST ONLY check for availability and credential validity. You MUST NOT install missing dependencies during this step because installation modifies the user's environment
+- If the AWS CLI is missing, You MUST ask the user explicitly before running any install command, using a prompt like: "I can install the AWS CLI via `<platform-specific command>`. Do you want me to install it, or would you prefer to install it manually?"
+- You MUST NOT run install commands without explicit user approval because this changes the user's environment
+- If credentials are missing or invalid, You MUST ask the user to configure credentials and MUST NOT proceed until credentials are confirmed
+- The caller MUST have at minimum: `cloudformation:DescribeStacks`, `cloudformation:DescribeEvents`, `cloudtrail:LookupEvents`. You SHOULD warn the user if `iam:SimulatePrincipalPolicy` is also unavailable because it limits how deeply you can diagnose permission-related failures
+
+### 2. Get Stack Status
+
+Fetch the current stack state.
+
+**Constraints:**
+
+- You MUST call `aws cloudformation describe-stacks --stack-name <name_or_arn> --region <region>`
+- You MUST capture the `StackStatus`, `StackStatusReason`, `LastUpdatedTime`, and `StackId` fields
+- If the stack is not found and the user provided a name, You MUST ask whether the stack may have been deleted (in which case the user needs to provide the Stack ARN)
+- If the stack is in a success state (`CREATE_COMPLETE`, `UPDATE_COMPLETE`), You MUST inform the user the stack is healthy and ask whether they want to investigate a different stack or a past failure (which requires reviewing historical events)
+
+### 3. Fetch Failed Events
+
+Retrieve only the failed events using the `FailedEvents` filter.
+
+**Constraints:**
+
+- You MUST call `aws cloudformation describe-events --stack-name <name_or_arn> --filters FailedEvents=true --region <region>` because the filter returns only `PROVISIONING_ERROR` and `VALIDATION_ERROR` event types which are the relevant signals for root-cause analysis
+- You MUST NOT use `aws cloudformation describe-stack-events` for root-cause analysis because it returns every event without filtering and buries the actual failures in noise
+- You MUST capture for each failed event: `LogicalResourceId`, `PhysicalResourceId`, `ResourceType`, `ResourceStatus`, `ResourceStatusReason`, `Timestamp`, `EventType`
+- If no failed events are returned, You MUST fall back to `describe-events` without the filter to find the earliest status change, because some failures surface as non-FAIL events (e.g., stuck in `IN_PROGRESS`)
+- You MUST sort events chronologically and identify the FIRST failure, because subsequent failures are often cascading consequences of the first
+- If a failed event has `ResourceType: AWS::CloudFormation::Stack`, You MUST recursively call `describe-events --stack-name <PhysicalResourceId> --filters FailedEvents=true --region <region>` to retrieve the nested stack's failed events, because the parent stack's `ResourceStatusReason` is generic and the actionable error is only visible in the nested stack
+
+### 4. Match Failure Patterns
+
+Compare the failure message against known patterns to propose a diagnosis.
+
+**Constraints:**
+
+- You MUST evaluate each failure message against these common patterns:
+  - `is not authorized to perform` → IAM permission gap
+  - `already exists` → resource name conflict
+  - `Invalid` / `does not match pattern` → property validation failure
+  - `Rate exceeded` / `Throttling` → API throttling
+  - `timed out` → resource creation took too long; possibly quota or dependency issue
+  - `DELETE_FAILED` with `is not empty` → stateful resource has data
+  - `Requested resource not found` → referenced resource (AMI, KMS key, IAM role) does not exist in this region/account
+  - `cannot be deleted` → resource has deletion protection enabled or is in use by another resource/service
+- If the message matches none of the above, You SHOULD categorize it as "service-specific" and inspect `ResourceType` to consult the relevant service's documentation
+- You SHOULD identify the FIRST failed event as the root cause candidate, because later failures are typically cascading
+
+### 5. Correlate CloudTrail (Optional but Recommended)
+
+Pull CloudTrail events in a ±60 second window around the first failure to find the underlying AWS API error.
+
+**Constraints:**
+
+- You MUST skip this step if the user set `include_cloudtrail=false` or if `cloudtrail:LookupEvents` permission is missing
+- You MUST compute the time window as `Timestamp - 60s` to `Timestamp + 60s` using the first failed event's timestamp, because CloudFormation issues API calls within seconds of recording the failure
+- You MUST call `aws cloudtrail lookup-events --start-time <start> --end-time <end> --region <region> --max-results 50`
+- You MUST filter the returned events client-side to those where:
+  - `CloudTrailEvent.errorCode` is non-empty OR `CloudTrailEvent.errorMessage` is non-empty
+- For each matching event, You MUST extract: `EventName`, `EventTime`, `errorCode`, `errorMessage`, `Username`
+- You SHOULD provide a CloudTrail console deeplink scoped to the failure window so the user can browse additional context:
+  - Format: `https://console.aws.amazon.com/cloudtrailv2/home?region=<region>#/events?StartTime=<start>&EndTime=<end>&ReadOnly=false`
+  - Note: Console domain varies by partition (e.g., `console.amazonaws.cn` for China regions, `console.amazonaws-us-gov.com` for GovCloud)
+- If no matching CloudTrail events are found, You MUST note this and continue — not all failures produce CloudTrail-visible errors
+
+### 6. Present Root Cause and Fix
+
+Synthesize the stack event, pattern match, and CloudTrail correlation into a prioritized diagnosis.
+
+**Constraints:**
+
+- You MUST lead with the root cause of the FIRST failed event, because cascading failures often disappear once the first is fixed
+- You MUST classify each fix as either:
+  - **Template-level** (change the template, redeploy): missing required property, invalid enum, name conflict, cyclic `DependsOn`
+  - **Environment-level** (fix outside the template): IAM permission, service quota, resource state
+- For template-level fixes, You MUST provide the specific YAML/JSON change showing the corrected property
+- For environment-level fixes, You MUST provide the specific AWS CLI command or IAM statement to apply
+- You MUST NOT propose template changes for environment-level issues because that wastes cycles and does not resolve the underlying problem
+- You MUST show the CloudTrail console deeplink when CloudTrail events were retrieved
+- You SHOULD surface all failed events (not just the first) so the user can see cascading consequences, but clearly mark which is the root cause vs. downstream effects
+
+### 7. Recommend Next Steps
+
+Guide the user toward recovery.
+
+**Constraints:**
+
+- If the fix is template-level, You SHOULD recommend running a pre-deployment validation pipeline (cfn-lint → cfn-guard → change set validation) on the corrected template before redeploying, because re-deploying a broken template reruns the failure cycle
+- If the fix is environment-level, You MUST NOT recommend redeploying until the environment issue is confirmed resolved
+- If the stack is in `UPDATE_ROLLBACK_FAILED`, You MUST warn before recommending `continue-update-rollback` that it is a one-way operation and resources listed in `--resources-to-skip` will desynchronize from the template
+- If the stack is `DELETE_FAILED`, You SHOULD recommend inspecting the specific resource(s) blocking deletion before re-issuing delete
+- You SHOULD offer to help draft the corrected template or the environment fix on request
+
+## Examples
+
+### Example: IAM permission failure (environment-level)
+
+```
+Stack: my-api-stack (UPDATE_ROLLBACK_COMPLETE)
+Region: us-east-1
+
+Root cause (environment-level):
+  Resource: OrdersTable (AWS::DynamoDB::Table)
+  Status: CREATE_FAILED
+  Reason: User: arn:aws:iam::123456789012:role/CFNDeployRole is not authorized
+  to perform: dynamodb:CreateTable on resource: arn:aws:dynamodb:us-east-1:...
+
+CloudTrail evidence:
+  2026-04-21T14:23:05Z — CreateTable — AccessDenied
+  Deeplink: https://console.aws.amazon.com/cloudtrailv2/...
+
+Fix (no template change needed):
+  Attach this statement to role CFNDeployRole:
+    {
+      "Effect": "Allow",
+      "Action": ["dynamodb:CreateTable", "dynamodb:DescribeTable"],
+      "Resource": "arn:aws:dynamodb:us-east-1:123456789012:table/*"
+    }
+
+Next steps:
+  1. Apply the IAM policy change
+  2. Redeploy the stack (no template changes required)
+```
+
+### Example: Resource name conflict (template-level)
+
+```
+Stack: analytics-stack (CREATE_FAILED)
+Region: eu-west-1
+
+Root cause (template-level):
+  Resource: ReportBucket (AWS::S3::Bucket)
+  Status: CREATE_FAILED
+  Reason: acme-reports already exists
+
+Fix (template change):
+  Make the bucket name unique per stack:
+    ReportBucket:
+      Type: AWS::S3::Bucket
+      Properties:
+        BucketName: !Sub "${AWS::StackName}-reports"  # was: acme-reports
+
+Next steps:
+  1. Apply the template fix
+  2. Run pre-deployment validation (cfn-lint, cfn-guard, change set) on the
+     corrected template before redeploying
+  3. Delete the failed stack, then re-create with the corrected template
+```
+
+## Troubleshooting
+
+### "Stack not found" but I know the stack existed
+The stack was likely deleted after failure. If you have the Stack ARN (format: `arn:aws:cloudformation:<region>:<account>:stack/<name>/<uuid>`), pass it as `stack_name`. CloudFormation retains historical events for deleted stacks for ~90 days via `describe-events` with the ARN.
+
+### `describe-events` with `--filters FailedEvents=true` is not recognized
+The `--filters` parameter requires a recent AWS CLI version. Upgrade with `pip install --upgrade awscli` or `brew upgrade awscli`. As a fallback, use `describe-events` without the filter and manually filter for `EventType` in `[PROVISIONING_ERROR, VALIDATION_ERROR]`.
+
+### CloudTrail lookup returns nothing for a known failure
+Causes:
+
+- The failure was older than 90 days (CloudTrail Events history limit)
+- The CloudTrail trail is in a different region than the stack
+- The failing API call was made from a service that does not source from `cloudformation.amazonaws.com` (e.g., a Lambda-backed custom resource calls AWS APIs from its own execution role, so `sourceIPAddress` will differ)
+
+For older failures, check the S3 bucket configured for CloudTrail logging, if any.
+
+### The first failed event is a downstream effect, not the root cause
+Sometimes CloudFormation creates resources in parallel and the first reported failure is a dependency rather than the cause. Inspect all failed events; the root cause is often the one with the most specific `ResourceStatusReason` (e.g., "Property value is invalid" is more specific than "Dependency resource failed to create").

package/dist/global-skills/aws-cloudformation/references/validate-cloudformation-template.script.md

@@ -0,0 +1,135 @@
+# Validate CloudFormation Template
+
+## Overview
+
+Deterministic procedure for validating a CloudFormation template's syntax, schema, and resource properties using cfn-lint. Works via the `cfn-lint` CLI or Python API.
+
+## Parameters
+
+- **template_content** (required): The CloudFormation template as a YAML or JSON string, a file path, or a URL to the template.
+- **regions** (optional): List of AWS regions to validate against (e.g., `["us-east-1", "eu-west-1"]`). Defaults to cfn-lint's default region if omitted.
+- **ignore_checks** (optional): List of cfn-lint rule IDs to suppress (e.g., `["W2001", "E3012"]`).
+
+**Constraints for parameter acquisition:**
+
+- You MUST ask for all required parameters upfront in a single prompt rather than one at a time
+- You MUST support multiple input methods for the template:
+  - Direct input: Template content pasted directly in the conversation
+  - File path: Path to a local template file
+  - URL: Link to a template in a repository or S3
+- You MUST use appropriate tools to read the template content based on the input method
+- You MUST confirm successful acquisition of the template content before proceeding
+
+## Steps
+
+### 1. Verify Dependencies
+
+Check which validation mechanism is available.
+
+**Constraints:**
+
+- You MUST check in this order of preference:
+  1. `cfn-lint` CLI available on the user's system (verify with `which cfn-lint` or `cfn-lint --version`)
+  2. Python `cfnlint` library (verify by attempting `import cfnlint` in a throwaway Python command)
+- If cfn-lint is not installed, You MUST ask the user: "I can install `cfn-lint` via `pip install cfn-lint`. Do you want me to install it, or would you prefer to install it manually?"
+- You MUST NOT execute validation or run any install command without the user's explicit approval because this changes the user's environment
+- If no mechanism is available and the user declines installation, You MUST ask whether to abort or proceed anyway (knowing the SOP cannot complete)
+- You MUST respect the user's decision to proceed, install, or abort
+
+### 2. Acquire Template Content
+
+Obtain the CloudFormation template from the user.
+
+**Constraints:**
+
+- You MUST ask the user which template(s) to validate even if templates are discoverable in the working directory, because the user may only want a subset validated
+- You MUST read the template content from the provided source (file path, direct input, or URL)
+- You MUST confirm the template is non-empty and parseable as YAML or JSON before proceeding
+- If the template cannot be read or parsed, You MUST inform the user with the specific error and stop
+
+### 3. Run Validation
+
+Execute cfn-lint against the template using the best available mechanism.
+
+**Constraints:**
+
+- If `cfn-lint` CLI is available, You MUST invoke it on the template file with appropriate flags:
+  - Regions: `--regions us-east-1 eu-west-1`
+  - Ignore checks: `--ignore-checks W2001 E3012`
+  - Output format: `--format json` for structured output
+  - Example: `cfn-lint --format json --regions us-east-1 template.yaml`
+- Otherwise, if the Python `cfnlint` library is available, You MUST invoke `cfnlint.api.lint(s=template_content, config={"regions": [...], "ignore_checks": [...]})`
+- You MUST NOT modify the template content before validation because the user needs to see errors against their actual template
+- You MUST capture the full output including rule IDs, severity levels (E=error, W=warning, I=info), line numbers, and messages
+
+### 4. Present Results
+
+Report validation findings to the user.
+
+**Constraints:**
+
+- You MUST start the summary with the total count: "Your template has X errors, Y warnings, Z info messages"
+- You MUST group related issues by resource or template section (e.g., all `MyBucket` errors together)
+- You MUST prioritize errors first, then warnings, then informational messages
+- You MUST include the rule ID, line number, and property path for each issue so the user can locate it
+- For each error, You MUST provide the specific YAML/JSON fix showing the corrected property
+- You SHOULD use inline comments in code fixes to explain why each change is needed
+- For similar errors across multiple resources, You SHOULD show the pattern once with the list of affected resources
+- If the template is valid with no issues, You MUST confirm this clearly
+
+### 5. Recommend Next Steps
+
+Guide the user on what to do after validation.
+
+**Constraints:**
+
+- If errors were found, You MUST recommend fixing all errors before proceeding to other checks
+- Once the template is error-free, You SHOULD recommend running the `check-cloudformation-template-compliance` SOP to check security and compliance
+- After compliance passes, You SHOULD recommend the `cloudformation-pre-deploy-validation` SOP for final pre-deployment readiness
+- You MUST explain what each recommended next step does so the user can make an informed decision
+
+## Examples
+
+### Example Input
+
+```yaml
+AWSTemplateFormatVersion: '2010-09-09'
+Resources:
+  MyFunction:
+    Type: AWS::Lambda::Function
+    Properties:
+      FunctionNam: my-function
+      Runtime: python3.9
+      Handler: index.handler
+      Role: arn:aws:iam::123456789012:role/my-function-role
+      Code:
+        ZipFile: |
+          def handler(event, context):
+              return {'statusCode': 200}
+```
+
+### Example Output
+
+```
+Your template has 1 error, 0 warnings, 0 info messages.
+
+**MyFunction (AWS::Lambda::Function):**
+- E3002 at line 6: Invalid Property Resources/MyFunction/Properties/FunctionNam
+
+Fix (line 6):
+  FunctionName: my-function  # Typo: FunctionNam → FunctionName
+```
+
+## Troubleshooting
+
+### Template fails to parse
+If the tool or CLI returns a parsing error, the template has invalid YAML or JSON syntax. Check for indentation issues, missing colons, or unquoted special characters. Fix the syntax and re-run validation.
+
+### Unexpected rule violations
+If cfn-lint reports errors you believe are incorrect, suppress specific rules using `ignore_checks`. Verify the rule ID from the output (e.g., `W2001`) and pass it in the parameter.
+
+### Region-specific failures
+Some resource properties are only valid in certain regions. If you see region-related errors, pass the target deployment region in the `regions` parameter to get accurate validation.
+
+### cfn-lint not installed
+Install with `pip install cfn-lint`. The tool is maintained at https://github.com/aws-cloudformation/cfn-lint.

package/dist/global-skills/aws-serverless/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: aws-serverless
+description: Builds, deploys, manages, debugs, configures, and optimizes serverless applications on AWS using Lambda, API Gateway, Step Functions, EventBridge, and SAM/CDK. Covers cold starts, CORS debugging, event source mappings, troubleshooting, concurrency, SnapStart, Powertools, function URLs, EventBridge Scheduler, Lambda layers, and production readiness. Triggers on mentions of Lambda, API Gateway, Step Functions, SAM templates, CDK serverless stacks, DynamoDB stream triggers, SQS event sources, cold starts, timeouts, 502/504 errors, throttling, concurrency, CORS, Powertools, or any event-driven architecture on AWS, even without the word "serverless." Does not apply to EC2, ECS/Fargate containers, or Amplify hosting.
+version: 1
+metadata:
+  service: [lambda, api-gateway, step-functions, eventbridge, dynamodb, sqs, sns, s3, kinesis]
+  task: [build, deploy, debug, optimize]
+  persona: [developer, devops]
+  workload: [serverless]
+---
+
+# AWS Serverless
+## Overview
+
+Domain expertise for building serverless applications on AWS. Covers Lambda configuration, API Gateway debugging, Step Functions orchestration, EventBridge patterns, event source mappings, concurrency tuning, cold start optimization, deployment with SAM/CDK, production readiness, and troubleshooting across all serverless services.
+
+**Works best with** the [AWS MCP server](https://docs.aws.amazon.com/aws-mcp/) — enables running CLI commands, querying CloudWatch, and validating configurations directly. All guidance also works with standard AWS CLI access.
+
+**Note:** Reference files contain specific runtime versions, quota values, and feature matrices that may change. When precision matters (e.g., deploying to production, choosing a runtime, or checking a quota), confirm values against current AWS documentation rather than relying solely on the values in these files.
+
+## Routing
+
+| User need | Action |
+|-----------|--------|
+| Building a new serverless app | Read [architecture.md](references/architecture.md) for pattern selection, then [deployment.md](references/deployment.md) for SAM/CDK templates |
+| Debugging an error | Read [troubleshooting.md](references/troubleshooting.md) — starts with the 5 most common fixes |
+| Optimizing performance or cost | Read [lambda.md](references/lambda.md) for cold starts and memory tuning, [production.md](references/production.md) for readiness checklist |
+| Configuring event sources (SQS, DDB Streams, SNS) | Read [event-sources.md](references/event-sources.md) |
+| Step Functions, EventBridge, or orchestration | Read [orchestration.md](references/orchestration.md) |
+| Concurrency configuration | Read [concurrency.md](references/concurrency.md) |
+| API Gateway setup | Read [api-gateway.md](references/api-gateway.md) |
+| Common anti-patterns | Read the anti-patterns section in [production.md](references/production.md) |
+| Starting with Powertools | Use [powertools-handler.py](assets/powertools-handler.py) as a template |
+| Lambda Managed Instances, LMI, capacity providers, EC2-backed Lambda, PerExecutionEnvironmentMaxConcurrency | Use the **aws-lambda-managed-instances** skill instead |
+| Durable functions, durable execution, checkpoint-and-replay | Use the **aws-lambda-durable-functions** skill instead |
+| Firecracker microVMs, strong tenant isolation, sandboxed/untrusted code execution, long-lived sessions, suspend/resume, port-listening servers, snapshot-resumable compute | Use the **aws-lambda-microvms** skill instead |
+| Spans multiple areas | Read the most specific reference first, then consult others as needed |
+
+## Files
+
+| File | Content |
+|------|---------|
+| [lambda.md](references/lambda.md) | Runtime, memory/CPU, cold starts, SnapStart, layers, containers |
+| [api-gateway.md](references/api-gateway.md) | REST vs HTTP API, stages, auth, throttling, mapping |
+| [event-sources.md](references/event-sources.md) | SQS, DDB Streams, SNS, S3, Kinesis triggers |
+| [orchestration.md](references/orchestration.md) | Step Functions, EventBridge rules/pipes/scheduler |
+| [concurrency.md](references/concurrency.md) | Reserved vs provisioned, scaling, ESM concurrency |
+| [architecture.md](references/architecture.md) | Patterns, reference architectures, service selection |
+| [deployment.md](references/deployment.md) | SAM/CDK resource types, globals, fast iteration |
+| [production.md](references/production.md) | Readiness checklist, observability, anti-patterns |
+| [troubleshooting.md](references/troubleshooting.md) | Error → cause → fix for all serverless services |

package/dist/global-skills/aws-serverless/assets/powertools-handler.py

@@ -0,0 +1,49 @@
+"""Lambda handler with Powertools Logger, Tracer, Metrics, and Idempotency wired."""
+
+import json
+
+from aws_lambda_powertools import Logger, Metrics, Tracer
+from aws_lambda_powertools.metrics import MetricUnit
+from aws_lambda_powertools.utilities.idempotency import (
+    DynamoDBPersistenceLayer,
+    IdempotencyConfig,
+    idempotent,
+)
+from aws_lambda_powertools.utilities.typing import LambdaContext
+
+logger = Logger()
+tracer = Tracer()
+metrics = Metrics()
+persistence = DynamoDBPersistenceLayer(table_name="IdempotencyTable")
+
+# Idempotency key: "body" deduplicates identical payloads.
+config = IdempotencyConfig(event_key_jmespath="body")
+
+
+# Set log_event=True only in non-production environments;
+# events may contain auth tokens, cookies, or PII.
+@logger.inject_lambda_context(log_event=False)
+@tracer.capture_lambda_handler
+@metrics.log_metrics(capture_cold_start_metric=True)
+@idempotent(config=config, persistence_store=persistence)
+def handler(event: dict, context: LambdaContext) -> dict:
+    logger.info("Processing request")
+
+    result = process(event)
+
+    metrics.add_metric(name="RequestsProcessed", unit=MetricUnit.Count, value=1)
+
+    return {
+        "statusCode": 200,
+        "headers": {
+            "Content-Type": "application/json",
+            "Access-Control-Allow-Origin": "https://your-domain.example",  # Replace with your domain
+        },
+        "body": json.dumps(result),
+    }
+
+
+@tracer.capture_method
+def process(event: dict) -> dict:
+    """Replace with your business logic."""
+    return {"message": "success"}