agent-plugins

# Agent Plugins for AWS

> **Note:** `CLAUDE.md` is a symlink to this file. Only edit `AGENTS.md` — changes apply to both automatically.

## TL;DR Pitch

This repository supports **plugins** - bundles of skills, MCP servers, and agent configurations that extend capabilities. The `awslabs/agent-plugins` marketplace includes plugins like `deploy-on-aws` (architecture recommendations, cost estimates, and working IaC), `amazon-location-service` (maps, geocoding, routing, and geospatial features), and `databases-on-aws` (database guidance for the AWS portfolio, starting with Aurora DSQL).

## Core Concepts

### Plugins vs Skills vs MCP Servers

| Concept         | What It Is                                                                         | Example                                   |
| --------------- | ---------------------------------------------------------------------------------- | ----------------------------------------- |
| **Plugin**      | A distributable bundle (skills + MCP servers + agents)                             | `deploy-on-aws`                           |
| **Skill**       | Instructions that auto-trigger based on user intent (YAML frontmatter description) | "deploy to AWS" triggers the deploy skill |
| **MCP Server**  | External tool integration via Model Context Protocol                               | `awspricing` for cost estimates           |
| **Marketplace** | Registry of plugins users can install                                              | `awslabs/agent-plugins`                   |

### Key Design Decision: Skills Auto-Trigger

Skills are **NOT** slash commands. The agent determines when to use a skill based on the `description` field in YAML frontmatter. If user says "host this on AWS", the agent matches that intent to the deploy skill's description and invokes it.

## Directory Structure

```
agent-plugins/
├── .claude-plugin/
│   └── marketplace.json          # Marketplace registry
├── .github/
│   ├── workflows/                # CI (build, lint, security, etc.)
│   ├── ISSUE_TEMPLATE/
│   └── ...
├── docs/                         # Role-specific guides
│   ├── DESIGN_GUIDELINES.md      # Plugin design best practices
│   ├── DEVELOPMENT_GUIDE.md      # Contributor setup and workflow
│   ├── MAINTAINERS_GUIDE.md      # Reviewer/maintainer processes
│   └── TROUBLESHOOTING.md        # Plugin troubleshooting
├── plugins/
│   ├── deploy-on-aws/
│   │   ├── .claude-plugin/
│   │   │   └── plugin.json       # Plugin manifest
│   │   ├── .mcp.json             # MCP server definitions
│   │   └── skills/
│   │       └── deploy/
│   │           ├── SKILL.md     # Main skill (auto-triggers)
│   │           └── references/
│   │               ├── defaults.md
│   │               ├── cost-estimation.md
│   │               └── security.md
│   ├── amazon-location-service/
│   │   ├── .claude-plugin/
│   │   │   └── plugin.json
│   │   ├── .mcp.json
│   │   └── skills/
│   │       └── amazon-location-service/
│   │           ├── SKILL.md
│   │           └── references/
│   ├── databases-on-aws/
│   │   ├── .claude-plugin/
│   │   │   └── plugin.json
│   │   ├── .mcp.json
│   │   ├── hooks/
│   │   │   └── hooks.json
│   │   ├── scripts/
│   │   └── skills/
│   │       └── dsql/
│   │           ├── SKILL.md
│   │           ├── mcp/
│   │           └── references/
├── schemas/                      # JSON schemas for manifests
│   ├── marketplace.schema.json
│   ├── plugin.schema.json
│   ├── mcp.schema.json
│   └── skill-frontmatter.schema.json
├── tools/                        # Lint, validation, and eval scripts
│   ├── evals/                    # Eval suites for plugins, kept separate from plugin clients
│   │   └── databases-on-aws/
│   │       ├── README.md
│   │       └── dsql/
│   │           ├── evals.json
│   │           ├── trigger_evals.json
│   │           ├── query_explainability_evals.json
│   │           ├── safe_query_evals.json
│   │           └── scripts/
│   │               └── run_functional_evals.py
│   ├── validate-cross-refs.cjs
│   └── ...
├── mise.toml                     # Tool versions and tasks
├── dprint.json
├── .markdownlint-cli2.yaml
├── .pre-commit-config.yaml
└── README.md
```

## MCP Servers

### deploy-on-aws

| Server         | Type  | Purpose                                           |
| -------------- | ----- | ------------------------------------------------- |
| `awsknowledge` | HTTP  | AWS documentation, architecture guidance          |
| `awspricing`   | stdio | Real-time cost estimates                          |
| `awsiac`       | stdio | IaC best practices (CDK/CloudFormation/Terraform) |

### amazon-location-service

| Server    | Type  | Purpose                                |
| --------- | ----- | -------------------------------------- |
| `aws-mcp` | stdio | AWS documentation and service guidance |

### databases-on-aws

| Server         | Type  | Purpose                                                                          |
| -------------- | ----- | -------------------------------------------------------------------------------- |
| `awsknowledge` | HTTP  | AWS documentation, architecture guidance, and best practices                     |
| `aurora-dsql`  | stdio | Direct database operations — queries, schema, transactions (disabled by default) |

## Workflow: Deploy Skill

1. **Analyze** - Scan codebase for framework, database, dependencies
2. **Recommend** - Select AWS services with concise rationale
3. **Estimate** - Show monthly cost before proceeding (always!)
4. **Generate** - Write IaC code (CDK by default)
5. **Deploy** - Execute with user confirmation

## Default Service Selections

- Web frameworks → Fargate + ALB (not Lambda - cold starts break WSGI frameworks)
- Static sites/SPAs → Amplify Hosting (not S3+CloudFront - too much config)
- Databases → Aurora Serverless v2 (scales to near-zero in dev)
- IaC → CDK TypeScript (most expressive, best IDE support)

Default to **dev sizing** unless user says "production".

## Development commands (mise)

The project uses [mise](https://mise.jdx.dev) for tool versions and tasks. Ensure mise is installed, then from the repo root:

```bash
# Install tools (Node, markdownlint, pre-commit, security scanners, etc.)
mise install

# Run common tasks
mise run pre-commit    # Pre-commit hooks on all files
mise run fmt           # Format with dprint
mise run fmt:check     # Check formatting (CI)
mise run lint:md       # Lint Markdown (incl. SKILL.md)
mise run lint:md:fix   # Lint Markdown with auto-fix
mise run lint:manifests   # Validate JSON manifests (marketplace, plugin, MCP)
mise run lint:cross-refs  # Validate cross-references between manifests
mise run lint          # All linters
mise run test          # Run unit tests (pytest for Python; npm/jest when a package.json defines tests)
mise run security      # All security scans (Bandit, SemGrep, Gitleaks, Checkov, Grype, zizmor)
mise run build         # Full build: lint + fmt:check + validate + test + security
```

See `mise.toml` for the full task list and tool versions.

## Plugin commands (Claude)

Project-level plugin settings are in `.claude/settings.json` (`enabledPlugins`).
Contributors must first add the marketplace before these take effect.

```bash
# Add marketplace
/plugin marketplace add awslabs/agent-plugins

# Install plugin
/plugin install deploy-on-aws@agent-plugins-for-aws

# Test locally
claude --plugin-dir ./plugins/deploy-on-aws
```

## Git Worktree Workflow

ALWAYS use git worktrees for new work. The main worktree stays on its current branch and is never switched. Each piece of work gets its own worktree under `.tmp/`, branching off the latest `origin/main`. This enables multiple agents to work in parallel without conflicts.

```bash
# Fast-forward main first, then branch new work off the latest remote
git pull --ff-only origin main
git worktree add .tmp/<short-name> -b <branch-name> origin/main

# Create a worktree for an existing branch
git worktree add .tmp/<short-name> <branch-name>

# List worktrees
git worktree list

# Remove a worktree after the branch is merged
git worktree remove .tmp/<short-name>
```

All worktrees live under `.tmp/` (already in `.gitignore`).

## Boundaries

- ALWAYS use `git worktree add .tmp/<name>` for new work. NEVER switch branches in the main worktree.
- ONLY fast-forward `main` (`git pull --ff-only`); never commit, merge, or rebase it locally.
- ALWAYS Use mise commands to interact with the codebase. If a command is not available, add it.
- NEVER add new dependencies without asking first.
- ALWAYS run a full build when done with a task, this is to ensure all required files are generated before commit.
- ALWAYS Ask first before modifying existing files in a major way.