Skip to content

AGENTS.md

Latest commit

 

History

History
213 lines (170 loc) · 9.41 KB

AGENTS.md

File metadata and controls

213 lines (170 loc) · 9.41 KB

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), databases-on-aws (database guidance for the AWS portfolio, starting with Aurora DSQL), and migration-to-aws (GCP-to-AWS migration with resource discovery, architecture mapping, and cost analysis).

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/
│   └── migration-to-aws/
│       ├── .claude-plugin/
│       │   └── plugin.json
│       ├── .mcp.json
│       └── skills/
│           └── gcp-to-aws/
│               ├── SKILL.md
│               └── 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
│   │       ├── evals.json
│   │       ├── trigger_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)

migration-to-aws

Server Type Purpose
awsknowledge HTTP AWS documentation and architecture guidance
awspricing stdio Real-time AWS service pricing for cost analysis

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 for tool versions and tasks. Ensure mise is installed, then from the repo root:

# 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 security      # All security scans (Bandit, SemGrep, Gitleaks, Checkov, Grype)
mise run build         # Full build: lint + fmt:check + 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.

# 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 current branch. This enables multiple agents to work in parallel without conflicts.

# Create a worktree for new work (branches off current branch)
git worktree add .tmp/<short-name> -b <branch-name>

# 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.
  • 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.