Claude Apps and API Skills

Why the surface matters

The same skill idea travels across Claude products, but installation is not universal. A local folder path matters in Claude Code. A UI upload matters in Claude.ai. An API upload and identifier matter in a Messages API workflow.

When documenting a skill for users, say which surface you tested. "Works as a Claude Code project skill" is more useful than a vague "works with Claude" claim.

Claude apps

In the Claude apps, skills are aimed at end-user workflows such as files, documents, design artifacts, and custom organizational procedures. Enable them in Settings; they are available on Pro, Max, Team, and Enterprise, and Team or Enterprise admins must switch Skills on for the organization before individual users see them. The Help Center is the right source for upload instructions and product limitations because those rules change faster than the portable file format.

Activation is automatic rather than manual. Claude picks the matching skill from the task and shows it in its chain of thought, which is a useful debugging signal when a skill fires at the wrong time. If the workflow needs local repo access, shell commands, or codebase-specific automation, Claude Code may be the better surface.

Claude API

In the API, a skill is part of an application workflow. Skills can be attached to Messages API requests, and the /v1/skills endpoint gives programmatic control over custom skill versioning and management; the Claude Console covers the same create, view, and upgrade steps interactively. Skills on this surface require the code execution tool beta, which provides the sandbox they run in — so a skill is not a drop-in addition to an existing request if that tool is not enabled.

Pick the model for the job rather than assuming the skill compensates. Opus 5 is the general default, Fable 5.1 suits long-horizon agentic runs that load several bundled references, and Sonnet 5 is the balance choice for high-volume skill calls. API usage also raises concerns the skill text cannot solve: package versioning, tenant isolation, file retention, audit logs, and explicit testing around tool calls or generated outputs.

Portability expectations

Portable skill design still helps even when product-specific packaging differs. A clear SKILL.md, named references, deterministic scripts, and small assets are easier to adapt across surfaces than a giant prompt pasted into one product.

If a skill depends on a Claude Code-only path, a local executable, or a private service, document that dependency in the first screen of the skill so API and Claude.ai users do not assume it is portable.

FAQ