RFC: Amazon Location Service plugin

[cgalvan]

Is this related to an existing feature request or issue?

No response

Summary

This RFC proposes adding an amazon-location-service plugin to the agent-plugins-for-aws marketplace. The plugin provides an agent skill that guides developers through integrating geospatial features into their applications using Amazon Location Service APIs, covering maps, places search, geocoding, routing, address verification, and authentication setup.

Use case

Developers building location-aware applications on AWS currently need to navigate multiple API references, SDK documentation, and best practices guides across Amazon Location Service's five service areas (Places, Maps, Routes, Geofences, and Trackers). Common pitfalls include using wrong API action names in permissions, incorrect map initialization patterns, and choosing suboptimal APIs for their use case.

This plugin encodes that domain expertise into a skill that auto-triggers when developers express location-related intent (e.g., "add a map", "geocode an address", "calculate a route"). It provides API selection guidance, authentication setup, SDK integration patterns, and reference documentation for specific implementation tasks.

Proposal

The plugin follows the established plugin structure:

plugins/amazon-location-service/
├── .claude-plugin/
│   └── plugin.json
├── .mcp.json                          # aws-mcp server for documentation access
└── skills/
    └── amazon-location-service/
        ├── SKILL.md                   # Core skill with API guidance and common mistakes
        └── references/
            ├── address-input.md       # Address autocomplete form patterns
            ├── address-verification.md # Address validation before persistence
            ├── calculate-routes.md    # Route calculation and map display
            ├── dynamic-map.md         # MapLibre integration with Amazon Location tiles
            ├── places-search.md       # Text search, nearby search, suggestions
            └── web-javascript.md      # Browser SDK integration patterns

The skill covers:

• API selection guidance (which API to use for which use case)
• Common mistakes and how to avoid them (wrong display fields, incorrect map init, mixed resource types)
• Authentication patterns (API keys for client-side, IAM for server-side)
• Preference for resourceless operations over resource-based ones
• Preference for the bundled JavaScript client (@aws/amazon-location-client) for web development
• Reference files for progressive disclosure of implementation details

The plugin integrates with the AWS MCP Server for access to live documentation and API references.

Changes outside the plugin directory include registering it in marketplace.json, updating README.md, AGENTS.md, MAINTAINERS_GUIDE.md, DESIGN_GUIDELINES.md, and .github/copilot-instructions.md to reflect the new plugin.

Out of scope

• Mobile-native SDK integration (Android/iOS) — the current references focus on web/JavaScript
• Geofence and Tracker implementation references (the skill mentions these APIs but detailed reference files are not included in v1.0)

Potential challenges

• Skill size: The SKILL.md is comprehensive to cover the breadth of Amazon Location Service APIs. Reference files use progressive disclosure to keep initial context load manageable, but the main skill file should be monitored for token usage.
• API evolution: Amazon Location Service APIs may change or add new features. The skill and references will need periodic updates to stay current.
• Web-focused: The current references are primarily focused on JavaScript/web integration. Mobile and server-side patterns may need additional reference files in future versions.

Dependencies and Integrations

• AWS MCP Server (aws-mcp): Provides access to AWS documentation and service guidance at runtime. Configured in .mcp.json.
• MapLibre GL JS: Referenced as the recommended map rendering library for dynamic maps. Not a plugin dependency, but a recommendation made to users.
• @aws/amazon-location-client: The bundled JavaScript client recommended for web development. Not a plugin dependency, but a recommendation made to users.

Alternative solutions

- **Documentation only**: Developers could rely on the Amazon Location Service Developer Guide and API Reference directly. However, this requires navigating multiple docs and doesn't provide the opinionated API selection guidance or common mistake prevention that the skill offers.
- **MCP server only**: An MCP server providing direct Amazon Location API access could be built instead. However, the skill-based approach is more appropriate here since the value is in guidance and best practices rather than API execution.