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

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) and amazon-location-service (maps, geocoding, routing, and geospatial features).

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.

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/
├── schemas/                      # JSON schemas for manifests
│   ├── marketplace.schema.json
│   ├── plugin.schema.json
│   ├── mcp.schema.json
│   └── skill-frontmatter.schema.json
├── tools/                        # Lint/validation scripts
│   ├── validate-cross-refs.cjs
│   └── ...
├── mise.toml                     # Tool versions and tasks
├── dprint.json
├── .markdownlint-cli2.yaml
├── .pre-commit-config.yaml
└── README.md

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

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

See .claude/docs/ for Claude Code plugin system reference:

• plugin_overview.md - Creating plugins
• plugin_marketplace_distribution.md - Marketplace distribution
• plugin_reference.md - Complete technical reference
• skills_docs.md - Skill authoring guide

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.

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

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).

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