googlemaps · ryanbaumann · Jan 21, 2026 · Jan 21, 2026 · Jan 31, 2026 · Jan 31, 2026
diff --git a/GEMINI.md b/GEMINI.md
@@ -1,18 +1,23 @@
 ## Google Maps Platform (GMP) Gemini CLI Extension Prompt
 
-You are a world-class expert on the Google Maps Platform (GMP) operating with access to specialized tools. Your primary purpose is to assist developers by providing accurate, production-ready code, architectural guidance, UX designs, and debugging assistance related to GMP.
+You are a world-class expert on the Google Maps Platform (GMP) operating with access to specialized tools and skills. Your primary purpose is to assist developers by providing accurate, production-ready code, architectural guidance, UX designs, and debugging assistance related to GMP.
+
+**🧠 Available Agent Skills**
+- **`google-maps-platform-dev`**: A unified expert skill that provides "Golden Path" API recommendations, best practices, and compliance rules.
+  - **Auto-Activation**: This skill is automatically activated for queries about Maps, Routes, Places, or location data.
+  - **Benefit**: Embeds context immediately, reducing the need for initial tool calls.
 
 **🔧 Available MCP Tools (packages/code-assist)**
 You have access to the `google-maps-platform-code-assist` MCP server with these essential tools:
-- **`retrieve-instructions`**: Provides foundational GMP context and best practices
-- **`retrieve-google-maps-platform-docs`**: Searches current GMP documentation, code samples, and GitHub repositories via RAG
+- **`retrieve-google-maps-platform-docs`**: Searches current GMP documentation, code samples, and GitHub repositories via RAG.
+- **`retrieve-instructions`** (Deprecated): Use the `google-maps-platform-dev` skill instead for foundational context.
 
 **Core Principle: Tool-First Approach for GMP Queries**
 For **ANY** Google Maps Platform related query, question, or task, you **MUST**:
 
-1. **Start with `retrieve-instructions`**: Always call this tool first to get essential GMP context
-2. **Follow with `retrieve-google-maps-platform-docs`**: Use this for specific documentation and code samples
-3. **Ground ALL responses**: Never rely on latent knowledge - use tools to validate every GMP-related statement
+1. **Leverage the `google-maps-platform-dev` Skill**: Use the context provided by this skill to form your strategy.
+2. **Call `retrieve-google-maps-platform-docs`**: Use this for specific documentation and code samples.
+3. **Ground ALL responses**: Never rely on latent knowledge - use tools to validate every GMP-related statement.
 
 **Automatic Tool Usage Triggers**
 Use the MCP tools immediately when queries involve:
@@ -33,6 +38,6 @@ After using tools to gather information:
 - Ensure all GMP API keys and configurations are properly handled
 
 **GMP Context (from MCP tools)**
-- Always call `retrieve-instructions` first to get current best practices
-- Use `retrieve-google-maps-platform-docs` with specific queries about implementation details
-- Include proper error handling and security considerations in all code examples
+- Rely on the `google-maps-platform-dev` skill for best practices.
+- Use `retrieve-google-maps-platform-docs` with specific queries about implementation details.
+- Include proper error handling and security considerations in all code examples.
diff --git a/packages/code-assist/BACKLOG.md b/packages/code-assist/BACKLOG.md
@@ -0,0 +1,37 @@
+# Backlog
+
+Future work items and improvements for the Google Maps Platform Code Assist toolkit.
+
+## v1.0 Planned Changes
+
+### Tool Deprecation
+
+- [ ] **Remove `retrieve-instructions` tool** - The `retrieve-instructions` tool is deprecated in favor of the Agent Skill. For v1.0, this tool should be fully removed once the skill has been widely adopted and backward compatibility is no longer needed.
+  - **Rationale**: The Agent Skill (AgentSkills.io spec) embeds context directly into skill-aware agents, eliminating the need for an extra tool call before each query.
+  - **Migration Path**: Users should install the `google-maps-platform` skill from the `skills/` directory.
+  - **Tracking**: Monitor skill adoption through npm package downloads and skill registry listings.
+
+### MCP Server Updates
+
+- [ ] **Update `retrieve-google-maps-platform-docs` description** - Remove references to requiring `retrieve-instructions` first.
+- [ ] **Simplify tool registration** - If `retrieve-instructions` is removed, simplify the tool registration logic.
+
+## Future Considerations
+
+### v0.2 (Post-Skill Release)
+
+- [ ] Add `scripts/` directory to skill for automated API key validation
+- [ ] Create skill-specific prompts for different use cases (mobile, web, enterprise)
+
+### v0.3+
+
+- [ ] Explore interactive skill commands (e.g., `/gmp-help` style)
+- [ ] Add skill versioning support for multiple versions per tool
+- [ ] Investigate dynamic skill updates (hot-reload without agent restart)
+- [ ] Skill composition with other skills (e.g., Firebase skill)
+
+## Completed
+
+- [x] Create Agent Skill following AgentSkills.io specification (v0.x)
+- [x] Bundle skill with npm package
+- [x] Document skill installation in README
diff --git a/packages/code-assist/CHANGELOG.md b/packages/code-assist/CHANGELOG.md
@@ -2,6 +2,22 @@
 
 All notable changes to this project will be documented in this file.
 
+## [Unreleased]
+
+### ✨ Features
+
+*   **Agent Skill (AgentSkills.io):** Added a Google Maps Platform Agent Skill following the [AgentSkills.io](https://agentskills.io) specification. The skill embeds foundational context directly into skill-aware agents, reducing latency by eliminating the need for an extra `retrieve-instructions` tool call before each query.
+    *   `skills/google-maps-platform/SKILL.md` - Core instructions with API selection guides, best practices, and production readiness checklist
+    *   `skills/google-maps-platform/references/code-examples.md` - Platform-specific examples for Web, Android, iOS, and Flutter with proper attribution IDs
+    *   `skills/google-maps-platform/references/decision-trees.md` - API selection flowcharts for Maps, Places, Routes, and Data Visualization
+    *   `skills/google-maps-platform/references/eea-compliance.md` - EU Digital Markets Act requirements
+    *   `skills/google-maps-platform/references/attribution.md` - Attribution ID integration guide
+*   **npm Package Update:** Skills directory is now bundled with the npm package for easy distribution.
+
+### 📚 Documentation
+
+*   Added Agent Skill section to `README.md` with installation instructions for Claude Code, Cursor, Windsurf, and other skill-aware agents.
+
 ## [0.1.7] - 2025-08-28
 
 ### ✨ Features

diff --git a/packages/code-assist/README.md b/packages/code-assist/README.md
@@ -59,6 +59,81 @@ The MCP server exposes the following tools for AI clients:
 
 -----
 
+<!-- [START maps_AgentSkill] -->
+## Agent Skill (Optional)
+
+This package includes the **Google Maps Platform Developer Skill** (`google-maps-platform-dev`), a unified and optimized skill following the [AgentSkills.io](https://agentskills.io) specification. It embeds "Golden Path" best practices, API decision trees, and compliance rules directly into your agent.
+
+### Capabilities (In Scope)
+
+The skill is designed to handle the full development lifecycle for Google Maps Platform:
+
+*   **API Selection**: Automatically selects the right API (e.g., Places API (New) vs. Places UI Kit) based on cost, performance, and compliance (EEA).
+*   **"Golden Path" Defaults**: Enforces modern, stable defaults like Vector Maps, Advanced Markers, and Data-driven Styling.
+*   **Implementation Patterns**: Provides production-ready code patterns for React, Android (Compose), iOS (SwiftUI), and Flutter.
+*   **Compliance & Licensing**: Automatically handles attribution requirements and EEA (Digital Markets Act) compliance checks.
+*   **Troubleshooting**: Diagnoses common issues like API key restrictions and quota limits.
+
+### Skill Installation
+
+The skill is located in the `skills/google-maps-platform-dev/` directory.
+
+#### Gemini CLI - Local Clone (Recommended)
+
+```bash
+# From the repo root
+gemini skills install ./packages/code-assist/skills/google-maps-platform-dev
+```
+
+#### Gemini CLI - From GitHub
+
+```bash
+# Install to user scope
+gemini skills install https://github.com/googlemaps/platform-ai.git \
+  --path packages/code-assist/skills/google-maps-platform-dev
+```
+
+#### npm + Gemini CLI
+
+```bash
+# Install the npm package
+npm install @googlemaps/code-assist-mcp
+
+# Install skill from node_modules
+gemini skills install ./node_modules/@googlemaps/code-assist-mcp/skills/google-maps-platform-dev
+```
+
+#### Claude Code
+
+```bash
+cp -r $(npm root -g)/@googlemaps/code-assist-mcp/skills/google-maps-platform-dev ~/.claude/skills/
+```
+
+#### Cursor / Windsurf / VS Code
+
+Add to your workspace's `.cursor/skills/` or `.windsurf/skills/` directory:
+```bash
+cp -r node_modules/@googlemaps/code-assist-mcp/skills/google-maps-platform-dev .cursor/skills/
+```
+
+### Skill Contents
+
+| File | Description |
+|------|-------------|
+| `SKILL.md` | Core instructions, "Golden Path" rules, and best practices |
+| `references/products-overview.md` | Full hierarchy of Maps, Routes, Places, and Environment APIs |
+| `references/places-overview.md` | Decision guide for Places API (New) vs. Places UI Kit |
+| `references/routes-navigation.md` | Decision guide for Routes API vs. Navigation SDK |
+| `references/environment-apis.md` | Guide for Air Quality, Pollen, and Solar APIs |
+| `resources/getting-started.md` | "DIRT Simple" API key setup and troubleshooting |
+| `resources/platform-*.md` | Implementation patterns for React, Android, iOS, etc. |
+
+> **Note:** The skill works best when combined with the MCP server (`retrieve-google-maps-platform-docs`), which provides real-time documentation search.
+
+<!-- [END maps_AgentSkill] -->
+
+-----
+
 <!-- [START maps_Transports] -->
 
 ## Supported MCP Transports

diff --git a/packages/code-assist/package.json b/packages/code-assist/package.json
@@ -8,7 +8,8 @@
     "code-assist-mcp": "dist/index.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "skills"
   ],
   "scripts": {
     "clean": "rm -rf dist",