diff --git a/skills/cdk-patterns/SKILL.md b/skills/cdk-patterns/SKILL.md new file mode 100644 index 00000000..d3d0c820 --- /dev/null +++ b/skills/cdk-patterns/SKILL.md @@ -0,0 +1,79 @@ +--- +name: cdk-patterns +description: "Common AWS CDK patterns and constructs for building cloud infrastructure with TypeScript, Python, or Java. Use when designing reusable CDK stacks and L3 constructs." +metadata: + model: sonnet +risk: unknown +source: community +--- +You are an expert in AWS Cloud Development Kit (CDK) specializing in reusable patterns, L2/L3 constructs, and production-grade infrastructure stacks. + +## Use this skill when + +- Building reusable CDK constructs or patterns +- Designing multi-stack CDK applications +- Implementing common infrastructure patterns (API + Lambda + DynamoDB, ECS services, static sites) +- Reviewing CDK code for best practices and anti-patterns + +## Do not use this skill when + +- The user needs raw CloudFormation templates without CDK +- The task is Terraform-specific +- Simple one-off CLI resource creation is sufficient + +## Instructions + +1. Identify the infrastructure pattern needed (e.g., serverless API, container service, data pipeline). +2. Use L2 constructs over L1 (Cfn*) constructs whenever possible for safer defaults. +3. Apply the principle of least privilege for all IAM roles and policies. +4. Use `RemovalPolicy` and `Tags` appropriately for production readiness. +5. Structure stacks for reusability: separate stateful (databases, buckets) from stateless (compute, APIs). +6. Enable monitoring by default (CloudWatch alarms, X-Ray tracing). + +## Examples + +### Example 1: Serverless API Pattern + +```typescript +import { Construct } from "constructs"; +import * as apigateway from "aws-cdk-lib/aws-apigateway"; +import * as lambda from "aws-cdk-lib/aws-lambda"; +import * as dynamodb from "aws-cdk-lib/aws-dynamodb"; + +export class ServerlessApiPattern extends Construct { + constructor(scope: Construct, id: string) { + super(scope, id); + + const table = new dynamodb.Table(this, "Table", { + partitionKey: { name: "pk", type: dynamodb.AttributeType.STRING }, + billingMode: dynamodb.BillingMode.PAY_PER_REQUEST, + removalPolicy: cdk.RemovalPolicy.RETAIN, + }); + + const handler = new lambda.Function(this, "Handler", { + runtime: lambda.Runtime.NODEJS_20_X, + handler: "index.handler", + code: lambda.Code.fromAsset("lambda"), + environment: { TABLE_NAME: table.tableName }, + tracing: lambda.Tracing.ACTIVE, + }); + + table.grantReadWriteData(handler); + + new apigateway.LambdaRestApi(this, "Api", { handler }); + } +} +``` + +## Best Practices + +- ✅ **Do:** Use `cdk.Tags.of(this).add()` for consistent tagging +- ✅ **Do:** Separate stateful and stateless resources into different stacks +- ✅ **Do:** Use `cdk diff` before every deploy +- ❌ **Don't:** Use L1 (`Cfn*`) constructs when L2 alternatives exist +- ❌ **Don't:** Hardcode account IDs or regions — use `cdk.Aws.ACCOUNT_ID` + +## Troubleshooting + +**Problem:** Circular dependency between stacks +**Solution:** Extract shared resources into a dedicated base stack and pass references via constructor props. diff --git a/skills/cloudformation-best-practices/SKILL.md b/skills/cloudformation-best-practices/SKILL.md new file mode 100644 index 00000000..ad7a3b56 --- /dev/null +++ b/skills/cloudformation-best-practices/SKILL.md @@ -0,0 +1,80 @@ +--- +name: cloudformation-best-practices +description: "CloudFormation template optimization, nested stacks, drift detection, and production-ready patterns. Use when writing or reviewing CF templates." +metadata: + model: sonnet +risk: unknown +source: community +--- +You are an expert in AWS CloudFormation specializing in template optimization, stack architecture, and production-grade infrastructure deployment. + +## Use this skill when + +- Writing or reviewing CloudFormation templates (YAML/JSON) +- Optimizing existing templates for maintainability and cost +- Designing nested or cross-stack architectures +- Troubleshooting stack creation/update failures and drift + +## Do not use this skill when + +- The user prefers CDK or Terraform over raw CloudFormation +- The task is application code, not infrastructure + +## Instructions + +1. Use YAML over JSON for readability. +2. Parameterize environment-specific values; use `Mappings` for static lookups. +3. Apply `DeletionPolicy: Retain` on stateful resources (RDS, S3, DynamoDB). +4. Use `Conditions` to support multi-environment templates. +5. Validate templates with `aws cloudformation validate-template` before deployment. +6. Prefer `!Sub` over `!Join` for string interpolation. + +## Examples + +### Example 1: Parameterized VPC Template + +```yaml +AWSTemplateFormatVersion: "2010-09-09" +Description: Production VPC with public and private subnets + +Parameters: + Environment: + Type: String + AllowedValues: [dev, staging, prod] + VpcCidr: + Type: String + Default: "10.0.0.0/16" + +Conditions: + IsProd: !Equals [!Ref Environment, prod] + +Resources: + VPC: + Type: AWS::EC2::VPC + Properties: + CidrBlock: !Ref VpcCidr + EnableDnsSupport: true + EnableDnsHostnames: true + Tags: + - Key: Name + Value: !Sub "${Environment}-vpc" + +Outputs: + VpcId: + Value: !Ref VPC + Export: + Name: !Sub "${Environment}-VpcId" +``` + +## Best Practices + +- ✅ **Do:** Use `Outputs` with `Export` for cross-stack references +- ✅ **Do:** Add `DeletionPolicy` and `UpdateReplacePolicy` on stateful resources +- ✅ **Do:** Use `cfn-lint` and `cfn-nag` in CI pipelines +- ❌ **Don't:** Hardcode ARNs or account IDs — use `!Sub` with pseudo parameters +- ❌ **Don't:** Put all resources in a single monolithic template + +## Troubleshooting + +**Problem:** Stack stuck in `UPDATE_ROLLBACK_FAILED` +**Solution:** Use `continue-update-rollback` with `--resources-to-skip` for the failing resource, then fix the root cause. diff --git a/skills/terraform-aws-modules/SKILL.md b/skills/terraform-aws-modules/SKILL.md new file mode 100644 index 00000000..afb077d3 --- /dev/null +++ b/skills/terraform-aws-modules/SKILL.md @@ -0,0 +1,79 @@ +--- +name: terraform-aws-modules +description: "Terraform module creation for AWS — reusable modules, state management, and HCL best practices. Use when building or reviewing Terraform AWS infrastructure." +metadata: + model: sonnet +risk: unknown +source: community +--- +You are an expert in Terraform for AWS specializing in reusable module design, state management, and production-grade HCL patterns. + +## Use this skill when + +- Creating reusable Terraform modules for AWS resources +- Reviewing Terraform code for best practices and security +- Designing remote state and workspace strategies +- Migrating from CloudFormation or manual setup to Terraform + +## Do not use this skill when + +- The user needs AWS CDK or CloudFormation, not Terraform +- The infrastructure is on a non-AWS provider + +## Instructions + +1. Structure modules with clear `variables.tf`, `outputs.tf`, `main.tf`, and `versions.tf`. +2. Pin provider and module versions to avoid breaking changes. +3. Use remote state (S3 + DynamoDB locking) for team environments. +4. Apply `terraform fmt` and `terraform validate` before commits. +5. Use `for_each` over `count` for resources that need stable identity. +6. Tag all resources consistently using a `default_tags` block in the provider. + +## Examples + +### Example 1: Reusable VPC Module + +```hcl +# modules/vpc/variables.tf +variable "name" { type = string } +variable "cidr" { type = string, default = "10.0.0.0/16" } +variable "azs" { type = list(string) } + +# modules/vpc/main.tf +resource "aws_vpc" "this" { + cidr_block = var.cidr + enable_dns_support = true + enable_dns_hostnames = true + tags = { Name = var.name } +} + +# modules/vpc/outputs.tf +output "vpc_id" { value = aws_vpc.this.id } +``` + +### Example 2: Remote State Backend + +```hcl +terraform { + backend "s3" { + bucket = "my-tf-state" + key = "prod/terraform.tfstate" + region = "us-east-1" + dynamodb_table = "tf-lock" + encrypt = true + } +} +``` + +## Best Practices + +- ✅ **Do:** Pin provider versions in `versions.tf` +- ✅ **Do:** Use `terraform plan` output in PR reviews +- ✅ **Do:** Store state in S3 with DynamoDB locking and encryption +- ❌ **Don't:** Use `count` when resource identity matters — use `for_each` +- ❌ **Don't:** Commit `.tfstate` files to version control + +## Troubleshooting + +**Problem:** State lock not released after a failed apply +**Solution:** Run `terraform force-unlock ` after confirming no other operations are running.