[DOCS] `/claude-api` skill docs omit agent design guidance topics

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/skills

Section/Topic

Bundled skills table (/claude-api entry)

Current Documentation

The code.claude.com skills docs currently describe /claude-api as:

Load Claude API reference material for your project's language (Python, TypeScript, Java, Go, Ruby, C#, PHP, or cURL) and Agent SDK reference for Python and TypeScript. Covers tool use, streaming, batches, structured outputs, and common pitfalls. Also activates automatically when your code imports anthropic, @anthropic-ai/sdk, or claude_agent_sdk

The dedicated Claude API skill page currently says:

The skill uses progressive disclosure to keep context efficient: Claude loads only the documentation relevant to your project's language and the specific task at hand (tool use, streaming, batches, and so on), rather than loading everything at once. - Tool use guidance: Language-specific examples and conceptual foundations for function calling - Streaming patterns: Implementation details for building chat UIs and handling incremental display - Batch processing: Offline batch processing at 50% cost - Agent SDK reference: Installation, built-in tools, permissions, MCP integration, and common patterns (Python and TypeScript) - Common pitfalls: Detailed guidance on avoiding frequent mistakes when integrating with the API

What's Wrong or Missing?

Changelog v2.1.91 says:

Improved /claude-api skill guidance for agent design patterns including tool surface decisions, context management, and caching strategy

Current docs do not mention those newly improved guidance areas anywhere in the /claude-api descriptions on code.claude.com or on the dedicated platform skill page.

Users can currently discover that /claude-api helps with tool use, streaming, batches, structured outputs, and common pitfalls, but they are not told that the skill now also covers:

• tool surface decisions when designing agent tools
• context management guidance for long-running agents
• caching strategy guidance

That makes the new v2.1.91 skill improvements hard to discover for users who rely on the docs to decide when to invoke /claude-api.

Suggested Improvement

Update the /claude-api descriptions on the Claude Code skills pages and on the dedicated platform skill page to explicitly mention the new agent-design guidance areas added in v2.1.91.

A concise fix would be to add a sentence or bullet such as:

Also covers agent design patterns such as choosing an effective tool surface, managing context for long-running agents, and planning prompt-caching/caching strategies.

It would also help to add cross-references to the existing platform docs that cover those topics in depth.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/skills | 28 | Bundled /claude-api description omits the new agent-design guidance topics |
| https://code.claude.com/docs/en/slash-commands | 28 | Mirrored bundled-skill entry has the same incomplete description |
| https://platform.claude.com/docs/en/agents-and-tools/agent-skills/claude-api-skill | 11-23 | Dedicated skill page lists current coverage but does not mention tool surface decisions, context management, or caching strategy |

Total scope: 3 pages affected

Relevant existing docs to cross-reference:

| Page | Context |
|------|---------|
| https://platform.claude.com/docs/en/agents-and-tools/tool-use/define-tools | Existing tool-design guidance for tool surface decisions |
| https://platform.claude.com/docs/en/build-with-claude/context-windows | Existing context-management guidance |
| https://platform.claude.com/docs/en/build-with-claude/prompt-caching | Existing caching-strategy guidance |

Source: Changelog v2.1.91

Changelog entry: Improved /claude-api skill guidance for agent design patterns including tool surface decisions, context management, and caching strategy