Sentinel

Architecture

User Query
    ↓
Claude Agent (this skill)
    ↓
Custom Tools (sentinel_find_closest, sentinel_get_visual)
    ↓
Sentinel CLI (business logic)
    ↓
NASA APIs (NeoWs, APOD)

Constitutional Compliance:

• Rule of Discovery: Tools include CLI capability discovery
• Boundary: All business logic in CLI; agent only orchestrates
• Output Format: Structured JSON via CLIOutput envelope

Prerequisites

Environment Setup

1. NASA API Key (required):

   export NASA_API_KEY="your_api_key_here"
   

   Get free key at: https://api.nasa.gov

2. Anthropic API Key (for agent usage):

   export ANTHROPIC_API_KEY="your_key_here"
   

3. Sentinel CLI Installation:

   pip install -e .
   

Verification

Test the CLI is installed:

sentinel --help
sentinel find-closest --help
sentinel get-visual --help

Tool Definitions

The skill provides two structured tools defined in sentinel_skill.py:

Tool 1: sentinel_find_closest

Find today's closest asteroid approaching Earth.

Input Schema:

{
  "verbose": false  // Optional: enable diagnostic output
}

Output:

{
  "status": "success",
  "data": {
    "asteroid": {
      "name": "2024 AA1",
      "distance_miles": 2340000.5,
      "velocity_mph": 25000.3,
      "approach_date": "2024-02-16T14:23:00Z",
      "is_potentially_hazardous": false
    }
  },
  "message": "Found closest asteroid: 2024 AA1"
}

Tool 2: sentinel_get_visual

Get NASA's Astronomy Picture of the Day.

Input Schema:

{
  "date": "2024-01-15",  // Optional: YYYY-MM-DD format, defaults to today
  "verbose": false        // Optional: enable diagnostic output
}

Date Constraints:

• Earliest: 1995-06-16 (APOD service start)
• Latest: Today (no future dates)
• Format: YYYY-MM-DD

Output:

{
  "status": "success",
  "data": {
    "visual": {
      "date": "2024-01-15",
      "url": "https://apod.nasa.gov/apod/image/2401/orion_jwst.jpg",
      "title": "Orion Nebula in Infrared",
      "description": "This stunning image...",
      "media_type": "image",
      "copyright": "NASA/ESA/CSA",
      "hdurl": "https://apod.nasa.gov/apod/image/2401/orion_jwst_hd.jpg"
    }
  },
  "message": "Retrieved image for 2024-01-15"
}

Usage Procedures

Procedure 1: Find Closest Asteroid

When to use: User asks about asteroids, near-Earth objects, or space threats.

Steps:

1. Confirm NASA_API_KEY is set in environment
2. Load the skill executor
3. Call sentinel_find_closest tool with optional verbose flag
4. Parse the JSON response (CLIOutput structure)
5. Present asteroid data in natural language:
   • Name and approach date/time
   • Distance in miles (optionally convert to km)
   • Velocity in mph (optionally convert to km/h)
   • Hazard status if available

Example Agent Interaction:

User: "What's the closest asteroid today?"

Agent Actions:
1. Invokes sentinel_find_closest tool
2. Receives: {"status": "success", "data": {"asteroid": {...}}}
3. Responds: "The closest asteroid today is 2024 AA1, approaching 
   at 2,340,000 miles with a velocity of 25,000 mph at 2:23 PM UTC.
   It is not classified as potentially hazardous."

Procedure 2: Retrieve NASA Image

When to use: User asks for space images, APOD, or images from specific dates.

Steps:

1. Confirm NASA_API_KEY is set in environment
2. Load the skill executor
3. Parse date if provided, or use today
4. Validate date is between 1995-06-16 and today
5. Call sentinel_get_visual tool with date parameter
6. Parse the JSON response (CLIOutput structure)
7. Present visual data:
   • Title and date
   • Image URL (as clickable link)
   • Description (summarize if long)
   • Media type (image or video)
   • Copyright attribution if present

Example Agent Interaction:

User: "Show me NASA's image from January 15th, 2024"

Agent Actions:
1. Invokes sentinel_get_visual with {"date": "2024-01-15"}
2. Receives: {"status": "success", "data": {"visual": {...}}}
3. Responds: "Here's NASA's Astronomy Picture of the Day for 
   January 15, 2024: 'Orion Nebula in Infrared' by NASA/ESA/CSA.
   
   [View Image](https://apod.nasa.gov/apod/image/2401/orion_jwst.jpg)
   
   This stunning image captured by the James Webb Space Telescope..."

Procedure 3: Combined Queries

When to use: User asks for multiple types of data.

Steps:

1. Execute relevant tools in sequence or parallel
2. Combine results in coherent response
3. Maintain context between tool calls

Example:

User: "What's happening in space today?"

Agent Actions:
1. Call sentinel_find_closest for asteroid data
2. Call sentinel_get_visual for today's image
3. Combine: "Today's closest asteroid is... and NASA's Astronomy 
   Picture of the Day shows..."

Error Handling

All tools return CLIOutput structure with status field:

Success Response

{
  "status": "success",
  "data": { /* tool-specific data */ },
  "message": "Descriptive success message"
}

Error Response

{
  "status": "error",
  "data": null,
  "message": "Detailed error with remediation guidance"
}

Common Errors

Missing API Key:

"NASA API key not found. Set NASA_API_KEY environment variable. 
Get key at https://api.nasa.gov"

→ Guide user to obtain and set NASA_API_KEY

Rate Limit:

"NASA API rate limit exceeded. Retry after 3600 seconds or use 
a registered API key."

→ Inform user to wait or upgrade API key

Invalid Date:

"Future date 2025-01-01 is not valid. APOD images are only 
available up to today (2024-02-16)."

→ Clarify date constraints (1995-06-16 to today)

No Data:

"No asteroids found for today (2024-02-16)"

→ Explain no close approaches detected today

Network Timeout:

"Network request timed out after 30 seconds. Check your internet 
connection and retry."

→ Suggest retrying, checking connectivity

Implementation Details

Tool Executor

The sentinel_skill.py script provides:

Class: SentinelSkillExecutor

• Executes CLI commands via subprocess
• Parses JSON output from --json flag
• Handles errors and returns consistent structure

Function: create_tool_handler()

• Factory for tool execution function
• Returns handler that maps tool names to executors

Function: discover_cli_capabilities()

• Runs sentinel --help to verify CLI availability
• Returns CLI version and available commands
• Called at agent initialization (Rule of Discovery)

Constant: SENTINEL_TOOLS

• List of tool definitions for Claude SDK
• Includes input schemas and descriptions

Integration Pattern

from scripts.sentinel_skill import SENTINEL_TOOLS, create_tool_handler, discover_cli_capabilities
import anthropic

# Initialize
client = anthropic.Anthropic()
tool_handler = create_tool_handler()

# Discover CLI (Rule of Discovery)
cli_info = discover_cli_capabilities()
if not cli_info.get("available"):
    # Handle CLI not installed
    pass

# Use tools in conversation
response = client.messages.create(
    model="claude-haiku-4-5-20251001",
    max_tokens=4096,
    tools=SENTINEL_TOOLS,
    messages=[{"role": "user", "content": "What's the closest asteroid?"}]
)

# Handle tool execution
for block in response.content:
    if block.type == "tool_use":
        result = tool_handler(block.name, block.input)
        # Continue conversation with result

Advanced Usage

Verbose Mode

Enable diagnostic output for debugging:

tool_handler("sentinel_find_closest", {"verbose": True})
tool_handler("sentinel_get_visual", {"date": "2024-01-15", "verbose": True})

Verbose output includes:

• API request URLs
• Response timing
• Data parsing steps
• Detailed error traces

Date Range Queries

For historical analysis, loop through date ranges:

from datetime import date, timedelta

start = date(2024, 1, 1)
end = date(2024, 1, 7)
current = start

while current <= end:
    result = tool_handler("sentinel_get_visual", {
        "date": current.isoformat()
    })
    # Process result
    current += timedelta(days=1)

Batch Queries

For multiple asteroid checks throughout the day, cache results:

# Cache asteroid data to avoid repeated API calls
asteroid_cache = None
cache_time = None

def get_cached_asteroid():
    global asteroid_cache, cache_time
    from datetime import datetime, timedelta
    
    now = datetime.utcnow()
    if asteroid_cache is None or (now - cache_time) > timedelta(hours=1):
        asteroid_cache = tool_handler("sentinel_find_closest", {})
        cache_time = now
    
    return asteroid_cache

Testing

Manual CLI Testing

Before using tools, verify CLI works directly:

# Test asteroid lookup
sentinel find-closest --json

# Test visual lookup
sentinel get-visual --date 2024-01-15 --json

# Test error handling
sentinel get-visual --date 2030-01-01 --json  # Future date
sentinel find-closest --json  # Without NASA_API_KEY set

Tool Testing

Test the skill executor independently:

from scripts.sentinel_skill import create_tool_handler

handler = create_tool_handler()

# Test asteroid tool
result = handler("sentinel_find_closest", {})
assert result["status"] == "success"
assert "asteroid" in result["data"]

# Test visual tool
result = handler("sentinel_get_visual", {"date": "2024-01-15"})
assert result["status"] == "success"
assert "visual" in result["data"]

Troubleshooting

CLI Not Found

Symptom: "Sentinel CLI not found. Install with: pip install -e ."

Solutions:

1. Check if package is installed: pip list | grep sentinel
2. Verify entry point: which sentinel
3. Reinstall: pip install -e .
4. Check virtual environment is activated

API Key Issues

Symptom: "Invalid NASA API key"

Solutions:

1. Verify key is set: echo $NASA_API_KEY
2. Test key at https://api.nasa.gov/neo/rest/v1/feed?api_key=YOUR_KEY
3. Register for new key if expired
4. Check for typos or extra spaces

Import Errors

Symptom: "Module not found" for sentinel_skill

Solutions:

1. Ensure scripts are in correct path relative to skill folder
2. Check file exists: ls .github/skills/sentinel/scripts/sentinel_skill.py
3. Verify skill is being loaded from correct directory

JSON Parsing Failures

Symptom: "Failed to parse JSON output"

Solutions:

1. Run CLI manually to check output format
2. Use --verbose to see raw output
3. Check if CLI is writing to stderr instead of stdout
4. Verify CLI version matches expected output format

Project Context

Specification: specs/001-sentinel-nasa-cli/

• spec.md - Feature requirements
• plan.md - Technical design
• data-model.md - Entity definitions
• contracts/ - API contracts
• quickstart.md - Usage guide

CLI Source: sentinel/ Agent: agent.py - Example agent implementation Skill Executor: scripts/sentinel_skill.py

References

• NASA API Documentation
• NeoWs API
• APOD API
• Claude SDK Documentation

Version History

• v1.0.0 (2024-02-16): Initial release
  • Two core tools: find_closest, get_visual
  • Custom skill architecture with structured tools
  • CLI discovery and validation
  • Comprehensive error handling