Claude Skill

api-fetch-wrapper

Wrap a public HTTP API (Open-Meteo weather as the demo) with credential handling, error normalisation, and a single retry on transient network failures. Demonstrates the production-shaped baseline for any "skill that calls an external service" — env-based secrets, structured erro

LLM Mart · 0 points · 3 views 58 listing impressions 0 install-command copies
Download chronoaiproject-ornn-examples_api-fetch-wrapper-e7e21e9.zip · 3 KB

Install

skills CLI npx skills add https://github.com/ChronoAIProject/Ornn/tree/develop/examples/api-fetch-wrapper
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install chronoaiproject-ornn@llmmart
Git git clone https://github.com/ChronoAIProject/Ornn.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole chronoaiproject/ornn collection as a plugin from our marketplace. Git is the plain clone.

README

api-fetch-wrapper

Call a public HTTP API with retries, structured errors, and no-leak credential handling. Demo target is Open-Meteo (keyless, so the example runs out of the box).

Run: echo '{"latitude":52.52,"longitude":13.41}' | bun run src/index.ts

Adapt: swap the upstream URL + shape; add Authorization header reading from env. The retry-and-error-mapping skeleton is the load-bearing part — don't drop it.

See SKILL.md for the full contract.

Skill manifest

api-fetch-wrapper

The case that breaks first in production — a skill that hits an external service. This example covers the four things every such skill needs: secret handling, retry policy, error normalisation, and no-leak-on-failure logging.

Contract

Input (stdin, JSON):

{ "latitude": 52.52, "longitude": 13.41 }

Output (stdout, JSON):

{
  "temperatureC": 18.4,
  "windSpeedKmh": 12.6,
  "fetchedAt": "2026-05-19T08:00:00.000Z"
}

Errors — written to stderr as {"error": "...", "cause": "..."} and exit code 1. Error messages NEVER include the raw upstream response body (it might echo a secret); they include the upstream status code and a short canonical reason.

Required environment

Var Purpose
OPEN_METEO_URL Optional override of the upstream host. Defaults to https://api.open-meteo.com.
(none for auth) Open-Meteo is keyless. For an auth'd API, the same skeleton reads process.env.YOUR_API_KEY and passes it via Authorization header.

Run locally

cd examples/api-fetch-wrapper
bun install
echo '{"latitude":52.52,"longitude":13.41}' | bun run src/index.ts

Adapt this

  • Different API — replace the URL, query params, and response shape. The retry / error-mapping skeleton stays.
  • API-key auth — read process.env.YOUR_API_KEY once at the top, pass it via Authorization: Bearer ${apiKey}, and ensure the key never appears in error messages.
  • Stronger retry — bump MAX_ATTEMPTS, add exponential backoff with jitter, or distinguish 5xx (retry) vs 4xx (do not retry) explicitly.
  • Cache — wrap the fetch in a TTL cache when the upstream rate-limits.
Files (ornn)
  • src
    • index.ts 3.6 KB
      Loading…
  • package.json 282 B
    Loading…
  • README.md 470 B
    # api-fetch-wrapper
    
    Call a public HTTP API with retries, structured errors, and no-leak credential handling. Demo target is Open-Meteo (keyless, so the example runs out of the box).
    
    **Run:** `echo '{"latitude":52.52,"longitude":13.41}' | bun run src/index.ts`
    
    **Adapt:** swap the upstream URL + shape; add `Authorization` header reading from env. The retry-and-error-mapping skeleton is the load-bearing part — don't drop it.
    
    See `SKILL.md` for the full contract.
    
  • SKILL.md 2.4 KB
    ---
    name: api-fetch-wrapper
    description: Wrap a public HTTP API (Open-Meteo weather as the demo) with credential handling, error normalisation, and a single retry on transient network failures. Demonstrates the production-shaped baseline for any "skill that calls an external service" — env-based secrets, structured error output, no leaked API keys in logs, and a deliberate retry policy. The Open-Meteo endpoint used here is keyless on purpose so the example runs without setup; replace `OPEN_METEO_URL` with your own host and add `process.env.MY_API_KEY` for an auth'd version.
    version: "1.0"
    license: MIT
    metadata:
      category: integration
      tag:
        - example
        - http
        - external-api
        - typescript
    ---
    
    # api-fetch-wrapper
    
    The case that breaks first in production — a skill that hits an external service. This example covers the four things every such skill needs: secret handling, retry policy, error normalisation, and no-leak-on-failure logging.
    
    ## Contract
    
    **Input** (stdin, JSON):
    
    ```json
    { "latitude": 52.52, "longitude": 13.41 }
    ```
    
    **Output** (stdout, JSON):
    
    ```json
    {
      "temperatureC": 18.4,
      "windSpeedKmh": 12.6,
      "fetchedAt": "2026-05-19T08:00:00.000Z"
    }
    ```
    
    **Errors** — written to stderr as `{"error": "...", "cause": "..."}` and exit code `1`. Error messages NEVER include the raw upstream response body (it might echo a secret); they include the upstream status code and a short canonical reason.
    
    ## Required environment
    
    | Var | Purpose |
    |---|---|
    | `OPEN_METEO_URL` | Optional override of the upstream host. Defaults to `https://api.open-meteo.com`. |
    | *(none for auth)* | Open-Meteo is keyless. For an auth'd API, the same skeleton reads `process.env.YOUR_API_KEY` and passes it via `Authorization` header. |
    
    ## Run locally
    
    ```bash
    cd examples/api-fetch-wrapper
    bun install
    echo '{"latitude":52.52,"longitude":13.41}' | bun run src/index.ts
    ```
    
    ## Adapt this
    
    - **Different API** — replace the URL, query params, and response shape. The retry / error-mapping skeleton stays.
    - **API-key auth** — read `process.env.YOUR_API_KEY` once at the top, pass it via `Authorization: Bearer ${apiKey}`, and ensure the key never appears in error messages.
    - **Stronger retry** — bump `MAX_ATTEMPTS`, add exponential backoff with jitter, or distinguish 5xx (retry) vs 4xx (do not retry) explicitly.
    - **Cache** — wrap the fetch in a TTL cache when the upstream rate-limits.
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.