Skip to main content
Comparison8 min read·Updated November 9, 2026
🧩

Claude Skills: claude.ai vs Claude Code vs API (2026)

B

A. Frans

Published November 9, 2026

Agent SkillsClaude CodeClaude APISKILL.mdSkill Security

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.aiClaude CodeClaude API
How a skill gets thereZIP upload in Customize > SkillsFolder on diskUpload to /v1/skills
Pre-built document skillsYes, no setupNoYes, by skill_id
Frontmatter fields6 spec fieldsAll Claude Code fields6 spec fields
Description limit200 characters (Help Center)1,536 in the listing, combined with when_to_use1,024 characters
Network accessFull, partial or none, set by user or adminSame as any program on your machineNone
Install packages at runtimeNot stated in the overviewYes, locally preferredNo
SharingView-only shares on Team and EnterpriseGit, plugins, managed settingsEveryone in the workspace
Syncs to other surfacesOne-way into Claude CodeReceives from claude.aiNo

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, /deploy runs yours and the account copy stays reachable as /anthropic-skills:deploy.
  • Claude Code never runs !command injections 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

📬

Get More AI Tool Guides

New comparisons and guides every week. Join thousands of professionals staying ahead of the AI curve.