feat: split plugin into focused map skills

.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "mcp-google-map",
   "version": "0.0.64",
-  "description": "Use Google Maps-backed place search, routing, geocoding, weather, air quality, and geographic analysis through a standalone CLI.",
+  "description": "Use focused Skills for Google Maps place research, travel planning, and local SEO through a standalone CLI.",
   "author": {
     "name": "CabLate",
     "url": "https://github.com/cablate"
@@ -20,8 +20,8 @@
   "skills": "./skills/",
   "interface": {
     "displayName": "Google Maps CLI",
-    "shortDescription": "Geospatial research and planning through a standalone CLI.",
-    "longDescription": "Guide an AI agent to use the @cablate/mcp-google-map exec CLI for place discovery, routing, geocoding, travel planning, local SEO, weather, air quality, and other geographic workflows. No MCP connection is required.",
+    "shortDescription": "Focused maps, travel planning, and local SEO workflows through a standalone CLI.",
+    "longDescription": "Three focused Skills guide an AI agent to use the @cablate/mcp-google-map CLI for general geospatial research, evidence-backed travel planning, and local SEO analysis. No MCP connection is required.",
     "developerName": "CabLate",
     "category": "Productivity",
     "capabilities": [
@@ -30,8 +30,8 @@
     "websiteURL": "https://github.com/cablate/mcp-google-map",
     "defaultPrompt": [
       "Find and compare places for my trip.",
-      "Plan an efficient route between these stops.",
-      "Research what is near this location."
+      "Plan a practical multi-day itinerary with checked routes.",
+      "Analyze this business's local Google Maps visibility."
     ]
   }
 }

.github/workflows/ci.yml

@@ -35,6 +35,6 @@ jobs:
           node-version: 18
 
       - run: npm ci
-      - run: python3 scripts/package-skill.py --check
+      - run: python3 scripts/validate-skills.py
       - run: npm run build
       - run: npm run test:unit

CHANGELOG.md

@@ -105,6 +105,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+- Split the Skill-only plugin into focused general maps, travel planning, and local SEO Skills with shared setup and attribution guidance.
+- Add a non-billable `doctor` readiness check and opt-in `doctor --live` checks for Geocoding, Places API (New), and Routes API.
+
 ## [0.0.48]
 
 - feat: batch keyword scanning for local rank tracker (#68)

CLAUDE.md

@@ -16,8 +16,8 @@
 | 3 | `src/cli.ts` | EXEC_TOOLS 列表 + switch case |
 | 4 | `tests/smoke.test.ts` | expectedTools 陣列 + tool count assertions |
 | 5 | `README.md` | tool 數量（header、vs Grounding Lite 表、Server Info、exec mode）+ Available Tools 表格 + Project Structure |
-| 6 | `skills/google-maps/SKILL.md` | Tool Map 表格 |
-| 7 | `skills/google-maps/references/tools-api.md` | 參數文件 + chaining patterns |
+| 6 | `skills/*/SKILL.md` | 對應使用者目標、工具選擇與 Skill 邊界 |
+| 7 | `skills/google-maps/references/tools-api.md` | 參數文件 + chaining patterns；專用流程同步更新其 Skill reference |
 | 8 | `server.json` | description（如有提到 tool 數量） |
 | 9 | `package.json` | description（如有提到 tool 數量） |
 

README.md

@@ -21,7 +21,7 @@
 
 - **18 tools** — 14 atomic + 4 composite (explore-area, plan-route, compare-places, local-rank-tracker)
 - **3 modes** — stdio, StreamableHTTP, standalone exec CLI
-- **Agent Skill** — built-in skill definition teaches AI how to chain geo tools ([`skills/google-maps/`](./skills/google-maps/))
+- **3 Agent Skills** — focused workflows for general maps, travel planning, and local SEO ([`skills/`](./skills/))
 
 ### vs Google Grounding Lite
 
@@ -89,7 +89,7 @@ All tools are annotated with `readOnlyHint: true` and `destructiveHint: false` 
 
 ## Installation
 
-### Codex Plugin (Agent Skill, no MCP required)
+### Codex Plugin (3 Agent Skills, no MCP required)
 
 Install the CabLate marketplace, then install the Skill-only plugin:
 
@@ -98,7 +98,13 @@ codex plugin marketplace add cablate/mcp-google-map --ref main
 codex plugin add mcp-google-map@cablate
 ```
 
-Set `GOOGLE_MAPS_API_KEY` in the environment available to Codex, make sure Node.js 18+ and `npx` are installed, then start a new conversation. The plugin teaches the agent to run `npx -y @cablate/mcp-google-map exec ...` directly. It does not register or start an MCP server; the MCP setup below remains an independent option.
+Set `GOOGLE_MAPS_API_KEY` in the environment available to Codex, make sure Node.js 18+ and `npx` are installed, then start a new conversation. The plugin discovers three focused Skills and teaches the agent to run `npx -y @cablate/mcp-google-map exec ...` directly. It does not register or start an MCP server; the MCP setup below remains an independent option.
+
+At runtime, Codex sees the name and description of each Skill and loads the full instructions only when the request matches:
+
+- `google-maps` — place search, geocoding, routes, neighborhood and environmental facts
+- `google-maps-travel-planning` — day trips and multi-day itineraries
+- `google-maps-local-seo` — Google Business Profile visibility and geographic rank analysis
 
 ### Method 1: stdio (Recommended for most clients)
 
@@ -169,17 +175,17 @@ npx @cablate/mcp-google-map exec geocode '{"address":"Tokyo Tower"}'
 npx @cablate/mcp-google-map exec search-places '{"query":"ramen in Tokyo"}'
 ```
 
-All 18 tools available: `geocode`, `reverse-geocode`, `search-nearby`, `search-places`, `place-details`, `directions`, `distance-matrix`, `elevation`, `timezone`, `weather`, `air-quality`, `static-map`, `batch-geocode-tool`, `search-along-route`, `explore-area`, `plan-route`, `compare-places`, `local-rank-tracker`. See [`skills/google-maps/`](./skills/google-maps/) for the agent skill definition and full parameter docs.
+All 18 tools available: `geocode`, `reverse-geocode`, `search-nearby`, `search-places`, `place-details`, `directions`, `distance-matrix`, `elevation`, `timezone`, `weather`, `air-quality`, `static-map`, `batch-geocode-tool`, `search-along-route`, `explore-area`, `plan-route`, `compare-places`, `local-rank-tracker`. See [`skills/`](./skills/) for the Skill definitions and full parameter docs.
 
 To use the **Agent Skill without MCP**:
 
-1. Install the entire [`skills/google-maps/`](./skills/google-maps/) folder in your agent's Skills directory, following that client's instructions. Keep `SKILL.md` and `references/` together. Clients that support `.skill` imports can use the bundled [`SKILL.skill`](./skills/google-maps/SKILL.skill) archive instead. Installing the npm package alone does not register a Skill with an agent.
+1. Install the entire [`skills/`](./skills/) tree in your agent's Skills directory, following that client's instructions. Keep all three Skill folders and `_shared/` together so cross-Skill references continue to resolve. Installing the npm package alone does not register a Skill unless the package is installed through its plugin marketplace.
 2. Make Node.js 18+ and `npx` available to the agent, and set `GOOGLE_MAPS_API_KEY` in its environment. Prefer the environment variable to `--apikey`, which can expose a key in shell history or process listings.
 3. Ask the agent a location question. The Skill guides it to call the standalone CLI, for example `npx -y @cablate/mcp-google-map exec geocode '{"address":"Tokyo Tower"}'`. No MCP server or MCP client configuration is needed.
 
-You can verify the CLI is available with `npx -y @cablate/mcp-google-map exec --help` before making a billable API call.
+Run `npx -y @cablate/mcp-google-map doctor` for a non-billable local readiness check. After informing the user that test requests may incur Google Maps Platform charges, `doctor --live` can verify Geocoding, Places API (New), and Routes API independently.
 
-For a reproducible no-MCP walkthrough, see the [Agent Skill demo](./examples/agent-skill-demo.md). If your agent or app displays Places reviews, photos, or AI summaries, follow the [content attribution and storage guidance](./skills/google-maps/references/content-attribution.md); the tool preserves source/disclosure metadata but does not render a compliant UI for you.
+For a reproducible no-MCP walkthrough, see the [Agent Skill demo](./examples/agent-skill-demo.md). If your agent or app displays Places reviews, photos, or AI summaries, follow the [content attribution and storage guidance](./skills/_shared/content-attribution.md); the tool preserves source/disclosure metadata but does not render a compliant UI for you.
 
 ### Batch Geocode
 
@@ -301,13 +307,18 @@ src/
 tests/
 └── smoke.test.ts                 # Smoke + E2E test suite
 skills/
-└── google-maps/                  # Public Agent Skill — standalone CLI workflows
-│   ├── SKILL.md                  # Tool map, recipes, invocation
-│   ├── SKILL.skill               # Importable archive of this Skill
-│   └── references/
-│       ├── tools-api.md          # Tool parameters + scenario recipes
-│       ├── travel-planning.md    # Travel planning methodology
-│       └── local-seo.md          # Local SEO / Google Business Profile ranking analysis
+├── google-maps/                  # General place, route, and environment workflow
+│   ├── SKILL.md
+│   └── references/tools-api.md   # Tool parameters + generic recipes
+├── google-maps-travel-planning/  # Day-trip and itinerary workflow
+│   ├── SKILL.md
+│   └── references/travel-planning.md
+├── google-maps-local-seo/        # Business visibility and grid-rank workflow
+│   ├── SKILL.md
+│   └── references/local-seo.md
+└── _shared/                      # On-demand resources used by all three Skills
+    ├── setup-and-diagnostics.md
+    └── content-attribution.md
 .agents/
 ├── plugins/marketplace.json      # CabLate marketplace catalog
 └── skills/project-docs/          # Maintainer-only development Skill

README.zh-TW.md

@@ -21,7 +21,7 @@
 
 - **18 個工具** — 14 個原子工具 + 4 個組合工具（explore-area、plan-route、compare-places、local-rank-tracker）
 - **3 種模式** — stdio、StreamableHTTP、獨立 exec CLI
-- **Agent Skill** — 內建技能定義，教 AI 如何串接地理工具（[`skills/google-maps/`](./skills/google-maps/)）
+- **3 個 Agent Skills** — 分別處理一般地圖、旅行規劃與 Local SEO（[`skills/`](./skills/)）
 
 ### vs Google Grounding Lite
 
@@ -89,7 +89,7 @@ npx @cablate/mcp-google-map --port 3000 --apikey "YOUR_API_KEY"
 
 ## 安裝
 
-### Codex Plugin（Agent Skill，不需要 MCP）
+### Codex Plugin（3 個 Agent Skills，不需要 MCP）
 
 先加入 CabLate marketplace，再安裝只包含 Skill 的 plugin：
 
@@ -98,7 +98,13 @@ codex plugin marketplace add cablate/mcp-google-map --ref main
 codex plugin add mcp-google-map@cablate
 ```
 
-請在 Codex 可讀取的環境中設定 `GOOGLE_MAPS_API_KEY`，並確認已安裝 Node.js 18+ 與 `npx`，然後開啟新對話。Plugin 會教代理直接執行 `npx -y @cablate/mcp-google-map exec ...`；它不會註冊或啟動 MCP server。下方的 MCP 設定仍是另一種獨立使用方式。
+請在 Codex 可讀取的環境中設定 `GOOGLE_MAPS_API_KEY`，並確認已安裝 Node.js 18+ 與 `npx`，然後開啟新對話。Plugin 會探索三個用途明確的 Skills，並教代理直接執行 `npx -y @cablate/mcp-google-map exec ...`；它不會註冊或啟動 MCP server。下方的 MCP 設定仍是另一種獨立使用方式。
+
+執行階段會先看到每個 Skill 的名稱與描述，只有請求符合時才載入完整指令：
+
+- `google-maps` — 地點搜尋、地址解析、路線、區域與環境資訊
+- `google-maps-travel-planning` — 單日與多日旅行行程
+- `google-maps-local-seo` — Google 商家檔案能見度與地理排名分析
 
 ### 方法一：stdio（大多數客戶端推薦）
 
@@ -169,17 +175,17 @@ npx @cablate/mcp-google-map exec geocode '{"address":"台北101"}'
 npx @cablate/mcp-google-map exec search-places '{"query":"東京拉麵"}'
 ```
 
-全部 18 個工具可用：`geocode`、`reverse-geocode`、`search-nearby`、`search-places`、`place-details`、`directions`、`distance-matrix`、`elevation`、`timezone`、`weather`、`air-quality`、`static-map`、`batch-geocode-tool`、`search-along-route`、`explore-area`、`plan-route`、`compare-places`、`local-rank-tracker`。完整參數文件見 [`skills/google-maps/`](./skills/google-maps/)。
+全部 18 個工具可用：`geocode`、`reverse-geocode`、`search-nearby`、`search-places`、`place-details`、`directions`、`distance-matrix`、`elevation`、`timezone`、`weather`、`air-quality`、`static-map`、`batch-geocode-tool`、`search-along-route`、`explore-area`、`plan-route`、`compare-places`、`local-rank-tracker`。Skill 定義與完整參數文件見 [`skills/`](./skills/)。
 
 若要**不透過 MCP、只用 Agent Skill**：
 
-1. 依你的代理工具說明，將整個 [`skills/google-maps/`](./skills/google-maps/) 資料夾安裝到它的 Skills 目錄；`SKILL.md` 與 `references/` 必須放在一起。支援匯入 `.skill` 的工具也可使用隨附的 [`SKILL.skill`](./skills/google-maps/SKILL.skill)。只安裝 npm 套件不會自動把 Skill 註冊到代理工具。
+1. 依你的代理工具說明，將整個 [`skills/`](./skills/) 目錄樹安裝到它的 Skills 目錄；三個 Skill 資料夾與 `_shared/` 必須放在一起，跨 Skill 參考才會正常解析。除非透過 Plugin Marketplace 安裝，否則只安裝 npm 套件不會自動把 Skill 註冊到代理工具。
 2. 讓代理工具可使用 Node.js 18+、`npx`，並在其環境設定 `GOOGLE_MAPS_API_KEY`。建議使用環境變數；`--apikey` 可能讓金鑰出現在 shell 歷史或程序清單。
 3. 直接向代理工具提問地點問題。Skill 會引導它呼叫獨立 CLI，例如 `npx -y @cablate/mcp-google-map exec geocode '{"address":"台北101"}'`；不必啟動 MCP server 或設定 MCP client。
 
-呼叫可能計費的 API 前，可先用 `npx -y @cablate/mcp-google-map exec --help` 確認 CLI 可用。
+先執行 `npx -y @cablate/mcp-google-map doctor`，即可在不呼叫 Google API、不產生 API 費用的情況下檢查本機準備狀態。告知使用者測試請求可能產生 Google Maps Platform 費用後，可用 `doctor --live` 分別驗證 Geocoding、Places API (New) 與 Routes API。
 
-完整的非 MCP 操作步驟見 [Agent Skill 示範](./examples/agent-skill-demo.md)。若代理工具或應用程式會呈現 Places 評論、照片或 AI 摘要，請遵照[內容署名與保存指引](./skills/google-maps/references/content-attribution.md)；工具會保留來源及揭露欄位，但不會替你的介面完成署名呈現。
+完整的非 MCP 操作步驟見 [Agent Skill 示範](./examples/agent-skill-demo.md)。若代理工具或應用程式會呈現 Places 評論、照片或 AI 摘要，請遵照[內容署名與保存指引](./skills/_shared/content-attribution.md)；工具會保留來源及揭露欄位，但不會替你的介面完成署名呈現。
 
 ### 批次地理編碼
 
@@ -298,13 +304,18 @@ src/
 tests/
 └── smoke.test.ts                 # Smoke + E2E 測試套件
 skills/
-└── google-maps/                  # 公開 Agent Skill — 獨立 CLI 工作流程
-│   ├── SKILL.md                  # 工具對照表、場景食譜、呼叫方式
-│   ├── SKILL.skill               # 可匯入的 Skill 封裝檔
-│   └── references/
-│       ├── tools-api.md          # 工具參數 + 場景食譜
-│       ├── travel-planning.md    # 旅行規劃方法論
-│       └── local-seo.md          # Local SEO / Google 商家排名分析
+├── google-maps/                  # 一般地點、路線與環境資訊工作流程
+│   ├── SKILL.md
+│   └── references/tools-api.md   # 工具參數 + 一般場景食譜
+├── google-maps-travel-planning/  # 單日與多日行程工作流程
+│   ├── SKILL.md
+│   └── references/travel-planning.md
+├── google-maps-local-seo/        # 商家能見度與地理排名工作流程
+│   ├── SKILL.md
+│   └── references/local-seo.md
+└── _shared/                      # 三個 Skills 按需載入的共用資源
+    ├── setup-and-diagnostics.md
+    └── content-attribution.md
 .agents/
 ├── plugins/marketplace.json      # CabLate marketplace 目錄
 └── skills/project-docs/          # 僅供維護者使用的開發 Skill

docs/backlog-and-strategy.md

@@ -13,7 +13,7 @@ This is a current maintenance and product roadmap, not a release-status ledger.
 
 - Keep Google Maps content display guidance aligned with the [Places API policies](https://developers.google.com/maps/documentation/places/web-service/policies), particularly attribution for reviews/photos, AI-summary disclosures, source links, and storage limits. The package is a data/tool layer; downstream applications still own their rendered UI, terms, and privacy notices.
 - Triage production dependency advisories by affected path and exploit preconditions, then update compatible versions and verify build, tests, and live API behavior. An audit count alone is not proof of an exploitable path.
-- Keep the packaged Agent Skill synchronized with its source using `python3 scripts/package-skill.py --check` in CI. Update its tool map and API reference whenever tools change.
+- Keep all packaged Agent Skills and shared references synchronized with source tools using `python3 scripts/validate-skills.py` in CI. Update the relevant workflow Skill and API reference whenever tools change.
 
 ## Deferred ideas