Claude Skills - Modular Location Intelligence Tools

What Are Agent Skills?

Agent Skills are modular packages of knowledge and capabilities that extend Claude's abilities. Each skill is a directory containing a SKILL.md file with YAML frontmatter and progressive disclosure architecture.

Key Benefits

• Progressive Disclosure: Skills load information in stages - metadata first, then core instructions, then additional resources as needed
• Context Efficiency: Only relevant information is loaded into context when needed
• Reusability: Create once, use across multiple agents and workflows
• Version Control: Manage skill versions through API and console
• Modularity: Combine multiple skills (up to 8 per request) for complex capabilities

Creating a Location Intelligence Skill

Basic Skill Structure

camino-location-skill/
├── SKILL.md              # Core skill definition
├── reference.md          # API reference documentation
├── use-cases.md          # Example scenarios
└── tools/
    └── search.py         # Helper scripts (optional)

SKILL.md Format

---
name: Camino Location Intelligence
description: Search locations, calculate routes, and perform spatial analysis using natural language queries via Camino AI API
---

# Location Intelligence Skill

This skill enables Claude to perform location-aware tasks using Camino AI's location intelligence API.

## When to Use This Skill

Use this skill when you need to:
- Find places based on natural language descriptions
- Calculate routes and travel times between locations
- Analyze spatial relationships
- Plan multi-stop journeys
- Get contextual information about geographic areas

## Available Capabilities

### 1. Location Search
Search for places using natural language queries.

**API Endpoint:** GET https://api.getcamino.ai/query

**Parameters:**
- `query` (required): Natural language description (e.g., "coffee shops near Central Park")
- `lat` (optional): Latitude coordinate
- `lon` (optional): Longitude coordinate
- `radius` (optional): Search radius in meters (default: 1000)
- `rank` (optional): Enable AI ranking (default: true)
- `answer` (optional): Generate human-readable summary (default: true)
- `limit` (optional): Maximum results (default: 20)

**Authentication:**
Include API key in X-API-Key header.

**Example Query:**
```bash
curl -H "X-API-Key: YOUR_KEY" \
  "https://api.getcamino.ai/query?query=Italian%20restaurants&lat=40.7589&lon=-73.9851&rank=true"
```

**Response Structure:**
```json
{
  "results": [
    {
      "name": "Restaurant Name",
      "lat": 40.7614,
      "lon": -73.9776,
      "address": "123 Main St",
      "distance_km": 0.5,
      "tags": {...}
    }
  ],
  "answer": "AI-generated summary..."
}
```

### 2. Route Calculation
Calculate routes with turn-by-turn directions.

**API Endpoint:** GET https://api.getcamino.ai/route

**Parameters:**
- `start_lat`, `start_lon`: Starting coordinates
- `end_lat`, `end_lon`: Destination coordinates
- `mode`: Transport mode (car, bike, foot)

**Example:**
```bash
curl -H "X-API-Key: YOUR_KEY" \
  "https://api.getcamino.ai/route?start_lat=40.7589&start_lon=-73.9851&end_lat=40.7614&end_lon=-73.9776&mode=foot"
```

### 3. Spatial Relationships
Analyze relationships between locations.

**API Endpoint:** POST https://api.getcamino.ai/relationship

**Request Body:**
```json
{
  "start": {"lat": 40.7589, "lon": -73.9851},
  "end": {"lat": 40.7614, "lon": -73.9776},
  "include": ["distance", "direction", "travel_time", "description"]
}
```

### 4. Location Context
Get AI-generated contextual information about areas.

**API Endpoint:** POST https://api.getcamino.ai/context

**Request Body:**
```json
{
  "location": {"lat": 40.7589, "lon": -73.9851},
  "radius": 500,
  "context": "What businesses and attractions are in this area?"
}
```

## Best Practices

1. **Always provide coordinates when possible** for most accurate results
2. **Use descriptive queries** ("family-friendly parks" > "parks")
3. **Enable AI ranking** (`rank=true`) for relevance-sorted results
4. **Set appropriate radius** based on search context (urban: 500-2000m, suburban: 2000-5000m)
5. **Request answers** (`answer=true`) for human-readable summaries
6. **Handle rate limits** (30 requests/minute)
7. **Cache responses** when appropriate

## Common Patterns

### Finding Nearby Places
```
User: "Find coffee shops near Times Square"
Action: Use /query with query="coffee shops", lat=40.7589, lon=-73.9851, rank=true
```

### Route Planning
```
User: "How do I walk from the Louvre to Eiffel Tower?"
Action: Use /route with appropriate Paris coordinates, mode=foot
```

### Multi-Stop Itinerary
```
User: "Plan a day visiting museums in Paris"
Action: 
1. Use /query to find museums
2. Use /journey to optimize multi-stop route
3. Present itinerary with travel times
```

## Error Handling

- **401 Unauthorized:** Check API key in X-API-Key header
- **429 Rate Limited:** Implement exponential backoff
- **Empty Results:** Increase radius or broaden query terms
- **Invalid Coordinates:** Verify lat/lon are valid numbers in correct range

## Pricing

- **Cost:** $0.001 per API call
- **Free Tier:** 1,000 calls/month
- **17x cheaper** than Google Places API

## Additional Resources

For detailed API documentation, see reference.md
For real-world examples, see use-cases.md

API Integration with Skills

Using Skills via Messages API

import anthropic

client = anthropic.Anthropic(api_key="YOUR_ANTHROPIC_KEY")

# Upload custom skill (one-time)
skill_response = client.skills.create(
    name="Camino Location Intelligence",
    description="Search locations and calculate routes using Camino AI",
    files=[
        ("SKILL.md", open("camino-location-skill/SKILL.md", "rb")),
        ("reference.md", open("camino-location-skill/reference.md", "rb"))
    ]
)

skill_id = skill_response.id

# Use skill in conversation
message = client.messages.create(
    model="claude-sonnet-4.5-20250929",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "type": "skills",
        "skills": [
            {
                "type": "custom",
                "skill_id": skill_id,
                "version": "1.0.0"
            }
        ]
    },
    messages=[
        {
            "role": "user",
            "content": "Find me the top 3 Italian restaurants near Central Park and tell me which is closest."
        }
    ]
)

print(message.content)

TypeScript/Node.js Example

import Anthropic from '@anthropic-ai/sdk';
import fs from 'fs';

const client = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY,
});

// Upload skill
const skill = await client.skills.create({
  name: 'Camino Location Intelligence',
  description: 'Search locations and calculate routes using Camino AI',
  files: [
    { name: 'SKILL.md', content: fs.readFileSync('camino-location-skill/SKILL.md') },
    { name: 'reference.md', content: fs.readFileSync('camino-location-skill/reference.md') }
  ]
});

// Use skill in message
const message = await client.messages.create({
  model: 'claude-sonnet-4.5-20250929',
  max_tokens: 4096,
  betas: ['code-execution-2025-08-25', 'skills-2025-10-02'],
  container: {
    type: 'skills',
    skills: [
      {
        type: 'custom',
        skill_id: skill.id,
        version: '1.0.0'
      }
    ]
  },
  messages: [
    {
      role: 'user',
      content: 'Plan a walking tour of Paris visiting 5 museums'
    }
  ]
});

console.log(message.content);

Advanced Skill: Multi-Step Location Planning

Enhanced SKILL.md with Workflows

---
name: Camino Travel Planner
description: Plan complete trips with itineraries, routes, and recommendations using Camino AI location intelligence
---

# Travel Planning Skill

## Multi-Step Planning Workflow

When user requests trip planning:

1. **Extract Requirements**
   - Destination and dates
   - Trip style (adventure, relaxation, cultural, etc.)
   - Budget constraints
   - Special preferences (family-friendly, accessible, etc.)

2. **Find Attractions**
   ```
   GET /query?query={trip_style} attractions in {destination}&rank=true&answer=true&limit=20
   ```

3. **Find Dining**
   ```
   GET /query?query={cuisine_type} restaurants in {area}&rank=true&limit=10
   ```

4. **Calculate Routes**
   ```
   POST /journey
   Body: {"waypoints": [...], "constraints": {"transport": "walking", "time_budget": "6 hours"}}
   ```

5. **Present Itinerary**
   - Morning, afternoon, evening activities
   - Travel times between locations
   - Estimated costs
   - Alternative options

## Example Interaction

**User:** "Plan a romantic day in Venice"

**Skill Actions:**
1. Query: "romantic restaurants with canal views in Venice" → 5 options
2. Query: "scenic viewpoints and gondola stations in Venice" → 8 locations
3. Calculate walking route between selected locations
4. Generate itinerary:
   - 10 AM: Gondola ride at Rialto Bridge
   - 12:30 PM: Lunch at Osteria alle Testiere (1.2km, 15 min walk)
   - 3 PM: St. Mark's Basilica (800m, 10 min walk)
   - 6 PM: Sunset at Ponte dell'Accademia (600m, 8 min walk)
   - 8 PM: Dinner at Da Fiore (400m, 5 min walk)

## Progressive Resource Loading

The skill references additional files that load only when needed:
- `cuisines.md` - Loaded when food recommendations are requested
- `activities.md` - Loaded for activity planning
- `optimization.md` - Loaded for route optimization strategies

Combining Multiple Skills

Skills can be combined for complex workflows. Example: Combine Camino location intelligence with Anthropic's pre-built skills.

message = client.messages.create(
    model="claude-sonnet-4.5-20250929",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "type": "skills",
        "skills": [
            {
                "type": "custom",
                "skill_id": camino_skill_id,  # Location intelligence
                "version": "1.0.0"
            },
            {
                "type": "anthropic",
                "skill_id": "excel",  # Pre-built Excel skill
                "version": "latest"
            },
            {
                "type": "anthropic",
                "skill_id": "pdf",  # Pre-built PDF skill
                "version": "latest"
            }
        ]
    },
    messages=[{
        "role": "user",
        "content": "Find the top 10 hotels in San Francisco, create an Excel comparison spreadsheet, and generate a PDF report with maps."
    }]
)

# Claude automatically:
# 1. Uses Camino skill to search hotels
# 2. Uses Excel skill to create comparison spreadsheet
# 3. Uses PDF skill to generate report
# Each skill loads progressively as needed

Real-World Use Cases

Skill Versioning and Management

Update Skill Version

# Update skill with new version
skill_update = client.skills.update(
    skill_id=skill_id,
    version="1.1.0",
    files=[
        ("SKILL.md", open("camino-location-skill-v1.1/SKILL.md", "rb"))
    ],
    changelog="Added journey planning workflow and better error handling"
)

# List all versions
versions = client.skills.versions.list(skill_id=skill_id)

# Use specific version
message = client.messages.create(
    # ...
    container={
        "type": "skills",
        "skills": [
            {
                "type": "custom",
                "skill_id": skill_id,
                "version": "1.1.0"  # Specify exact version
            }
        ]
    },
    # ...
)

Manage Skills via Console

Access the Anthropic Console to:

• View all uploaded skills
• Manage versions and rollback if needed
• Monitor skill usage and performance
• Share skills across organization
• Test skills in playground environment

Best Practices for Location Intelligence Skills

1. Progressive Resource Loading

Structure skills with multiple referenced files:

camino-location-skill/
├── SKILL.md              # Core instructions (always loaded)
├── api-reference.md      # Load when API details needed
├── examples.md           # Load when examples requested
├── troubleshooting.md    # Load only when errors occur
└── advanced-workflows.md # Load for complex use cases

2. Clear Tool Selection Guidance

In SKILL.md, provide decision trees:

## When to Use Each Endpoint

- **Simple search:** Use /query endpoint
- **Point-to-point route:** Use /route endpoint
- **Multi-stop trip:** Use /journey endpoint
- **Area analysis:** Use /context endpoint
- **Spatial relationship:** Use /relationship endpoint

3. Include Error Recovery

## Error Recovery Strategies

If /query returns no results:
1. Increase radius parameter
2. Try broader query terms
3. Verify coordinates are correct
4. Use /context to understand area first

If rate limited (429):
1. Wait 2 seconds
2. Retry with exponential backoff
3. Consider caching previous results

4. Optimize Context Usage

• Keep SKILL.md concise - put examples in separate files
• Use YAML frontmatter for all metadata
• Reference additional files only when needed
• Provide clear descriptions for progressive loading

Testing Your Skill

Local Testing

import anthropic

client = anthropic.Anthropic()

# Test skill upload
try:
    skill = client.skills.create(
        name="Test Camino Skill",
        description="Testing location intelligence skill",
        files=[("SKILL.md", open("SKILL.md", "rb"))]
    )
    print(f"Skill created: {skill.id}")
except Exception as e:
    print(f"Error: {e}")

# Test skill execution
test_queries = [
    "Find coffee shops near Times Square",
    "Calculate route from Central Park to Statue of Liberty",
    "Plan a day in San Francisco visiting museums and restaurants"
]

for query in test_queries:
    message = client.messages.create(
        model="claude-sonnet-4.5-20250929",
        max_tokens=4096,
        betas=["code-execution-2025-08-25", "skills-2025-10-02"],
        container={"type": "skills", "skills": [{"type": "custom", "skill_id": skill.id}]},
        messages=[{"role": "user", "content": query}]
    )
    print(f"\nQuery: {query}")
    print(f"Response: {message.content[0].text[:200]}...")

Migration from Agent SDK to Skills

If you're using the Claude Agent SDK, Skills provide better modularity:

When to use each:

• Agent SDK: Complex stateful agents, custom tool execution logic, TypeScript/Python ecosystems
• Skills: Reusable knowledge modules, API-driven workflows, context efficiency, cross-project sharing
• Both: Use Skills for knowledge + Agent SDK for orchestration

Example: Complete Location Intelligence Skill Bundle

Download the complete example skill from GitHub:

git clone https://github.com/getcamino/camino-claude-skill.git
cd camino-claude-skill

# Structure:
camino-claude-skill/
├── SKILL.md              # Main skill definition
├── api-reference.md      # Complete API documentation
├── use-cases.md          # Real-world examples
├── workflows.md          # Multi-step planning workflows
├── troubleshooting.md    # Error handling guide
└── README.md             # Installation instructions

# Upload to Claude
python upload_skill.py

Additional Resources

• Agent Skills Documentation
• Skills API Guide
• Official Skills Repository
• Engineering Deep Dive: Agent Skills
• Introducing Agent Skills
• Camino AI API Documentation

Pricing