# Easysam Skill

> Build and deploy modular serverless applications using the EasySAM YAML-to-SAM generator. Always use this skill whenever the user asks to scaffold a serverless project, configure AWS resources (Lambda, DynamoDB, S3, SQS, SNS, EventBridge poller, OpenSearch Serverless, Kinesis, Function URLs), define resources.yaml or easysam.yaml, inspect schema or cloud settings, generate SAM templates, or set up GitHub Actions CI/CD pipelines for serverless applications, even if they don't explicitly mention 'EasySAM'.

- Skill: `scartill/easysam-skill` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add scartill/easysam-skill`
- Raw SKILL.md: https://api.skillmd.com/api/skills/scartill/easysam-skill/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: scartill (https://skillmd.com/u/scartill)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/scartill/easysam-skill

---


# EasySAM Skill

This skill provides opinionated workflows and syntax rules for building, validating, and deploying serverless applications using the EasySAM YAML-to-SAM generator.

## Core Directives & Cardinal Rules

1. **NEVER Edit `template.yml` Directly**:
   `template.yml` (and `template.yaml`) is an ephemeral build artifact automatically generated by `easysam generate` and `easysam deploy`. **Do NOT edit `template.yml` manually under any circumstances.** All configuration changes must be made in `resources.yaml`, module-level `easysam.yaml`, or `deploy-context.yaml`.
2. **FastAPI Lambdas MUST Be Greedy**:
   Any Lambda function using FastAPI or similar routing frameworks must set `greedy: true` under `integration:`. FastAPI manages internal sub-path routing (`/api/v1/items`); non-greedy routes will cause API Gateway to return 404 for sub-routes.
3. **Deployment Failure Circuit-Breaker**:
   If `easysam deploy` or CloudFormation stack update gets stuck, fails, or enters a rollback loop **2 or more times**: **STOP attempting retries immediately.** Do not run command loops. Output the exact failure details from CloudFormation logs and inform the user so they can intervene (e.g. manual console rollback, `easysam delete --force`, or fixing CloudFormation resource locks).
4. **Do NOT Run Standalone `prismarine generate-client`**:
   When using Prismarine in EasySAM, client code generation (`prismarine_client.py`) is **automatically performed as an integrated step of `easysam generate .` and `easysam deploy .`**. Do NOT execute separate `prismarine generate-client` shell commands.

## Standard Project Hierarchy

EasySAM strictly enforces a modular "Module Pattern" for organizing AWS resources. Divide applications into feature or resource modules:

```text
my-project/
├── resources.yaml            # Global configuration (prefix, tags, python, envvars) and module imports
├── deploy-context.yaml       # Environment overrides (dev, prod ARNs/VPCs)
├── .gitignore                # Excludes **/common/ and **/prismarine_clients/
├── sam/
│   └── thirdparty/
│       └── requirements.txt  # Runtime dependencies packaged into Lambda artifacts
├── pyproject.toml            # Dev dependencies (pytest, ruff, easysam)
├── backend/                  # Main module (imported by resources.yaml)
│   ├── database/             # Database resources module (DynamoDB or Prismarine schema)
│   │   ├── easysam.yaml
│   │   └── schema.prisma     # Prismarine schema (if using Prismarine ORM)
│   └── function/             # Compute resources module
│       └── my-function/
│           ├── easysam.yaml  # Local resource definition
│           └── index.py      # Lambda handler code
├── common/                   # Shared application logic & custom DynamoAccess helpers
│   ├── utils.py
│   └── dynamo_access.py      # Custom DynamoAccess helper (if not using Prismarine)
└── tests/                    # Unit & integration test suite (pytest)
    └── test_myapp.py
```

### Key Architectural & Git Conventions
- **Modular Imports**: Root `resources.yaml` must list sub-modules under `import:` (e.g., `import: [backend]`).
- **Git Configuration**: Every `.gitignore` (or root `.gitignore`) **must** exclude:
  - `**/common/` (synced shared code modules)
  - `**/prismarine_clients/` (auto-generated Prismarine ORM clients)
- **Dependency Management**:
  - Place Lambda runtime packages in `sam/thirdparty/requirements.txt`.
  - Keep project dependencies empty in `pyproject.toml` (`[project] dependencies = []`) and place development tools under `[dependency-groups] dev`.

## Data Access Guidance: Prismarine vs Custom `DynamoAccess`

When building DynamoDB-backed applications in EasySAM, choose one of two supported data access patterns:

1. **Prismarine (Prisma for DynamoDB)**:
   - **Use Case**: Schema-driven ORM with type-safe models, auto-generated Pydantic models, and structured queries.
   - **Setup**: Define models in `common/<package>/models.py` and configure `prismarine:` in `resources.yaml`. EasySAM automatically generates `prismarine_client.py` during `easysam generate .` or `easysam deploy .`.
2. **Custom `DynamoAccess` (boto3 Helper)**:
   - **Use Case**: Lightweight, zero-dependency, low-latency DynamoDB access using direct `boto3` queries.
   - **Setup**: Define a `DynamoAccess` class in `common/dynamo_access.py` wrapping `boto3.resource('dynamodb')` table operations (`get_item`, `put_item`, `query`, `update_item`).

## Core Developer Workflows

### 1. Scaffolding a New Application
1. Run `uv run easysam init` to initialize project baseline.
2. Structure modules by boundary (e.g., `backend/database/`, `backend/orders/`).
3. Define global settings in `resources.yaml` (set `prefix`, `tags`, `python`, `import`).
4. Ensure `.gitignore` ignores `**/common/` and `**/prismarine_clients/`.

### 2. Adding a Resource (Implement-Validate-Test Cycle)
1. Add local resource definitions in the target module's `easysam.yaml`.
2. **Schema Validation Gate**: Run `uv run easysam --environment dev inspect schema .` to validate YAML schema.
3. Write minimal Lambda handler code alongside the module's `easysam.yaml`.
4. Write unit tests in `tests/` using `pytest`.

### 3. Deployment Pipeline & Safety
1. **Cloud Verification Gate**: Run `uv run easysam --environment dev --aws-profile <profile> inspect cloud .` to verify external ARNs and roles.
2. **Template Preview**: Run `uv run easysam --environment dev generate .` to inspect generated templates and generate Prismarine clients automatically. (**Do NOT edit `template.yml` directly or run standalone `prismarine generate-client`**).
3. **Deploy**: Run `uv run easysam --environment dev --aws-profile <profile> deploy .`.
4. **Stuck Deployment Safety**: If deployment fails or hangs 2+ times, **STOP retrying** and report CloudFormation stack status to the user.

## EasySAM YAML Syntax Rules

### 1. Resource References
- Refer to local DynamoDB tables and S3 buckets by bare name strings (`MyTable`, `my-bucket`). **Do NOT use `!Ref`**.

### 2. Environment Variables
- `envvars` MUST be defined under `resources:`, NOT as a sibling of `resources:` under `lambda:`.
- **SSM Parameters**: Use `{{resolve:ssm:/path/to/param}}`. **Do NOT use `!Param`**.

### 3. HTTP Integrations & Greedy Routes
- Use `integration:` (not `api:`). Ensure each HTTP Lambda has a unique path prefix.
- **FastAPI / Framework Lambdas**: Always specify `greedy: true`.

```yaml
lambda:
  name: api-handler
  integration:
    path: /api/v1
    greedy: true      # Mandatory for FastAPI to handle sub-paths
    open: true
```

## Reference Material
- **Examples Index**: See [references/examples.md](references/examples.md) for a complete mapping of all 18 example projects under `example/` in the `easysam` repository.
- **Resource Recipes & Patterns**: See [references/patterns.md](references/patterns.md) for full YAML recipes across all 14 supported resource types (FastAPI greedy routes, OpenSearch Serverless, Lambda Function URLs, Kinesis Streams, Custom Layers, Custom Authorizers, IoT MQTT, Prismarine vs DynamoAccess, DynamoDB, S3, SQS, SNS, Poller).
- **Troubleshooting**: See [references/troubleshooting.md](references/troubleshooting.md) for schema, cloud, stack lock, and template resolution error fixes.
- **CI/CD Pipeline**: Use [assets/publish.yml](assets/publish.yml) for GitHub Actions OIDC deployment.