[DOCS] Major Inconsistency in `SKILL.md` `allowed-tools` support between Claude Code CLI and Agent SDK

Documentation Type

Unclear/confusing documentation

Documentation Location

URL: https://platform.claude.com/docs/en/agent-sdk/skills (Section: Tool Restrictions)

Section/Topic

The "Tool Restrictions" section under "Agent Skills in the SDK."

Current Documentation

"The allowed-tools frontmatter field in SKILL.md is only supported when using Claude Code CLI directly. It does not apply when using Skills through the SDK. When using the SDK, control tool access through the main allowedTools option in your query configuration."

What's Wrong or Missing?

The documentation describes a major functional "broken logic" gap between the CLI and the SDK as if it were intended behavior. This creates several high-priority issues:

• Broken Reusability: The platform-wide documentation for Agent Skills defines them as "reusable, filesystem-based resources." This discrepancy means a Skill authored for Claude Code CLI is not fully portable to an SDK-based application without manual intervention.
• Security Risk: A developer may author a Skill with strict allowed-tools (e.g., restricting to Read only for a sensitive directory) assuming the Skill format itself enforces safety. If that Skill is then imported into an SDK project, the restrictions fail silently, granting the Skill whatever permissions the parent SDK session has (potentially Bash or Write).
• Functional Fragility: If a Skill's logic depends on specific tools being auto-approved via the frontmatter to reduce user friction, it will break or trigger unexpected canUseTool callbacks when run via the SDK.

Suggested Improvement

While this is primarily a request for architectural harmony, the documentation needs to be much more explicit about the risks.

Suggested Text Change:

Warning: Security and Portability Gap Unlike the Claude Code CLI, the Agent SDK ignores the allowed-tools field in SKILL.md frontmatter. CRITICAL: If you are importing a Skill designed for the CLI into an SDK project, you MUST manually replicate all tool restrictions in your ClaudeAgentOptions (Python) or Options (TypeScript) using the allowedTools parameter. Failure to do so will result in the Skill having broader permissions than its author intended, which poses a security risk when processing untrusted content.

Impact

High - Prevents users from using a feature

Additional Context

• Links to related documentation: The Agent Skills Best Practices guide explicitly encourages the use of allowed-tools for "security-sensitive workflows." The SDK documentation contradicts this best practice.
• Examples from other projects: In the Model Context Protocol (MCP) ecosystem, which Claude Code utilizes, configuration is expected to be respected by the client. Having the SDK act as a client that ignores its own specialized resource format (SKILL.md) is a significant outlier in agentic design.
• Severity: Major. This impacts any enterprise user attempting to standardize agent behavior across CLI (for developers) and SDK (for production automation).