Claude Code Skills vs Claude Agent Skills (API): What's the Difference?

"Claude skill" means three different things depending on where you heard it: a Claude.ai consumer feature you toggle on in a chat, a repo-native .claude/skills/<name>/SKILL.md file Claude Code loads on demand, or a Claude Agent SDK skill bundled into a custom application built on the API. They share the SKILL.md format and the same on-demand loading idea, but they live in different products with different install paths and different failure modes — including a repo skill silently losing to a same-named plugin skill. Last updated 2026-11-16 by Rakshit Yadav.

Three products, one file format

Claude.ai Skills are a consumer-facing feature: you (or a workspace admin) turn a skill on inside Claude.ai itself, and it's available across chats in that account. There's no repo, no git history, no folder structure you control directly — it's a setting on the product, closer to a browser extension than to a file you edit in an IDE.

Claude Code Skills are the opposite: a SKILL.md file committed at .claude/skills/<name>/SKILL.md inside a specific repo. They're plain markdown with YAML frontmatter (name, description), versioned in git alongside the code they describe, and loaded only when Claude Code decides the current task matches the description. Two different repos can have two completely different skills with the same name, because the skill lives in the repo, not in your account.

Claude Agent SDK Skills (sometimes called API skills) are what you get when you're building your own application on top of Claude's API using the Agent SDK. You bundle SKILL.md-shaped files into your application's own skill directory and load them programmatically — there's no Claude Code or Claude.ai in the loop at all. This is the one most developers never encounter unless they're shipping a custom agent product, not using Claude Code or Claude.ai directly.

Decision table: which one am I actually building

Claude.ai SkillClaude Code SkillAgent SDK Skill
Where it livesYour Claude.ai account/workspace settings.claude/skills/<name>/SKILL.md in a repoYour own app's skill directory, loaded via the Agent SDK
Who installs itYou, in the Claude.ai UIWhoever commits the file to the repoWhoever ships the application
Versioned withYour Claude.ai account, not gitThe repo's git historyYour application's own release process
ScopeFollows your account across chatsThat one repo only, shared with anyone who clones itWhatever your application decides to load per session
You're building this ifYou just want a personal Claude.ai chat habitYou're coding in Claude Code and want a team-shared playbookYou're building a product on the Claude API, not using Claude Code or Claude.ai as the end interface

If you're coding inside Claude Code and searched for "skills vs plugins," you almost certainly mean the middle column — see the mechanism-level breakdown in Claude Code Plugins vs Skills vs MCP, which covers what a skill does once it's in your repo, not which of the three products you're in.

Why a Claude Code skill can get silently overridden by a plugin

A Claude Code plugin can bundle its own skills/ directory and install it alongside whatever's already in a repo's .claude/skills/. If the plugin ships a skill with the same name as one you already committed, the plugin's copy is the one that ends up loaded for that name — your repo-native version doesn't get merged with it or flagged as a conflict, it just stops being the one Claude reaches for. This is the practical version of the "skills is a confusing term" complaint that's shown up in community bug reports: the word covers both "a file I wrote for this repo" and "a file a plugin installed for me," and nothing in the UI distinguishes them once they share a name.

The fix is mechanical, not a Claude Code setting: treat skill names like you'd treat npm package names. Before installing a plugin, check its bundled skills/ folder for a name collision with anything already in .claude/skills/, and rename one side if you find one. The same check matters in reverse — if you're the one publishing a plugin, prefix or namespace your skill names so you don't silently clobber a consumer's existing playbook.

Where AgenticKit fits

AgenticKit ships 61 skills as the middle column only: plain .claude/skills/<name>/SKILL.md files committed into your repo via npx agentickit-cursor init, each one scoped to a specific role among the 46 agents it also installs. There's no Claude.ai account toggle involved and no separate Agent SDK integration to wire up — if you're not building your own API-backed product, you don't need to think about that third column at all. Because the skill names are fixed and documented on the skills pillar, checking for a collision before adding a third-party plugin is a five-minute diff against that list rather than a guess.

Related pages

Frequently asked questions

  • Is a Claude.ai skill the same file format as a Claude Code skill?
    They're both SKILL.md-shaped (a description plus a body that loads on demand), but they live in different products with no automatic sync between them. A skill you turn on in Claude.ai doesn't appear in a repo's .claude/skills/ folder, and vice versa.
  • Do I need the Claude Agent SDK to use skills in Claude Code?
    No. Claude Code skills are a Claude Code feature on their own — just a SKILL.md file in .claude/skills/. The Agent SDK is only relevant if you're building a separate application on the Claude API that isn't Claude Code or Claude.ai.
  • Can a plugin's skill override my own repo's skill with the same name?
    Yes, if a plugin bundles a skill with the same name as one already in your .claude/skills/ folder, the plugin's version is the one that gets loaded for that name — there's no merge or conflict warning. Check a plugin's bundled skills for name collisions before installing it.
  • Why do so many articles use 'skills' to mean different things?
    Because Anthropic reused the same term and the same SKILL.md shape across three separate products — the Claude.ai consumer feature, Claude Code's repo-native skills, and the Agent SDK's programmatic skills for custom applications — released at different times without a naming scheme that distinguishes them.
  • Which kind of skill does AgenticKit install?
    Claude Code repo skills only: plain .claude/skills/<name>/SKILL.md files committed to your repo, scoped to the agents and commands AgenticKit also installs. It doesn't touch your Claude.ai account settings or require the Agent SDK.

Get repo-native skills, pre-wired

AgenticKit ships 61 skills as committed .claude/skills/ files, scoped to the 46 agents that call them — no consumer toggle, no separate SDK integration.