mapquest-agent-skills 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Avi Raju
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,156 @@
+# MapQuest Agent Skills
+
+**8 comprehensive Agent Skills** that teach AI assistants how to build fast, reliable, production-ready MapQuest applications. Covers geocoding, routing, static maps, search-ahead, web integration, key security, store locators, and real-time traffic data.
+
+## Quick Start
+
+Install all MapQuest Agent Skills:
+
+```bash
+npx add-skill definingAvi/mapquest-agent-skills
+```
+
+Install specific skills:
+
+```bash
+npx add-skill definingAvi/mapquest-agent-skills --skill mapquest-geocoding-patterns
+```
+
+List available skills:
+
+```bash
+npx add-skill definingAvi/mapquest-agent-skills --list
+```
+
+## What Are Agent Skills?
+
+Agent Skills are folders containing instructions and resources that AI assistants (like Claude Code, Cursor, GitHub Copilot) can discover and use to perform tasks more effectively. Unlike tools (which provide actions) or prompts (which provide workflows), skills provide **domain expertise** — the "know-how" that helps AI make informed decisions when working with MapQuest APIs.
+
+## Available Skills
+
+---
+
+### 📍 mapquest-geocoding-patterns
+**Address ↔ coordinate conversion using the MapQuest Geocoding API.**
+
+Covers forward geocoding, reverse geocoding, batch geocoding, quality codes, and response parsing. Teaches the AI to choose the right geocoding mode, handle partial/ambiguous addresses, and interpret `geocodeQuality` scores correctly.
+
+[View skill →](./skills/mapquest-geocoding-patterns/SKILL.md)
+
+---
+
+### 🗺️ mapquest-directions-routing
+**Turn-by-turn directions, route optimization, and multi-stop routing.**
+
+Covers the Directions API, route types (fastest/shortest/pedestrian/bicycle), narrative maneuvers, distance/time formatting, and common mistakes like ignoring `statusCode` or mixing up lat/lng order.
+
+[View skill →](./skills/mapquest-directions-routing/SKILL.md)
+
+---
+
+### 🖼️ mapquest-static-maps
+**Generating and embedding static map images via the Static Map API.**
+
+Covers center/zoom, markers, shape overlays, image sizing, map types (map/sat/hyb/light/dark), and URL construction patterns. Includes when to use static vs. interactive maps.
+
+[View skill →](./skills/mapquest-static-maps/SKILL.md)
+
+---
+
+### 🔍 mapquest-search-ahead
+**Typeahead/autocomplete using the Search Ahead API.**
+
+Covers debouncing, result categories, geographic bias, collection types (address, adminArea, airport, category, franchise, poi), and how to chain Search Ahead with Geocoding for full address resolution.
+
+[View skill →](./skills/mapquest-search-ahead/SKILL.md)
+
+---
+
+### 🌐 mapquest-web-integration
+**Integrating the MapQuest JavaScript SDK (Leaflet-based) into web applications.**
+
+Covers SDK loading, map initialization, tile layers, markers, popups, event handling, and framework integration patterns for React, Vue, and plain HTML/JS.
+
+[View skill →](./skills/mapquest-web-integration/SKILL.md)
+
+---
+
+### 🔐 mapquest-key-security
+**Best practices for handling MapQuest API keys securely.**
+
+Covers environment variable storage, referrer restrictions in the MapQuest developer portal, server-side proxying, key rotation, and what to do when a key is exposed.
+
+[View skill →](./skills/mapquest-key-security/SKILL.md)
+
+---
+
+### 🏪 mapquest-store-locator
+**Building store locators and POI finders with MapQuest APIs.**
+
+Covers the full pattern: geocode user input → find nearby locations → display on map → calculate routes to selected location. Includes distance calculations, result sorting, and marker clustering strategies.
+
+[View skill →](./skills/mapquest-store-locator/SKILL.md)
+
+---
+
+### 🚦 mapquest-traffic-data
+**Integrating real-time traffic data and incidents.**
+
+Covers the Traffic API, incident severity codes, flow segments, how to overlay traffic on maps, and when to factor traffic into routing requests.
+
+[View skill →](./skills/mapquest-traffic-data/SKILL.md)
+
+---
+
+## How Skills Work
+
+### With Claude Code
+
+```bash
+npx add-skill definingAvi/mapquest-agent-skills -a claude-code
+```
+
+### With Cursor
+
+```bash
+npx add-skill definingAvi/mapquest-agent-skills -a cursor
+```
+
+### With VS Code (GitHub Copilot)
+
+```bash
+npx add-skill definingAvi/mapquest-agent-skills -a vscode
+```
+
+## Repository Structure
+
+```
+mapquest-agent-skills/
+├── skills/
+│   ├── mapquest-geocoding-patterns/SKILL.md
+│   ├── mapquest-directions-routing/SKILL.md
+│   ├── mapquest-static-maps/SKILL.md
+│   ├── mapquest-search-ahead/SKILL.md
+│   ├── mapquest-web-integration/SKILL.md
+│   ├── mapquest-key-security/SKILL.md
+│   ├── mapquest-store-locator/SKILL.md
+│   └── mapquest-traffic-data/SKILL.md
+├── examples/
+│   └── conversations/
+├── README.md
+└── package.json
+```
+
+## Resources
+
+- [MapQuest Developer Portal](https://developer.mapquest.com)
+- [MapQuest API Documentation](https://developer.mapquest.com/documentation)
+- [MapQuest Geocoding API](https://developer.mapquest.com/documentation/geocoding-api/)
+- [MapQuest Directions API](https://developer.mapquest.com/documentation/directions-api/)
+- [MapQuest Static Map API](https://developer.mapquest.com/documentation/static-map-api/v5/)
+- [MapQuest Search Ahead API](https://developer.mapquest.com/documentation/searchahead-api/)
+- [Agent Skills Specification](https://agentskills.io)
+
+## License
+
+MIT

package/examples/conversations/store-locator-with-traffic.md

@@ -0,0 +1,34 @@
+# Example: Store Locator with Live Traffic
+
+This shows an AI assistant using MapQuest Agent Skills to build a store locator.
+
+---
+
+**User:** I need to build a store locator for our 200 retail locations. Users type their address, see the nearest stores on a map, and can get directions to the one they choose.
+
+**AI Assistant:** [Uses `mapquest-store-locator`, `mapquest-geocoding-patterns`, `mapquest-search-ahead`, `mapquest-web-integration`, `mapquest-directions-routing` skills]
+
+Great — for 200 locations, here's the pattern I'll use:
+
+- **Search Ahead** for address autocomplete as the user types
+- **Geocoding API** to convert their selected address to coordinates
+- **Haversine distance** (no API needed) to find and sort the 10 nearest stores
+- **Leaflet.markercluster** for the 200 markers (above the 50-marker threshold where individual markers cause performance issues)
+- **Directions API** only when the user clicks "Get Directions" on a specific store
+
+Here's the implementation...
+
+[Generates complete working code following all skill patterns]
+
+---
+
+**User:** Should I show traffic on the map?
+
+**AI Assistant:** [Uses `mapquest-traffic-data` skill]
+
+It depends on your use case:
+
+- **Yes** if your users are making same-day decisions about which store to visit — live traffic helps them pick the fastest route
+- **Skip it** if users are planning ahead or if your stores are in suburban/rural areas where traffic matters less
+
+If you add it: scope the traffic API calls to the visible map bounds, poll no faster than every 2 minutes, and give users a toggle to show/hide it. Here's how...

package/index.js

@@ -0,0 +1,21 @@
+const path = require('path');
+const pkg = require('./package.json');
+
+/**
+ * Returns all available skills with their absolute paths resolved.
+ */
+function getSkills() {
+  return pkg.skills.map(skill => ({
+    ...skill,
+    absolutePath: path.resolve(__dirname, skill.path),
+  }));
+}
+
+/**
+ * Returns a single skill by name, or undefined if not found.
+ */
+function getSkill(name) {
+  return getSkills().find(s => s.name === name);
+}
+
+module.exports = { getSkills, getSkill };

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "mapquest-agent-skills",
+  "version": "1.0.0",
+  "description": "Agent Skills for AI coding assistants (Claude Code, Cursor, Copilot) — teaches MapQuest API best practices: geocoding, directions, static maps, search-ahead, store locators, traffic, and key security.",
+  "main": "index.js",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/definingAvi/mapquest-agent-skills.git"
+  },
+  "homepage": "https://github.com/definingAvi/mapquest-agent-skills#readme",
+  "bugs": {
+    "url": "https://github.com/definingAvi/mapquest-agent-skills/issues"
+  },
+  "author": "definingAvi",
+  "license": "MIT",
+  "keywords": ["mapquest","maps","geocoding","directions","agent-skills","ai","claude","cursor","copilot","llm"],
+  "files": ["skills/","examples/","index.js","README.md","LICENSE"],
+  "skills": [
+    {"name":"mapquest-geocoding-patterns","path":"skills/mapquest-geocoding-patterns/SKILL.md","description":"Address-to-coordinate and coordinate-to-address conversion using the MapQuest Geocoding API"},
+    {"name":"mapquest-directions-routing","path":"skills/mapquest-directions-routing/SKILL.md","description":"Turn-by-turn directions and multi-stop routing using the MapQuest Directions API"},
+    {"name":"mapquest-static-maps","path":"skills/mapquest-static-maps/SKILL.md","description":"Generating and embedding static map images via the MapQuest Static Map API"},
+    {"name":"mapquest-search-ahead","path":"skills/mapquest-search-ahead/SKILL.md","description":"Typeahead/autocomplete using the MapQuest Search Ahead API"},
+    {"name":"mapquest-web-integration","path":"skills/mapquest-web-integration/SKILL.md","description":"Integrating the MapQuest JS SDK into web applications including React and Vue"},
+    {"name":"mapquest-key-security","path":"skills/mapquest-key-security/SKILL.md","description":"Best practices for securing MapQuest API keys"},
+    {"name":"mapquest-store-locator","path":"skills/mapquest-store-locator/SKILL.md","description":"Full store locator pattern: geocode user input, find nearby locations, display on map, get directions"},
+    {"name":"mapquest-traffic-data","path":"skills/mapquest-traffic-data/SKILL.md","description":"Real-time traffic incidents, flow data, and traffic-aware routing"}
+  ]
+}

package/skills/mapquest-directions-routing/SKILL.md

@@ -0,0 +1,261 @@
+---
+name: mapquest-directions-routing
+description: Turn-by-turn directions, multi-stop routing, and route optimization using the MapQuest Directions API. Covers route types, narrative maneuvers, response parsing, and common pitfalls.
+---
+
+# MapQuest Directions & Routing Patterns
+
+## Overview
+
+The MapQuest Directions API provides turn-by-turn directions between two or more locations. Base URL: `https://www.mapquestapi.com/directions/v2`
+
+---
+
+## Route Types
+
+Choose the right `routeType` for the use case:
+
+| routeType | Description | Use When |
+|---|---|---|
+| `fastest` | Minimize travel time (default) | Standard driving |
+| `shortest` | Minimize distance | Fuel efficiency priority |
+| `pedestrian` | Walking paths | Walking directions |
+| `bicycle` | Bike-friendly routes | Cycling apps |
+| `multimodal` | Mix of transit + walking | Urban transit apps |
+
+---
+
+## Basic Directions Request
+
+```js
+async function getDirections(from, to, apiKey, options = {}) {
+  const params = new URLSearchParams({
+    key: apiKey,
+    from,
+    to,
+    routeType: options.routeType || 'fastest',
+    unit: options.unit || 'm',         // 'm' = miles, 'k' = kilometers
+    narrativeType: 'text',             // 'text', 'microformat', 'none'
+    enhancedNarrative: false,
+    avoidTimedConditions: false,
+  });
+
+  const response = await fetch(
+    `https://www.mapquestapi.com/directions/v2/route?${params}`
+  );
+  const data = await response.json();
+
+  if (data.info.statuscode !== 0) {
+    throw new Error(`Directions error: ${data.info.messages.join(', ')}`);
+  }
+
+  return data.route;
+}
+```
+
+---
+
+## Multi-Stop Routing
+
+For routes with 3+ stops, use the `from`/`to` + multiple `to` parameters, or POST with a locations array:
+
+```js
+async function getMultiStopRoute(locations, apiKey) {
+  // locations: array of address strings or {lat, lng} objects
+  const response = await fetch(
+    `https://www.mapquestapi.com/directions/v2/route?key=${apiKey}`,
+    {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        locations: locations,
+        options: {
+          routeType: 'fastest',
+          unit: 'm',
+          narrativeType: 'text',
+          avoids: [],               // e.g. ['Toll Road', 'Ferry', 'Unpaved']
+          doReverseGeocode: false,  // Skip reverse geocoding stops (faster)
+        }
+      })
+    }
+  );
+
+  const data = await response.json();
+  return data.route;
+}
+
+// Example with lat/lng objects (avoid geocoding overhead)
+const stops = [
+  { latLng: { lat: 34.0522, lng: -118.2437 } },  // Los Angeles
+  { latLng: { lat: 36.1699, lng: -115.1398 } },  // Las Vegas
+  { latLng: { lat: 33.4484, lng: -112.0740 } },  // Phoenix
+];
+```
+
+---
+
+## Parsing the Route Response
+
+```js
+function parseRoute(route) {
+  return {
+    // Overall trip summary
+    distance: route.distance,          // in chosen unit (miles or km)
+    time: route.time,                  // seconds
+    formattedTime: route.formattedTime, // 'h:mm:ss'
+
+    // Route shape (encoded polyline)
+    shape: route.shape?.shapePoints,   // flat array [lat, lng, lat, lng, ...]
+
+    // Per-leg details (one leg per stop-to-stop segment)
+    legs: route.legs.map(leg => ({
+      distance: leg.distance,
+      time: leg.time,
+      maneuvers: leg.maneuvers.map(m => ({
+        narrative: m.narrative,        // Human-readable instruction
+        distance: m.distance,
+        time: m.time,
+        turnType: m.turnType,          // 0=straight, 1=slight right, etc.
+        startPoint: m.startPoint,      // {lat, lng}
+        signs: m.signs,                // Road signs
+        iconUrl: m.iconUrl,
+      }))
+    })),
+
+    // Bounding box for fitting map view
+    boundingBox: route.boundingBox,    // {ul: {lat,lng}, lr: {lat,lng}}
+
+    // Status
+    hasTollRoad: route.hasTollRoad,
+    hasHighway: route.hasHighway,
+    hasFerry: route.hasFerry,
+  };
+}
+```
+
+---
+
+## Route Avoidances
+
+```js
+const avoidOptions = [
+  'Toll Road',
+  'Limited Access',
+  'Ferry',
+  'Unpaved',
+  'Seasonal Closure',
+  'Country Border Crossing',
+];
+
+// In request options:
+options: {
+  avoids: ['Toll Road', 'Ferry']
+}
+```
+
+---
+
+## Optimized Route (Traveling Salesman)
+
+For store locators or delivery apps needing to reorder stops optimally:
+
+```js
+async function getOptimizedRoute(locations, apiKey) {
+  const response = await fetch(
+    `https://www.mapquestapi.com/directions/v2/optimizedroute?key=${apiKey}`,
+    {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        locations,
+        options: { routeType: 'fastest', unit: 'm' }
+      })
+    }
+  );
+  const data = await response.json();
+  // data.route.locationSequence shows optimized stop order
+  return data;
+}
+```
+
+---
+
+## Decoding the Shape Polyline
+
+The route shape comes as a flat array of alternating lat/lng values:
+
+```js
+function shapeToLatLngs(shapePoints) {
+  const latLngs = [];
+  for (let i = 0; i < shapePoints.length; i += 2) {
+    latLngs.push([shapePoints[i], shapePoints[i + 1]]);
+  }
+  return latLngs;
+}
+
+// Draw on Leaflet/MapQuest JS:
+const latLngs = shapeToLatLngs(route.shape.shapePoints);
+L.polyline(latLngs, { color: '#1a73e8', weight: 4 }).addTo(map);
+```
+
+---
+
+## Displaying Formatted Distance & Time
+
+```js
+function formatDistance(miles) {
+  if (miles < 0.1) return `${Math.round(miles * 5280)} ft`;
+  return `${miles.toFixed(1)} mi`;
+}
+
+function formatDuration(seconds) {
+  const h = Math.floor(seconds / 3600);
+  const m = Math.floor((seconds % 3600) / 60);
+  if (h === 0) return `${m} min`;
+  return `${h} hr ${m} min`;
+}
+```
+
+---
+
+## Turn Type Icons
+
+MapQuest returns numeric `turnType` codes. Map them to icons/labels:
+
+```js
+const TURN_TYPES = {
+  0: 'Straight',
+  1: 'Slight Right', 2: 'Right', 3: 'Sharp Right',
+  4: 'Reverse', 5: 'Sharp Left', 6: 'Left', 7: 'Slight Left',
+  8: 'Right U-Turn', 9: 'Left U-Turn',
+  11: 'Becomes', 12: 'Merge', 13: 'Fork Keep Right', 14: 'Fork Keep Left',
+  15: 'First Exit', 16: 'Second Exit', 17: 'Third Exit',
+  18: 'Exit Right', 19: 'Exit Left',
+  20: 'Right Ramp', 21: 'Left Ramp',
+  22: 'Right on Ramp', 23: 'Left on Ramp',
+  24: 'Take Ferry',
+  27: 'Roundabout 1st Exit', 28: 'Roundabout 2nd Exit', 29: 'Roundabout 3rd Exit',
+};
+```
+
+---
+
+## Common Mistakes to Avoid
+
+❌ **Don't** send raw address strings with unencoded special characters. Always `encodeURIComponent()`.
+
+❌ **Don't** use `pedestrian` routes for long distances (API may return an error or empty result).
+
+❌ **Don't** ignore `statuscode`. Possible values:
+- `0` = Success
+- `402` = Invalid key
+- `403` = Forbidden (key disabled)
+- `500` = Route not found
+
+❌ **Don't** request narrative for apps that only need the shape/distance — set `narrativeType: 'none'` for faster responses.
+
+✅ **Do** use lat/lng objects instead of address strings when you already have coordinates — avoids extra geocoding cost.
+
+✅ **Do** cache direction results for common origin/destination pairs.
+
+✅ **Do** fit the map to `route.boundingBox` after rendering so the full route is visible.