Curated API-focused Agent Skill examples (non-MCP)

api-skill-examples.md

🤖 Created by Cursor / gpt-5.2-xhigh, edited by me

API-focused Agent Skill examples

Short, high-quality set of non-MCP skills that primarily act as API usage/docs for real products (auth, endpoints/operations, examples, rate limits, troubleshooting):

• Hugging Face API tool-builder: explicitly lists Hub API endpoints and teaches how to query Hugging Face’s OpenAPI spec safely (via jq), with clear auth guidance (HF_TOKEN).

  • Source: huggingface/skills hugging-face-tool-builder/SKILL.md
  • Explicitly says "DO NOT ATTEMPT to read https://huggingface.co/.well-known/openapi.json directly as it is too large to process."

• Hugging Face CLI skill: “API via CLI” style, with a tight command reference and common workflows (download/upload/repos/jobs/endpoints).

  • Source: huggingface/skills hugging-face-cli/SKILL.md

• Raindrop.io REST API skill: strong “API doc in a skill” pattern (auth header, base URL, endpoint tables, rate limits, helper script usage).

  • Source: gmickel/raindrop-skill SKILL.md

• Spotify Web API skill: full API integration skill (OAuth, playlist/search/playback workflows) + pushes heavy detail into references/ (e.g. references/api_reference.md).

  • Source: fabioc-aloha/spotify-skill spotify-api/SKILL.md

• GitHub API via gh api skill (SkillMD): very concrete REST + GraphQL examples, including thread resolution workflows and endpoint references.

  • Source: SkillMD “Using GitHub API with gh CLI”

• Stripe API best-practices skill (official): concise “what primitives to use / avoid” guidance, latest API version pin, and links to canonical Stripe docs.

  • Source: stripe/ai stripe-best-practices/SKILL.md

• Stripe integration helper skill (SkillMD): practical Next.js integration snippets (Checkout Sessions, webhook verification, customer portal) + test card/Stripe CLI notes.

  • Source: SkillMD “stripe”

• GitHub PR comment workflow skill (Codex curated): smaller, but useful as an example of a “product API workflow” skill that delegates to scripts and forces auth verification first.

  • Source: openai/skills gh-address-comments/SKILL.md

What makes these good “API skills” (checklist to copy)

• Frontmatter triggers: name + a trigger-rich description (“use when…”), so the agent activates the skill at the right time.
• Prereqs & auth: env vars, tokens, scopes, login checks, and a clear “verify auth first” step.
• API surface summary: base URL, core resources, endpoint/operation list, and rate limits.
• Copy-paste workflows: 2–5 common tasks expressed as commands/snippets.
• Troubleshooting: common errors + fixes (missing scopes, 401s, rate limiting, pagination).
• Progressive disclosure: keep SKILL.md compact; move deep reference into references/.

Minimal SKILL.md template (copy/paste)

---
name: product-api
description: Use when integrating with ProductX API (auth, endpoints, rate limits, troubleshooting). Triggers: “ProductX API”, “create <resource>”, “list <resource>”, “webhook”, “401”, “rate limit”.
---

# ProductX API

## Prereqs
- Env vars: `PRODUCTX_TOKEN`, `PRODUCTX_BASE_URL`
- Verify auth:
  - `curl -H "Authorization: Bearer $PRODUCTX_TOKEN" "$PRODUCTX_BASE_URL/v1/me"`

## Base URL + Auth
- Base URL: `https://api.productx.com/v1`
- Header: `Authorization: Bearer $PRODUCTX_TOKEN`

## API surface
- Resources: `widgets`, `orders`, `customers`
- Rate limits: `X-RateLimit-*` headers

## Common workflows
1. Create <resource>
2. List/paginate <resource>
3. Update <resource>
4. Webhook verify/parse (if applicable)

## Troubleshooting
- 401: token/scope
- 403: permissions
- 429: backoff and retry
- Pagination: cursors vs offset

Where to put it

• Under .agents/skills/<your-product-api>/SKILL.md, plus a references/ folder for endpoint details.