Most API skills fail for boring reasons. They hardcode auth, ignore rate limits, skip pagination, and assume every endpoint responds with clean JSON on the first try. Then someone installs the skill, points it at a real API, and the agent gets stuck in a loop of 401s, partial results, or brittle one-off fixes.

This guide shows how to build a data fetching skill that actually holds up. It is for developers, platform teams, and operators who want an agent to pull data from APIs without turning every request into a custom debugging session. By the end, you will have a reusable pattern for authentication, endpoint references, retries, pagination, output shaping, and failure handling.

What is a data fetching skill?

A data fetching skill teaches an agent how to connect to an external API, ask for the right data, handle the ugly parts of real integrations, and return something useful. In Anthropic’s taxonomy shared by Thariq, this fits the Data Fetching & Analysis category: skills that connect agents to monitoring stacks, analytics tools, business systems, and external services.

The important distinction is this: a data fetching skill is not just a curl snippet. It is a reusable operating guide. It tells the agent which endpoint to use, how to authenticate, how to follow pagination, when to stop, and how to summarize results for humans. That is why strong API skills often sit next to marketplace listings such as Kong Gateway API AI and MCP Traffic Control, Pipedream API Workflow Automation Platform, and Metabase Open Source Business Intelligence and Embedded Analytics. The value is not access alone. The value is trustworthy use.

When should you build a data fetching skill?

Build one when the agent needs the same external system more than once, or when the integration has enough quirks that you do not want to rediscover them every week. Good candidates include customer support APIs, observability systems, internal admin panels, BI tools, project trackers, and any service where the model needs current data instead of stale pretraining.

If the task is rare and the API is simple, a short prompt may be enough. If the task is recurring, business-critical, or failure-prone, turn it into a skill. That is the same logic behind the Build Your First Agent Skill in 15 Minutes tutorial and the broader case for runbook skills: reusable context beats re-explaining the system every time.

Recommended file structure

Do not put everything into one massive SKILL.md. Use progressive disclosure so the agent can pull details only when needed.

customer-api-skill/
├── SKILL.md
├── config.example.json
├── references/
│   ├── authentication.md
│   ├── endpoints.md
│   ├── pagination.md
│   └── error-handling.md
├── scripts/
│   ├── fetch_customers.py
│   └── smoke_test.sh
└── examples/
    ├── common-queries.md
    └── sample-responses.json

This structure gives the agent a short activation path. SKILL.md handles triggers and judgment. The reference files hold endpoint details, required headers, and examples. The scripts folder carries any repeatable logic that should not be regenerated from scratch on every run.

If you need inspiration, browse marketplace entries tied to structured integrations, such as Hasura GraphQL Engine for Instant API and Database Automation or Baserow Open Source No-Code Database and Automation Platform. These tools are useful because the surrounding skill context can teach an agent what the docs alone do not: where people usually get stuck.

The core SKILL.md pattern

Your description field should read like a trigger map, not marketing copy. Tell the model exactly when to load the skill and when not to.

---
name: customer-api-fetcher
description: >
  Use when querying customer, billing, or account data from the Acme REST API.
  Triggers on: "look up customer by email", "fetch account usage", "get invoice status",
  "why did this sync fail", "list failed webhooks", "query Acme API".
  Not for: updating records, deleting resources, or provisioning new accounts.
---

# Customer API Fetcher

## Workflow
1. Read references/authentication.md and confirm required environment variables exist.
2. Read references/endpoints.md to select the smallest endpoint that answers the question.
3. Prefer filtered requests over full exports.
4. Follow pagination until the request is complete or the user asked for a capped sample.
5. Return a concise summary first, then include raw fields only if useful.

## Required environment variables
- ACME_API_BASE_URL
- ACME_API_TOKEN

## Output rules
- Default to structured bullets and tables.
- Call out missing data, partial pages, or rate-limit truncation.
- Never expose secrets in output.

That single block does a lot of work. It narrows scope, protects against accidental write operations, and tells the agent how to behave when the data comes back.

Auth, pagination, and retries are the real work

Most APIs break the same four ways: authentication drift, pagination bugs, rate limits, and vague errors. If your skill handles those well, it will feel reliable.

1. Authentication

Document the exact auth pattern: bearer token, API key header, OAuth token exchange, session cookie, signed request, or service account. If a token expires every 60 minutes, say that plainly. If the base URL changes across staging and production, move it to config. If the API requires a tenant header, call that out where the model sees it before making a request.

2. Pagination

Be explicit about the pagination scheme. Offset and limit behave differently from cursor-based pagination, and the agent should not guess. If each page returns 100 items and the endpoint caps at 10,000 records, that belongs in the skill. Those are the details that stop silent truncation.

3. Retries and backoff

Spell out what to retry and what not to retry. A 429 or 503 usually deserves exponential backoff. A 401 usually means the token is wrong or expired. A 404 might mean the record does not exist, or the wrong environment is in use. Put those distinctions in the gotchas section.

import requests, time

session = requests.Session()
session.headers.update({"Authorization": f"Bearer {token}"})

for attempt in range(4):
    response = session.get(url, params=params, timeout=20)
    if response.status_code in (429, 503):
        time.sleep(2 ** attempt)
        continue
    response.raise_for_status()
    data = response.json()
    break

This is not fancy code. That is the point. Stable integration skills usually rely on very boring patterns, applied consistently.

Design the output so humans can use it

Raw payloads are rarely helpful. Good data fetching skills summarize first, then reveal detail as needed. If an endpoint returns 247 records, say what matters: count, time window, top anomalies, and the fields the user asked for. If the request is ambiguous, state the filter you used.

A useful pattern is:

• Summary: one paragraph or 3 to 5 bullets
• Key fields: compact table with IDs, timestamps, status, and owner
• Caveats: rate-limit truncation, partial matches, stale cache, or missing permissions
• Next step: suggest a narrower follow-up query when the result set is too broad

This matters even more when the skill feeds another automation layer. A clean summary is easier to pass into a Netdata triage workflow or an external monitoring setup like Checkly CLI Monitoring as Code for API and Browser Checks.

The gotchas section that saves the skill

If you publish only one non-obvious part of the skill, publish the gotchas. This is where you record the weird behavior that the docs gloss over.

## Gotchas
- The search endpoint returns HTTP 200 with an `errors` array when the filter syntax is invalid.
  Always inspect the body before assuming success.
- `updated_after` expects RFC 3339 timestamps in UTC. Local timestamps are accepted but silently misinterpreted.
- The invoices endpoint omits refunded invoices unless `include_refunds=true` is set.
- Sandbox API keys cannot access production account IDs. A 404 may mean wrong environment, not missing data.
- Large exports time out after 30 seconds. Prefer date-windowed requests of 7 days or less.

That kind of detail is what turns a generic API skill into something a team can trust. It is also why strong marketplace listings tend to outperform vague ones. Clear non-obvious constraints beat long explanations every time.

Testing before you publish

Before you publish, run the skill through at least 3 realistic prompts, such as “find failed webhooks in the last 24 hours,” “look up the account behind this invoice ID,” and “summarize usage for the top 10 enterprise customers this week.” Check whether the agent picks the right endpoint, handles empty responses, and reports uncertainty honestly.

If you want a lightweight checklist, verify these 8 items:

1. The description contains realistic trigger phrases.
2. The skill cannot perform writes unless that behavior is explicitly intended.
3. All auth details are externalized.
4. Pagination behavior is documented.
5. 429, 401, 404, and 5xx behaviors are covered.
6. Output defaults to summary first.
7. At least one script or reference file handles repetitive detail.
8. The gotchas section reflects real failures, not generic advice.

Frequently asked questions

What is the fastest way to make an API skill more reliable?

Add a real gotchas section, document pagination, and define summary-first output. Those three fixes catch a surprising amount of breakage.

Should a data fetching skill ever support write actions?

Only if you separate reads from writes clearly and add explicit guardrails. For most teams, a read-only skill is the safer starting point.

Do I need scripts, or can everything live in SKILL.md?

You can start in one file, but scripts help once auth flows, request signing, or repeated parsing steps become tedious or error-prone.

Conclusion

A good data fetching skill does not win by being clever. It wins by being dependable. It tells the agent when to activate, how to authenticate, which endpoint to choose, how to page through results, and how to explain what came back without hiding uncertainty.

If you are building one this week, keep the first version narrow. Make it answer 2 or 3 recurring questions well. Then grow it from real failures, not imagined ones. That is how API skills become durable enough to publish, share, and trust.

For more patterns, browse the ASE marketplace, review the official Anthropic skills documentation, and study the AgentSkills standard before you publish your next integration.