Claude Skills: claude.ai vs Claude Code vs API (2026)
A. Frans
Published November 9, 2026
Table of Contents
- 01The description limit is the first thing to break
- 02Frontmatter: six fields travel, the rest don't
- 03Runtime: the same script can fail three different ways
- 04Claude Code: folders on disk
- 05claude.ai: ZIP files and plan rules
- 06Claude API: versions and workspaces
- 07Syncing: one-way, and only sometimes
- 08Security notes before you upload anyone else's skill
- 09What we'd do
- 10Frequently Asked Questions
One SKILL.md gets up to 1,536 characters of trigger text in Claude Code, 1,024 through the Skills API and, if the Help Center is current, 200 on claude.ai. Network access runs from unrestricted to none. Frontmatter that loads fine on your laptop can make an upload fail outright.
Anthropic calls all of these Agent Skills, and the core format is shared, so people assume a skill built in one place will work in the others. It often will, after some editing. Below is what changes on each surface, so you can write the skill once.
Everything here comes from Anthropic's Agent Skills overview, the Claude Code skills reference, the API skills guide and the Claude Help Center, read on November 9, 2026. Where those pages disagree, we point it out.
| claude.ai | Claude Code | Claude API | |
|---|---|---|---|
| How a skill gets there | ZIP upload in Customize > Skills | Folder on disk | Upload to /v1/skills |
| Pre-built document skills | Yes, no setup | No | Yes, by skill_id |
| Frontmatter fields | 6 spec fields | All Claude Code fields | 6 spec fields |
| Description limit | 200 characters (Help Center) | 1,536 in the listing, combined with when_to_use | 1,024 characters |
| Network access | Full, partial or none, set by user or admin | Same as any program on your machine | None |
| Install packages at runtime | Not stated in the overview | Yes, locally preferred | No |
| Sharing | View-only shares on Team and Enterprise | Git, plugins, managed settings | Everyone in the workspace |
| Syncs to other surfaces | One-way into Claude Code | Receives from claude.ai | No |
The description limit is the first thing to break
Claude picks a skill by matching your request against its description, so this one field decides whether the skill ever runs. The three limits measure slightly different things.
The Skills API rejects a description over 1,024 characters. It also caps name at 64 characters, allows only lowercase letters, numbers and hyphens, and bans the words anthropic and claude.
Claude Code will load a longer one. It truncates the combined description and when_to_use text at 1,536 characters in the skill listing, and if you have many skills it can drop descriptions from the listing altogether, starting with the skills you invoke least. The budget is 1% of the model's context window.
The Help Center's custom skills article gives 200 characters for claude.ai. That's far tighter than the platform documentation's 1,024, and we can't tell which one is enforced on upload today. Treat 200 as your target, since a description that fits there fits everywhere. Put the job and the trigger words in the first sentence.
Frontmatter: six fields travel, the rest don't
Claude Code accepts a long list of fields: disable-model-invocation, paths, context, agent, hooks, model, effort, argument-hint and more. Our frontmatter field guide walks through them.
claude.ai uploads and the Skills API accept only name, description, license, compatibility, metadata and allowed-tools. Anything else produces a hard "Unexpected key(s)" error at packaging or upload. Claude Code ignores unknown fields without an error, so you won't see this problem until you try to move the skill.
Body syntax has the same split. The Claude Code ` !command injection, which runs a shell command before the skill text reaches the model, doesn't function in claude.ai chat or through the API.
A portable skill starts like this:
---
name: weekly-report
description: Build the weekly sales report from a CSV. Use when asked for a weekly report or sales summary.
license: MIT
---
Runtime: the same script can fail three different ways
Scripts break most moved skills.
Claude API. Skills run in the code execution container with no network access and no runtime package installs. A script that calls pip install or hits an external API will fail. Check the code execution tool's package list and write to it.
claude.ai. Network access can be full, partial or off depending on user and admin settings. A skill that works for you can fail for a colleague in an organization with stricter settings.
Claude Code. The script has the same network access as any program on your computer. It's the most capable surface and the one where a careless or malicious skill can do the most harm.
If you want one script that runs everywhere, use the standard library or pre-installed packages and pass data in as files.
Claude Code: folders on disk
Claude Code needs no upload. Put the folder in the right place:
mkdir -p ~/.claude/skills/weekly-report
cp SKILL.md ~/.claude/skills/weekly-report/
Use ~/.claude/skills/ for yourself or .claude/skills/ inside a repo to share through git. Our guide to personal vs project skills covers the precedence rules. Edits are picked up without a restart, and /skills lists what loaded.
Anthropic's pre-built PowerPoint, Excel, Word and PDF skills aren't part of Claude Code. The open-source Claude API skill comes bundled instead, and our document skills comparison explains what to use for files.
claude.ai: ZIP files and plan rules
Turn on code execution first. Then package the folder so the skill folder itself is the root of the archive, and make sure the folder name matches the skill name:
zip -r weekly-report.zip weekly-report/
Upload it from Customize > Skills, using the + button, then Create skill, then Upload a skill.
On plans, the sources conflict. The Help Center says Free through Enterprise can use custom skills. The platform overview lists Pro, Max, Ultra, Team and Enterprise for custom uploads. If you're on Free, try it, and don't build a team process on the answer.
Sharing needs Team or Enterprise. You can share by name or email, and recipients get view-only access and receive your updates automatically. An owner has to enable the sharing toggles first. Publish to org pushes a skill to the whole organization and can require review.
Claude API: versions and workspaces
The API has explicit versioning. Each upload creates a skver_ version, and each version is a complete snapshot, so you re-upload the whole file set. Limits are 30 MB uncompressed per upload and 20 skills per request. Pin a version in production and keep latest for testing.
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2026-10-21" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 4096,
"container": {
"skills": [{"type": "custom", "skill_id": "skill_01...", "version": "latest"}]
},
"messages": [{"role": "user", "content": "Build the weekly report"}],
"tools": [{"type": "code_execution_20250825", "name": "code_execution"}]
}'
The code execution tool is mandatory because the skill runs inside its container. Custom skills are visible to everyone in the workspace, so if you serve several customers, give each one a separate workspace.
For regulated work, note that Agent Skills aren't eligible for zero data retention, and the same docs list HIPAA as not eligible.
Syncing: one-way, and only sometimes
The overview page says custom skills don't sync across surfaces, and for the API that's true. There's one exception it doesn't describe. Skills enabled on your claude.ai account download into Claude Code when you sign in with that same account on v2.1.273 or later. They land in ~/.claude/skills/synced/ and appear under "claude.ai sync" in /skills.
Four details catch people out:
- The sync only goes down. Local edits inside synced/
aren't saved to your account, and a later sync can overwrite them. - Sessions using an API key or a cloud provider such as Amazon Bedrock don't sync.
- A local skill with the same name takes the short command. With a local deploy
,/deployruns yours and the account copy stays reachable as/anthropic-skills:deploy. - Claude Code never runs
!commandinjections from synced skills on your machine.
Cowork and cloud sessions load account skills too, but they don't read your local ~/.claude/skills/ folder. If a skill needs to run on a schedule in the cloud, it has to live on your account. To stop the sync, set syncClaudeAiSkills to false.
Security notes before you upload anyone else's skill
Anthropic's guidance is to use skills only from yourself or Anthropic, and to audit anything else like software you're about to install. Read every file, including scripts and images. Be wary of skills that fetch from external URLs, because fetched content can carry instructions.
The risk differs by surface. The API's closed network limits what a bad skill can send out. Claude Code offers no such limit. Enterprise organizations can turn on content scanning for skills uploaded in claude.ai and Cowork, and that scanning doesn't cover the Skills API. Our audit checklist gives a concrete process, and the anthropics/skills repository is the safest place to read working examples. The format itself is documented at agentskills.io.
If you're building skills for a team, our list of tools for developers covers the surrounding stack, and our Claude listing has the product details.
What we'd do
Write for the strictest surface and add features as a copy. Keep a portable version with the six spec fields, a description under 200 characters, no network calls and no installs. Then make a Claude Code copy if you want paths`, hooks or forked context. Two small files are easier to maintain than one file that fails its upload every time someone forgets which field came from where.
Frequently Asked Questions
Do Claude skills work the same everywhere?
The SKILL.md format is shared, but frontmatter fields, description limits, network access and sharing differ across claude.ai, Claude Code and the API. Most skills need some editing to move.
Can I use a Claude Code skill on claude.ai?
Yes, if its frontmatter uses only the six spec fields: name, description, license, compatibility, metadata and allowed-tools. ZIP the folder and upload it. Remove Claude Code-only syntax such as command injection.
Do claude.ai skills show up in Claude Code?
Yes, on v2.1.273 or later when you sign in with the same Claude account. The sync is one-way and doesn't run for API-key or cloud-provider sessions.
Why does my skill script fail through the API?
Skills on the API run with no network access and can't install packages at runtime. Rewrite the script to use the pre-installed packages and pass in data as files.
What is the description limit for a Claude skill?
The API allows 1,024 characters. Claude Code truncates the listing at 1,536 combined with when_to_use. The Help Center gives 200 for claude.ai, so aim for 200 if you want one version.
Share this article
⚙Related Tools
📄Related Articles
Get More AI Tool Guides
New comparisons and guides every week. Join thousands of professionals staying ahead of the AI curve.