Build Skills That Call External APIs Safely — Patterns for Production

Skills can integrate with any HTTP API — weather services, GitHub, internal company APIs, anything. The pattern is straightforward but requires care with credentials and error handling. Here is how to build API-calling skills that are safe to share.

Once you understand markdown-only skills and skills with scripts, the next step is skills that call external APIs. This is where skills become genuinely powerful — bringing live external data into the agent workflow without requiring a separate MCP server.

The pattern is straightforward: bundle a script that makes HTTP requests, read credentials from environment variables, handle errors gracefully, and document everything in the SKILL.md.

Never Hardcode Credentials

The single most important rule for API-calling skills: never put credentials in the skill files. API keys, OAuth tokens, database passwords — none of these belong in SKILL.md, scripts, or any file that might end up in a git repository.

Use environment variables read at runtime instead. For Claude Code, set them in ~/.claude/.env. For other agents, in their equivalent config file. The skill files reference variables by name (OPENWEATHER_API_KEY) but never contain actual values. This makes skills safely shareable and version-controllable.

The Pattern: A Weather Skill

Here is a complete API-calling skill — fetching weather data from OpenWeatherMap. The folder structure:

weather-skill/
├── SKILL.md
└── scripts/
    └── get_weather.sh

The script:

#!/bin/bash
CITY=$1
if [ -z "$OPENWEATHER_API_KEY" ]; then
  echo "Error: OPENWEATHER_API_KEY not set"
  exit 1
fi

curl -s "https://api.openweathermap.org/data/2.5/weather" \
  -G --data-urlencode "q=$CITY" \
  --data-urlencode "appid=$OPENWEATHER_API_KEY" \
  --data-urlencode "units=metric"

The script does three important things: checks that the required environment variable is set (and fails clearly if not), uses --data-urlencode to handle special characters in inputs safely, and returns the API response on stdout for the agent to parse.

The SKILL.md That Documents It All

---
name: weather-fetcher
description: Fetches current weather data for any city from
  OpenWeatherMap. Use when the user asks about weather,
  current conditions, temperature or forecasts for a specific
  location.
---

## Instructions

1. Verify OPENWEATHER_API_KEY is set in the environment
2. Run: bash scripts/get_weather.sh "[city name]"
3. Parse the JSON response
4. Present current conditions to the user

## Required Environment Variables

- OPENWEATHER_API_KEY: Free at openweathermap.org/api

Handle Errors Gracefully

API calls fail in predictable ways: missing credentials, network errors, rate limits, malformed responses, the service being down. A good API-calling skill handles each case. Check that environment variables are set. Verify HTTP response codes before parsing. Handle empty responses. Output clear error messages to stderr so the agent can recognise them and respond appropriately.

The agent reads both stdout and stderr from the script. Errors on stderr signal the agent that something went wrong; the agent can then explain the problem to the user rather than pretending the call succeeded.