Skip to content

Commit 54c11da

Browse files
amrabedamrabed
committed
feat(skills): implement agent skills for lambda template
1 parent e742639 commit 54c11da

7 files changed

Lines changed: 374 additions & 8 deletions

File tree

‎.agents/skills/deploy-aws/SKILL.md‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
---
2+
name: deploy-aws
3+
description: Synthesizes, diffs, and deploys CDK Lambda stacks to AWS cloud environments using mise and CDK CLI. Use whenever the user asks to deploy, diff, or release a Lambda stack to AWS.
4+
category: coding
5+
tags: [aws, cdk, deploy, cloud, lambda, cur8d]
6+
---
7+
8+
# Deploy cur8d Lambda Stacks to AWS
9+
10+
This skill guides you through deploying AWS CDK Lambda stacks to a live AWS cloud environment adhering to cur8d quality and safety gates.
11+
12+
## Prerequisites
13+
14+
- AWS CLI configured with active credentials (`aws sts get-caller-identity` succeeds)
15+
- `mise` installed
16+
- Docker installed (required for CDK bundling and container image lambdas)
17+
18+
## Workflow
19+
20+
### 1. Verify Active AWS Identity & Target Environment
21+
Verify credentials and current account/region:
22+
23+
```bash
24+
aws sts get-caller-identity
25+
```
26+
27+
Ensure `AWS_REGION` or `AWS_DEFAULT_REGION` is explicitly configured.
28+
29+
### 2. Pre-Flight Verification
30+
Run all tests and linters before executing any cloud deployment:
31+
32+
```bash
33+
mise run verify
34+
```
35+
36+
Fix any linting or test regressions before proceeding.
37+
38+
### 3. Inspect CDK Infrastructure Changes (Diff)
39+
Generate a diff against the currently deployed cloud stack:
40+
41+
```bash
42+
mise run diff <stack_name>
43+
```
44+
45+
Carefully inspect:
46+
- Resources being added, updated, or destroyed (look out for accidental deletions of stateful resources like DynamoDB tables or S3 buckets).
47+
- IAM permission changes and policies.
48+
49+
### 4. Deploy the Stack
50+
Deploy the stack to AWS:
51+
52+
```bash
53+
mise run deploy <stack_name>
54+
```
55+
56+
Monitor the deployment progress in the terminal output. Upon success, CDK outputs (API Gateway endpoints, ARN outputs) will be printed.
57+
58+
### 5. Post-Deployment Verification
59+
- Test the deployed Lambda or API Gateway endpoint using `curl` or AWS CLI.
60+
- Check CloudWatch Logs for recent invocations:
61+
```bash
62+
aws logs tail /aws/lambda/<function_name> --since 5m --follow
63+
```
64+
65+
### 6. Teardown / Destruction (If Requested)
66+
To tear down the deployed stack:
67+
68+
```bash
69+
mise run destroy <stack_name>
70+
```
71+
72+
## Boundaries
73+
74+
✅ **Always do:**
75+
- Always run `aws sts get-caller-identity` to confirm the target account before deploying.
76+
- Always run `mise run verify` and `mise run diff <stack_name>` prior to deployment.
77+
- Always capture and report cloud deployment outputs (e.g., API Gateway URLs) back to the user.
78+
79+
🚫 **Never do:**
80+
- Never run deployment if `mise run verify` fails.
81+
- Never destroy production stacks without explicit user confirmation.

‎.agents/skills/init-project/SKILL.md‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
---
2+
name: init-project
3+
description: Initializes and customizes a new AWS Lambda service repository from the cur8d/lambda template. Use whenever the user asks to initialize, bootstrap, or configure a newly cloned or forked Lambda project.
4+
category: system
5+
tags: [scaffolding, template, init, aws, lambda, cur8d]
6+
---
7+
8+
# Initialize Project from cur8d/lambda Template
9+
10+
This skill guides you through transforming a newly cloned or forked `cur8d/lambda` repository into a fully personalized, standalone AWS Lambda project.
11+
12+
## Prerequisites
13+
14+
- Python 3.12+ and `uv` installed
15+
- `mise` installed
16+
- Clean git working tree
17+
18+
## Workflow
19+
20+
### 1. Gather Project Parameters
21+
Identify or ask the user for:
22+
- **Project Name** (kebab-case, e.g., `billing-service`)
23+
- **Description** (one-line summary, e.g., `Billing webhook and subscription processor`)
24+
- **Author Name** and **Email** (fallback to current git user: `git config user.name`, `git config user.email`)
25+
- **GitHub Username / Org** (e.g., `cur8d` or your personal handle)
26+
27+
### 2. Execute Template Initialization
28+
Run the built-in initialization script using `uv`:
29+
30+
```bash
31+
uv run python scripts/init.py \
32+
--name "<project-name>" \
33+
--description "<project-description>" \
34+
--author "<author-name>" \
35+
--email "<author-email>" \
36+
--github "<github-username>"
37+
```
38+
39+
The script will:
40+
- Rename `templates/` to the sanitized project package name (e.g. `billing_service/`).
41+
- Update package metadata in `pyproject.toml`.
42+
- Update repository references in `mkdocs.yml`, `.github/CODEOWNERS`, and documentation.
43+
- Remove `scripts/init.py` upon successful customization.
44+
45+
### 3. Local Environment Configuration
46+
Copy the template local environment file:
47+
48+
```bash
49+
cp .env.local.example .env.local
50+
```
51+
52+
Instruct the user or configure `LOCALSTACK_AUTH_TOKEN` if using LocalStack Pro features.
53+
54+
### 4. Verify Baseline
55+
Run repository verification to ensure formatting, linting, and tests pass:
56+
57+
```bash
58+
mise run verify
59+
```
60+
61+
## Boundaries
62+
63+
✅ **Always do:**
64+
- Always run `mise run verify` after initialization to ensure all renamed imports resolve cleanly.
65+
- Always verify git config values before prompting the user for author information.
66+
- Always copy `.env.local.example` to `.env.local`.
67+
68+
🚫 **Never do:**
69+
- Never run the initialization script with empty or invalid names (only alphanumeric characters, dashes, and underscores are allowed).
70+
- Never push initial changes to the upstream `cur8d/lambda` template repo; ensure git remotes point to the user's repository.

‎.agents/skills/local-invoke/SKILL.md‎

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
---
2+
name: local-invoke
3+
description: Generates synthetic event payloads and tests Lambda function execution locally using LocalStack. Use whenever the user asks to test, invoke, or debug a Lambda function or CDK stack locally.
4+
category: coding
5+
tags: [aws, lambda, localstack, testing, invoke, cur8d]
6+
---
7+
8+
# Test and Invoke Lambda Locally with LocalStack
9+
10+
This skill guides you through spinning up LocalStack, deploying the target CDK stack locally, generating test event payloads, and invoking the Lambda function without hitting AWS cloud.
11+
12+
## Prerequisites
13+
14+
- Docker installed and running
15+
- `.env.local` configured (copied from `.env.local.example`)
16+
- `mise` installed
17+
18+
## Workflow
19+
20+
### 1. Start LocalStack
21+
Launch the local AWS emulation container:
22+
23+
```bash
24+
mise run local:up
25+
```
26+
27+
Verify that the LocalStack gateway is responding at `http://localhost:4566`:
28+
29+
```bash
30+
curl -s http://localhost:4566/_localstack/health | jq .
31+
```
32+
33+
### 2. Deploy Stack to LocalStack
34+
Deploy the target stack locally using `aws-cdk-local`:
35+
36+
```bash
37+
mise run local:deploy <stack_name>
38+
```
39+
40+
*(You can also use the shorthand alias `mise run local <stack_name>` or `dl <stack_name>`)*
41+
42+
### 3. Generate Event Payload
43+
Synthesize a JSON test event matching the Lambda's trigger. For example:
44+
45+
**API Gateway HTTP Payload:**
46+
```json
47+
{
48+
"version": "2.0",
49+
"routeKey": "POST /items",
50+
"rawPath": "/items",
51+
"headers": {
52+
"content-type": "application/json"
53+
},
54+
"body": "{\"name\": \"sample-item\", \"value\": 42}",
55+
"isBase64Encoded": false
56+
}
57+
```
58+
59+
**SQS Message Payload:**
60+
```json
61+
{
62+
"Records": [
63+
{
64+
"messageId": "msg-12345",
65+
"body": "{\"action\": \"process\", \"id\": 1}",
66+
"eventSource": "aws:sqs"
67+
}
68+
]
69+
}
70+
```
71+
72+
Save payload to a temporary file (e.g. `/tmp/event.json`).
73+
74+
### 4. Invoke the Function
75+
Invoke using AWS CLI pointing to the local endpoint:
76+
77+
```bash
78+
aws --endpoint-url=http://localhost:4566 lambda invoke \
79+
--function-name <function_name> \
80+
--payload fileb:///tmp/event.json \
81+
/tmp/response.json
82+
```
83+
84+
Inspect the output:
85+
```bash
86+
cat /tmp/response.json
87+
```
88+
89+
### 5. Teardown / Cleanup
90+
When testing is complete:
91+
92+
```bash
93+
# Tear down the stack
94+
mise run local:destroy <stack_name>
95+
96+
# Stop LocalStack container
97+
mise run local:down
98+
```
99+
100+
## Boundaries
101+
102+
✅ **Always do:**
103+
- Always ensure LocalStack is up before deploying or invoking (`mise run local:up`).
104+
- Always pass `--endpoint-url=http://localhost:4566` when using AWS CLI for local testing.
105+
- Always clean up temporary payload files.
106+
107+
🚫 **Never do:**
108+
- Never commit secret API tokens or sensitive production data in test payload files.
109+
- Never deploy to real AWS when local testing is intended.

‎.agents/skills/new-lambda/SKILL.md‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
---
2+
name: new-lambda
3+
description: Scaffolds a new event-driven AWS Lambda function adhering to cur8d standards with Powertools (Logger, Tracer, Metrics), Pydantic models, unit tests, and CDK infrastructure stack. Use whenever the user asks to create, scaffold, or add a Lambda function or service.
4+
category: coding
5+
tags: [aws, lambda, cdk, python, powertools, cur8d]
6+
---
7+
8+
# Create New Lambda Function in cur8d/lambda
9+
10+
This skill guides you through scaffolding, implementing, and registering a new AWS Lambda function and its corresponding AWS CDK infrastructure stack in `cur8d/lambda`.
11+
12+
## Prerequisites
13+
14+
- Python 3.12+ and `uv` installed
15+
- `mise` installed
16+
- Docker installed and running (for local test invoke via LocalStack)
17+
18+
## Workflow
19+
20+
### 1. Scaffold Boilerplate Files
21+
Run the built-in generator script with the function name (in snake_case or kebab-case):
22+
23+
```bash
24+
uv run python scripts/new.py --name <function_name>
25+
```
26+
27+
This generates:
28+
- `templates/<function_name>/handler.py` (Lambda handler entry point)
29+
- `templates/<function_name>/models.py` (Pydantic payload/event models)
30+
- `templates/<function_name>/settings.py` (Environment variables and settings via Pydantic)
31+
- `tests/<function_name>/test_handler.py` (Pytest test suite)
32+
- `infra/stacks/<function_name>.py` (AWS CDK Stack definition)
33+
- `docs/template/<function_name>.md` & `docs/reference/<function_name>.md` (Documentation)
34+
- Updates `infra/app.py` to register the new stack in `STACK_REGISTRY`.
35+
36+
### 2. Implement Handler Logic & Models
37+
In `templates/<function_name>/handler.py`:
38+
- Use AWS Lambda Powertools decorators:
39+
```python
40+
from aws_lambda_powertools import Logger, Metrics, Tracer
41+
42+
logger = Logger()
43+
tracer = Tracer()
44+
metrics = Metrics()
45+
46+
47+
@logger.inject_lambda_context(log_event=True)
48+
@tracer.capture_lambda_handler
49+
@metrics.log_metrics(capture_cold_start_metric=True)
50+
def lambda_handler(event: dict, context) -> dict: ...
51+
```
52+
- Define typed request/event models in `models.py` using Pydantic.
53+
- Define environment settings in `settings.py` using `pydantic_settings.BaseSettings`.
54+
55+
### 3. Configure the CDK Stack
56+
In `infra/stacks/<function_name>.py`:
57+
- Customize runtime settings (memory size, timeout, log retention).
58+
- Wire triggers according to event source (API Gateway, SQS Queue, S3 Event, EventBridge rule, DynamoDB Streams).
59+
- Configure IAM permissions with least privilege.
60+
61+
### 4. Implement Unit Tests
62+
In `tests/<function_name>/test_handler.py`:
63+
- Test successful execution with nominal mock event payloads.
64+
- Test invalid event schemas (expect appropriate validation errors).
65+
- Test error handling and cold start resilience.
66+
67+
### 5. Verify Quality Gates
68+
Run repository verification:
69+
70+
```bash
71+
mise run verify
72+
```
73+
74+
Ensure formatting (`ruff format`), linting (`ruff check`), type checks, and pytest tests pass.
75+
76+
## Boundaries
77+
78+
✅ **Always do:**
79+
- Always decorate handlers with `@logger.inject_lambda_context`, `@tracer.capture_lambda_handler`, and `@metrics.log_metrics`.
80+
- Always register the new CDK stack in `infra/app.py`'s `STACK_REGISTRY`.
81+
- Always verify all checks pass with `mise run verify` before committing.
82+
83+
🚫 **Never do:**
84+
- Never hardcode AWS credentials, account IDs, or region names in handlers or stacks.
85+
- Never write handlers without companion unit tests in `tests/<function_name>/`.

‎.vibe/specs/add-skills/tasks.md‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
11
# Tasks: Agent Skills for cur8d Lambda
22

3-
- [ ] Create `.agents/skills/init-project/SKILL.md` <!-- id: 0 -->
4-
- [ ] Create `.agents/skills/new-lambda/SKILL.md` <!-- id: 1 -->
5-
- [ ] Create `.agents/skills/local-invoke/SKILL.md` <!-- id: 2 -->
6-
- [ ] Create `.agents/skills/deploy-aws/SKILL.md` <!-- id: 3 -->
7-
- [ ] Update `AGENTS.md` with skills inventory and triggering instructions <!-- id: 4 -->
8-
- [ ] Update `docs/README.md` with Agent Skills documentation <!-- id: 5 -->
9-
- [ ] Run `mise run verify` to ensure tests and linters pass <!-- id: 6 -->
10-
- [ ] Verify skills discovery with `npx skills` <!-- id: 7 -->
3+
- [x] Create `.agents/skills/init-project/SKILL.md` <!-- id: 0 -->
4+
- [x] Create `.agents/skills/new-lambda/SKILL.md` <!-- id: 1 -->
5+
- [x] Create `.agents/skills/local-invoke/SKILL.md` <!-- id: 2 -->
6+
- [x] Create `.agents/skills/deploy-aws/SKILL.md` <!-- id: 3 -->
7+
- [x] Update `AGENTS.md` with skills inventory and triggering instructions <!-- id: 4 -->
8+
- [x] Update `docs/README.md` with Agent Skills documentation <!-- id: 5 -->
9+
- [x] Run `mise run verify` to ensure tests and linters pass <!-- id: 6 -->
10+
- [x] Verify skills discovery with `npx skills` <!-- id: 7 -->

‎AGENTS.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -206,3 +206,23 @@ if __name__ == "__main__":
206206
### Lambda Entry Point
207207

208208
- The main Lambda entry point should be named `main`.
209+
210+
## Agent Skills
211+
212+
This repository provides built-in modular skills following the open Agent Skills standard under `.agents/skills/`:
213+
214+
| Skill | Purpose | Trigger / Usage |
215+
| :--- | :--- | :--- |
216+
| [`init-project`](.agents/skills/init-project/SKILL.md) | Initialize template into a standalone service | Initializing, bootstrapping, or configuring a new project from this repo |
217+
| [`new-lambda`](.agents/skills/new-lambda/SKILL.md) | Scaffold event-driven Lambda with CDK stack and tests | Creating or adding a new Lambda template or handler |
218+
| [`local-invoke`](.agents/skills/local-invoke/SKILL.md) | Test and invoke Lambda locally using LocalStack | Testing, invoking, or debugging Lambda execution locally |
219+
| [`deploy-aws`](.agents/skills/deploy-aws/SKILL.md) | Diff and deploy CDK stacks to live AWS cloud | Deploying, diffing, or releasing CDK stacks to AWS |
220+
221+
To discover or use skills with the `skills` CLI:
222+
```bash
223+
# List available skills
224+
npx skills add cur8d/lambda --list
225+
226+
# Install skills to current project
227+
npx skills add cur8d/lambda
228+
```

‎docs/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,7 @@ Templates come pre-wired with:
4444
- **Pre-commit Validations**: [pre-commit](https://pre-commit.com) hooks
4545
- **Workflow Automation**: [GitHub Actions](https://github.com/features/actions) for CI/CD and documentation auto-deployment to [GitHub Pages](https://pages.github.com)
4646
- **Tool Management & Tasks**: [mise](https://mise.jdx.dev/) for managing project tools and automating common development tasks
47+
- **Agent Skills**: Built-in modular AI agent skills under `.agents/skills/` compatible with [skills.sh](https://skills.sh), Claude Code, Cursor, and Google Antigravity
4748

4849
### GitHub files
4950

0 commit comments

Comments
 (0)