Claude API Skill Review: The Official Reference Skill Is Also a Context Trap
skills/claude-api/SKILL.md is not a small hint file. In today's clone of anthropics/skills, it is 75,707 bytes before the agent reads a single reference document. The full claude-api skill directory I inspected is 973,337 bytes across 68 files. Using the simple file-size estimate this column uses — bytes ÷ 4 — that is roughly 243,334 tokens if the whole local source set is loaded. That's not a bill from a run. It's arithmetic from bytes on disk.
The interesting part is the tension: this is the most authoritative Claude API skill you can install, and the public issue tracker says its trigger and loading behavior can hurt exactly the users who need authoritative docs. That's a better story than another "official skill is useful" paragraph.
TL;DR / quotable facts
- The
claude-apiskill'sSKILL.mdis 75,707 bytes, which estimates to about 18,927 tokens by the bytes ÷ 4 rule. - The inspected
skills/claude-apisource set is 973,337 bytes across 68 files, or about 243,334 estimated tokens if loaded in full. - The
anthropics/skillsrepository had 171,582 stars, 20,383 forks, 1,172 open issues, and 20 SKILL.md files when re-checked on August 26, 2026. - The repository API reports license NONE, but the
claude-apiskill directory itself includes an Apache-2.0 LICENSE.txt. - The strongest public complaint is GitHub issue #1487, where a user reported a 624,401-character eager payload and a fresh session failing with "Prompt is too long."
What the skill actually says
The skill is a Claude API reference pack. It covers model IDs, SDK examples, streaming, tool use, managed agents, caching, token counting, migration, and auth. It explicitly tells the agent not to trust memory when writing Claude API code:
"Never guess SDK usage. Function names, class names, namespaces, method signatures, and import paths must come from explicit documentation."
It also forces a default opinion:
"Unless the user requests otherwise: For the Claude model version, please use Claude Opus 5..."
The safety gate in the frontmatter is where the review gets less flattering. The trigger says to load the skill whenever the prompt names Claude, Anthropic, Opus, Sonnet, Haiku, and several model-id shapes. The skip clause tries to avoid non-Anthropic provider work with a grep over the project. That sounds careful until you remember this skill is nearly a megabyte of local reference material and that broad trigger words show up in prose, changelogs, config files, and docs.
Security gate: what I read before reviewing it
I read every file in skills/claude-api. There are 68 text files: markdown references plus LICENSE.txt. I found no bundled executable script in this skill directory. There are many code samples, cURL examples, auth notes, environment-variable examples, and credential-handling instructions, because the skill teaches API usage. That is different from a skill that ships a helper script and asks the agent to run it. Still, teams should treat it as high influence: it can steer model choice, auth style, API surface, and migration behavior.
What it costs you in context
This review does not run the skill through our API and does not publish measured traffic costs. The context estimate here is only:
file bytes ÷ 4 ≈ estimated tokens
By that rule, SKILL.md alone is 75,707 ÷ 4 ≈ 18,927 tokens. The whole inspected directory is 973,337 ÷ 4 ≈ 243,334 tokens. The biggest individual file is shared/model-migration.md at 175,868 bytes, or about 43,967 estimated tokens. That file is useful when you are actually migrating code. It is silly baggage when you are editing a README line that merely mentions "Opus."
| File | Bytes | Estimated tokens (bytes ÷ 4) |
|---|---|---|
LICENSE.txt | 11,345 B | ~2,836 |
SKILL.md | 75,707 B | ~18,927 |
csharp/claude-api/README.md | 18,448 B | ~4,612 |
csharp/claude-api/batches.md | 413 B | ~103 |
csharp/claude-api/files-api.md | 679 B | ~170 |
csharp/claude-api/streaming.md | 793 B | ~198 |
csharp/claude-api/tool-use.md | 6,022 B | ~1,506 |
curl/examples.md | 9,201 B | ~2,300 |
curl/managed-agents.md | 8,761 B | ~2,190 |
go/claude-api/README.md | 7,780 B | ~1,945 |
go/claude-api/files-api.md | 713 B | ~178 |
go/claude-api/streaming.md | 1,039 B | ~260 |
go/claude-api/tool-use.md | 8,435 B | ~2,109 |
go/managed-agents/README.md | 18,949 B | ~4,737 |
java/claude-api/README.md | 11,322 B | ~2,830 |
java/claude-api/files-api.md | 969 B | ~242 |
java/claude-api/streaming.md | 661 B | ~165 |
java/claude-api/tool-use.md | 9,542 B | ~2,386 |
java/managed-agents/README.md | 16,956 B | ~4,239 |
php/claude-api/README.md | 6,123 B | ~1,531 |
php/claude-api/batches.md | 447 B | ~112 |
php/claude-api/files-api.md | 241 B | ~60 |
php/claude-api/streaming.md | 682 B | ~170 |
php/claude-api/tool-use.md | 8,099 B | ~2,025 |
php/managed-agents/README.md | 13,526 B | ~3,382 |
python/claude-api/README.md | 19,926 B | ~4,982 |
python/claude-api/batches.md | 5,586 B | ~1,396 |
python/claude-api/files-api.md | 4,373 B | ~1,093 |
python/claude-api/sdk-upgrade.md | 28,841 B | ~7,210 |
python/claude-api/streaming.md | 6,548 B | ~1,637 |
python/claude-api/tool-use.md | 19,419 B | ~4,855 |
python/managed-agents/README.md | 10,357 B | ~2,589 |
ruby/claude-api/README.md | 4,481 B | ~1,120 |
ruby/claude-api/streaming.md | 235 B | ~59 |
ruby/claude-api/tool-use.md | 1,063 B | ~266 |
ruby/managed-agents/README.md | 10,460 B | ~2,615 |
shared/agent-design.md | 8,600 B | ~2,150 |
shared/anthropic-cli.md | 16,210 B | ~4,052 |
shared/claude-platform-on-aws.md | 3,878 B | ~970 |
shared/error-codes.md | 12,182 B | ~3,046 |
shared/live-sources.md | 19,837 B | ~4,959 |
shared/managed-agents-api-reference.md | 33,634 B | ~8,408 |
shared/managed-agents-client-patterns.md | 10,881 B | ~2,720 |
shared/managed-agents-core.md | 32,934 B | ~8,234 |
shared/managed-agents-environments.md | 12,105 B | ~3,026 |
shared/managed-agents-events.md | 22,908 B | ~5,727 |
shared/managed-agents-memory.md | 10,006 B | ~2,502 |
shared/managed-agents-multiagent.md | 25,099 B | ~6,275 |
shared/managed-agents-onboarding.md | 10,460 B | ~2,615 |
shared/managed-agents-outcomes.md | 7,286 B | ~1,822 |
shared/managed-agents-overview.md | 12,635 B | ~3,159 |
shared/managed-agents-scheduled-deployments.md | 8,411 B | ~2,103 |
shared/managed-agents-self-hosted-sandboxes.md | 10,181 B | ~2,545 |
shared/managed-agents-tools.md | 23,108 B | ~5,777 |
shared/managed-agents-webhooks.md | 11,392 B | ~2,848 |
shared/model-migration.md | 175,868 B | ~43,967 |
shared/models.md | 12,146 B | ~3,036 |
shared/platform-availability.md | 5,945 B | ~1,486 |
shared/prompt-audit.md | 32,954 B | ~8,238 |
shared/prompt-caching.md | 16,291 B | ~4,073 |
shared/token-counting.md | 1,604 B | ~401 |
shared/tool-use-concepts.md | 33,807 B | ~8,452 |
typescript/claude-api/README.md | 15,179 B | ~3,795 |
typescript/claude-api/batches.md | 2,592 B | ~648 |
typescript/claude-api/files-api.md | 2,259 B | ~565 |
typescript/claude-api/streaming.md | 5,843 B | ~1,461 |
typescript/claude-api/tool-use.md | 19,116 B | ~4,779 |
typescript/managed-agents/README.md | 9,844 B | ~2,461 |
What the community reports
Public discussion outside GitHub is thin. HN Algolia returned no direct stories for the claude-api skill and no direct story for the repo URL plus this skill name. The useful evidence is the repository's own issue tracker, where the complaints are concrete and reproducible.
| Source | Date | What was reported | Link |
|---|---|---|---|
| GitHub issue #1487 | 2026-07-27 | A user reported Skill(claude-api) injecting a 624,401-character payload, about 156k tokens by chars ÷ 4, after a prompt that only mentioned model names in prose; the next turn failed with "Prompt is too long." | issue |
| xg-gh-25 comment on #1487 | 2026-07-27 | The commenter called the pattern an anti-pattern for progressive disclosure and said their own pipeline moved to a two-phase index plus on-demand reference loading, with reported 12× cache-hit improvement. | comment |
| GitHub issue #881 | 2026-04-07 / 2026-06-13 update | The original report said the frontmatter description is truncated in Claude Code listings; a later comment reported the YAML-parsed description at 1,068 characters, above a 1,024-character limit enforced by GitHub Copilot CLI. | issue |
| GitHub issue #1603 | 2026-08-17 | A contributor checked model IDs listed in shared/models.md against the live API and reported five rows returning 404, including one listed under "Legacy Models (still active)." | issue |
| GitHub issue #1624 | 2026-08-21 | The skip grep uses unanchored cohere, so ordinary words like "coherent" can make the skill skip in projects with no Cohere integration; the same report says the grep names Gemini in prose but misses gemini in the pattern. | issue |
The dissent is also worth saying plainly. The skill exists because API code rots fast. Model IDs change, SDKs shift, thinking parameters get renamed, and old examples on the internet remain indexed forever. A large curated reference can stop the agent from writing stale SDK calls. The issue is not that the reference exists. The issue is loading and triggering: a reference this large needs sharp routing and lazy reads.
How to install it
The repository README gives the Claude Code route through the plugin marketplace. I verified these commands from the README in this run:
/plugin marketplace add anthropics/skills
/plugin install claude-api@anthropic-agent-skillsThe README also says the repository can be installed as document-skills or example-skills, and that Claude.ai paid plans already include the example skills. For this review, the relevant direct install command is the claude-api plugin above.
Where it earns its keep
Use this skill when the task is genuinely Claude API work: migrating SDK versions, implementing streaming, picking the right tool-use pattern, checking model IDs, or updating code across Python, TypeScript, Java, Go, Ruby, C#, PHP, and raw HTTP. The skill has real depth. The recent commit history backs that up: the SKILL.md path was updated on August 21 for a Python SDK 0.x to 1.x upgrade guide, August 13 for a prompt-audit subcommand, and August 7 for Managed Agents launch updates. This is not abandoned markdown.
Where it does not
Do not treat it as a harmless always-on Claude keyword skill. The trigger is too broad for the payload. A bare mention of "Opus" or "Sonnet" should not summon a giant API reference when the user is editing prose. The unanchored provider grep is also a real bug: a project that says "coherent state" can look like it mentions Cohere. That is the kind of tiny routing mistake that wastes context and makes users distrust skills.
My verdict: install it if you write Claude API code often, but keep an eye on when it triggers. For teams building their own skills, the lesson is sharper: big reference packs need a small stable index, narrow activation rules, and on-demand file reads. The official repo shows both the value of skills and the failure mode.
FAQ
Is the claude-api skill open source?
The repository API reports no repository-level SPDX license, but the skills/claude-api directory includes an Apache-2.0 LICENSE.txt. The article credits the directory license rather than guessing at the whole repo.
Did KissAPI run this skill and measure token or dollar cost?
No. This review does not run the skill through our API. The context numbers are estimates from file size: bytes ÷ 4.
What is the main criticism?
The skill is too large for broad keyword triggers. Public GitHub issues report eager loading, description-length limits, stale model rows, and a skip grep that matches ordinary words like "coherent."
Should I uninstall it?
Not if you write Claude API integrations. It is useful reference material. I would avoid letting it trigger on casual prose mentions, and I would prefer a future version that loads a small index first and reference docs only when needed.