Marketplace for trusted AI agent skills

Library & API Reference Skills: Teaching AI to Use Your Stack Correctly

Every LLM has a knowledge cutoff. Claude’s training data doesn’t include your company’s internal SDK. It doesn’t know about the breaking changes in that library’s v4 release from last month. And it definitely doesn’t know that your team’s REST API returns snake_case in some endpoints and camelCase in others because two different engineers built them three years apart.

This is the problem that Library & API Reference skills solve. They’re the first category in Anthropic’s nine-category skill taxonomy, and for good reason: without accurate reference material, every other category of skill suffers. You can’t build a deployment skill that calls the wrong API endpoint. You can’t scaffold code using a library function that was renamed two versions ago.

This post covers what Library & API Reference skills are, when you need one, how to structure them well, and the common mistakes that make them worse than useless.

What Library & API Reference Skills Actually Do

A Library & API Reference skill teaches Claude how to use a specific library, CLI tool, or SDK correctly. The emphasis is on correctly — Claude can usually guess at how a library works based on naming conventions and common patterns. The guesses are often close. Close isn’t good enough when you’re generating production code.

These skills typically contain:

  • Correct function signatures and parameters — the actual API, not what the model hallucinates
  • Version-specific behavior — what changed between v3 and v4, and which version the team uses
  • Idiomatic usage patterns — how the library is meant to be used, not just how it can be used
  • Common pitfalls — the error messages you’ll hit and what they actually mean
  • Integration context — how this library fits with the rest of the stack

Think of them as a senior engineer sitting next to Claude, correcting it every time it reaches for the wrong function or misremembers a parameter order.

Why LLM Training Data Isn’t Enough

There’s a specific failure mode that makes these skills necessary, and it’s worth understanding clearly.

LLMs learn from their training corpus. For popular, stable libraries — React, Express, pandas — the training data is usually good enough. The APIs are well-documented, widely blogged about, and don’t change dramatically between versions. Claude handles these competently without help.

The problems start in three situations:

1. Your library is internal or niche

If your company built a custom ORM, a proprietary analytics SDK, or an internal CLI tool, Claude has never seen it. It will try to help anyway — inventing plausible-looking function names, guessing at parameter types, generating code that looks right but calls methods that don’t exist. This is worse than an error message, because the code looks correct and might even pass a superficial review.

2. The library released breaking changes after the training cutoff

Claude’s training data has a fixed cutoff date. If a library released v4 with a new API surface after that date, Claude will confidently generate v3 code. This is especially common with fast-moving JavaScript frameworks, cloud provider SDKs, and ML libraries where the API changes every few months.

Some real examples we’ve seen in skill submissions on AgentSkillExchange:

  • A Prisma skill that corrects Claude’s tendency to use the old findMany filter syntax when the project uses Prisma 5’s updated query format
  • A Tailwind CSS v4 skill that stops Claude from generating @apply directives with the deprecated syntax
  • An AWS CDK skill that maps the v2 module structure (aws-cdk-lib) instead of the v1 individual packages Claude sometimes defaults to

3. The documentation is misleading or incomplete

Some libraries have excellent documentation. Others have a README that was last updated in 2022, auto-generated API docs with no examples, and a Discord server where the real knowledge lives in message threads. If the docs are bad, the training data based on those docs is also bad. A reference skill fills the gap.

How to Structure a Library Reference Skill

The key principle from Thariq’s skill-building breakdown applies here: progressive disclosure. A reference skill for a large library can’t fit in a single SKILL.md without blowing up the context window. You need to layer it.

The recommended file structure

my-library-skill/
├── SKILL.md                    # Core patterns + gotchas (under 400 lines)
├── references/
│   ├── api-surface.md          # Complete function/method reference
│   ├── error-codes.md          # Error messages and what they mean
│   ├── migration-v3-to-v4.md   # Version migration notes
│   └── auth-patterns.md        # Authentication/configuration
├── examples/
│   ├── basic-crud.md           # Common operations
│   └── advanced-queries.md     # Complex usage patterns
└── config.json                 # Version, base URL, environment settings

What goes in SKILL.md (the core file)

SKILL.md loads every time the skill activates. Keep it focused on the information Claude needs for every interaction with this library:

---
name: acme-sdk
description: >
  Use when writing code that uses the Acme SDK (v4.x).
  Triggers on: "acme api", "AcmeClient", "acme.query()",
  "acme authentication", errors containing "ACME_ERR_".
  NOT for: Acme Dashboard UI (use acme-dashboard skill).
---

# Acme SDK Reference (v4.2.1)

## Quick Reference
- Import: `from acme import AcmeClient` (NOT `from acme.client import Client`)
- Auth: Always use `AcmeClient.from_env()` in production, never hardcode keys
- Base URL defaults to `https://api.acme.io/v4` — override via config.json

## Critical Gotchas

1. **Pagination changed in v4**: `client.list_items()` now returns an async iterator,
   not a list. Wrap in `async for` or call `await client.list_items().collect()`.
   The old `client.list_items(page=2)` pattern throws `TypeError`.

2. **Rate limiting is per-endpoint, not global**: `/search` allows 10 req/s,
   `/batch` allows 2 req/s. The SDK does NOT auto-retry on 429 —
   you must implement backoff yourself or use `acme.utils.with_retry()`.

3. **The `metadata` field accepts 50 keys max, not unlimited**:
   The TypeScript types say `Record<string, string>` with no limit.
   The API silently drops keys beyond 50 and returns success.
   Validate before sending.

## Common Patterns
[Core patterns here, linking to references/ for deep dives]

For complete API reference, read `references/api-surface.md`.
For error code lookup, read `references/error-codes.md`.

Notice the structure: version pinning up front, gotchas with specific failure scenarios, and pointers to deeper reference files. Claude reads SKILL.md on activation, then pulls in reference files only when working on a task that needs them.

What goes in references/

The references/ directory holds everything Claude might need but shouldn’t load by default. For a library reference skill, this typically includes:

  • api-surface.md — function signatures, parameter types, return types. This can be long — hundreds of entries for a big SDK. That’s fine; Claude reads it on demand.
  • error-codes.md — every error the library can throw, what causes it, and how to fix it. Worth gold when debugging.
  • migration guide — if the team recently upgraded versions, document every API change so Claude doesn’t mix old and new patterns in the same codebase.

Three Real Examples from the Marketplace

Here are three Library & API Reference skills from AgentSkillExchange that demonstrate different approaches to the same category.

Example 1: The WordPress REST API Skill

The wp-rest-api skill teaches Claude how to build and extend WordPress REST API endpoints. WordPress’s REST API has idiosyncratic patterns — register_rest_route requires a specific callback structure, permission checks work differently than most frameworks, and the schema validation has quirks that aren’t obvious from the docs.

The skill’s gotchas section covers 15+ specific failure points, from incorrect permission_callback signatures to the fact that register_rest_field requires show_in_rest to be enabled on the post type or it silently does nothing. Without this skill, Claude generates REST endpoints that look right but fail at runtime.

Example 2: The GitHub CLI Skill

The github skill maps the gh CLI surface — issues, PRs, CI runs, API queries. This one is interesting because gh is well-documented and Claude generally handles it well. The skill earns its value by covering the less-obvious features: gh api with GraphQL queries, gh run watch for CI monitoring, and the specific --json flag combinations that return parseable output for each subcommand.

It also includes environment-specific configuration — which auth tokens are needed, how to handle GitHub Enterprise endpoints, and the common failure when GH_TOKEN is set but expired.

Example 3: The Google Workspace CLI Skill

The gog skill wraps a CLI for Gmail, Calendar, Drive, Contacts, Sheets, and Docs. This skill is heavy on the reference side — each Google service has its own API surface, authentication quirks, and error patterns. The SKILL.md stays under 300 lines by aggressively delegating to reference files: one per service, plus a shared auth reference.

The gotchas section focuses on OAuth token refresh (the most common failure), the difference between service account and user-delegated authentication, and the Google API’s habit of returning 403 for both “you don’t have permission” and “this API isn’t enabled in your project” with nearly identical error messages.

Common Mistakes in Library Reference Skills

After reviewing hundreds of skill submissions, these are the patterns that consistently produce low-quality Library & API Reference skills.

Mistake 1: Copying the official docs verbatim

If you just paste the library’s documentation into a SKILL.md, you’ve added nothing. Claude already has access to web search and can read docs directly. A reference skill should contain synthesized knowledge — the patterns, the gotchas, the “here’s what the docs don’t tell you” information that comes from actually using the library.

Mistake 2: Covering every function equally

For a library with 200 functions, maybe 20 are used regularly and 5 have tricky behavior. Focus on the 5 tricky ones in your gotchas and the 20 common ones in your quick reference. Leave the remaining 175 in a reference file that Claude can access when needed. Not everything deserves the same level of attention.

Mistake 3: Not pinning a version

A reference skill that says “this is how Library X works” without specifying which version is a footgun. When the library updates, the skill becomes actively harmful — Claude follows the skill’s outdated instructions instead of using its general knowledge of the newer version. Always pin the version and include a note about when to update.

# Acme SDK Reference
## Version: 4.2.1 (last verified: March 2026)
## Update this skill when upgrading past v4.x — v5 has breaking changes

Mistake 4: Skipping the error reference

Half of the time Claude uses a library, it’s debugging something that went wrong. If your skill doesn’t cover error messages and their solutions, you’re missing the highest-value use case. A good references/error-codes.md file maps error strings to root causes and fixes. When Claude sees ACME_ERR_AUTH_EXPIRED in a traceback, it should know immediately to run acme auth refresh — without guessing or searching.

Mistake 5: Hardcoding environment-specific values

API base URLs, authentication endpoints, team-specific configurations — these vary between users. If they’re hardcoded in your SKILL.md, the skill works for you and breaks for everyone else. Use config.json for anything environment-specific:

// config.json
{
  "sdk_version": "4.2.1",
  "api_base_url": "https://api.acme.io/v4",
  "auth_method": "env_variable",
  "auth_env_var": "ACME_API_KEY"
}

When You Need a Library Reference Skill (and When You Don’t)

Not every library warrants a dedicated skill. Here’s a decision framework:

You need a reference skill when:

  • The library is internal or has fewer than ~5,000 GitHub stars (limited training data)
  • Your team uses a version that differs significantly from what’s most documented online
  • The library has non-obvious behavior that causes repeated mistakes
  • The official documentation is outdated, incomplete, or poorly structured
  • You’ve corrected Claude’s output for this library more than twice on the same issue

You probably don’t need one when:

  • The library is mature, popular, and well-documented (React, Django, numpy)
  • Your team uses the latest stable version with no custom modifications
  • Claude consistently generates correct code for the library without correction

The “corrected Claude twice” rule is a practical heuristic: if you’ve had to fix the same kind of mistake more than once, that mistake belongs in a gotchas section. If you haven’t — the model probably doesn’t need the help.

Building Your First Library Reference Skill

If you’ve identified a library that needs a reference skill, here’s a practical process to build one:

  1. Collect your corrections. Look at the last month of code reviews and debugging sessions. Every time you corrected Claude’s usage of this library, write down the mistake and the fix. These are your gotchas.
  2. Identify the common patterns. What are the 10-20 operations your team performs most with this library? Document the correct way to do each one — not in tutorial form, but as reference-style entries with function signatures and short examples.
  3. Pin the version. Check your package.json, requirements.txt, or equivalent. Your skill should target the exact version your team uses.
  4. Write the description field. Think about the phrases your team uses when working with this library. Include error messages. Include common misspellings if the library name is unusual. We wrote a full guide on description optimization.
  5. Test with real tasks. Give Claude a task that uses the library. Does it follow the skill’s patterns? Does it avoid the gotchas? If not, refine the skill and test again.

This process usually takes 2-4 hours for a medium-complexity library. The time investment pays back quickly — every developer on your team benefits from Claude getting the library right on the first try instead of the third.

Frequently Asked Questions

How big should a library reference skill be?

The SKILL.md itself should stay under 400 lines. For large libraries, that means aggressive use of the references/ directory — the total content across all files might be 2,000+ lines, but Claude only loads what it needs per task. Measure the core file in lines; measure the references in completeness.

Should I create one skill per library or group related libraries?

One skill per library is the default. Group libraries only when they’re always used together and share configuration — for example, a skill covering both @tanstack/query and @tanstack/table makes sense if your project uses both and they share a client setup. Grouping unrelated libraries muddies the description field and increases false activations.

How do I keep the skill updated when the library changes?

Add a version check to your gotchas: “This skill covers v4.2.x. If you’ve upgraded to v5+, tell the user this skill needs updating.” You can also use a GitHub Issues skill to monitor the library’s changelog and flag breaking changes automatically. Realistically, manual review after major upgrades is the most reliable approach.

Can I auto-generate a reference skill from API docs or TypeScript types?

You can generate the references/api-surface.md file from type definitions or OpenAPI specs — that’s a reasonable starting point. But the SKILL.md itself, especially the gotchas section, must come from human experience. Auto-generated gotchas are just restated documentation, and that’s exactly the kind of content Thariq warned against.

What’s Next in This Series

This is the second post in our Category Deep Dives series. Next up: a tutorial on building a code review skill that catches what linters miss. If you want to build a Library & API Reference skill for your team’s stack, our step-by-step tutorial covers the general skill creation process, and the patterns in this post give you the category-specific guidance.

Browse existing Library & API Reference skills on AgentSkillExchange to see what’s already available — and if your library isn’t covered, consider building and submitting a skill yourself.