Skip to main content
    Kriv AI

    Claude Code

    A skill in Claude Code: what it is and where it goes

    Anthropic documents skills in its own Claude Code pages. This page puts the answer in one place and says where each line comes from.

    A skill in Claude Code is a folder that holds a SKILL.md file of instructions. Anthropic's documentation says "Create a SKILL.md file with instructions, and Claude adds it to its toolkit. Claude uses skills when relevant, or you can invoke one directly with /skill-name." You save it in your personal skills folder to use it in every project, or in your project's skills folder so your team gets it too. Source: Anthropic Claude Code documentation, read 18 November 2026.

    plain answer

    A skill is a SKILL.md file that Claude adds to its toolkit

    Anthropic's Extend Claude Code page says "A skill is a markdown file containing knowledge, workflows, or instructions." It adds that you can run one with a command such as /deploy, or Claude can load it on its own when it fits the task.

    Anthropic's best practices page says what belongs in one: knowledge about how your team works, such as a release process or an incident runbook, saved at .claude/skills/<name>/SKILL.md. It also says "only write down what Claude can't find on its own."

    Anthropic's skills page says a skill can be reference content or task content. Reference content "adds knowledge Claude applies to your current work", such as conventions, patterns and style guides. Task content "gives Claude step-by-step instructions for a specific action, like deployments, commits, or code generation."

    plain answer

    Make your first skill in three steps

    Anthropic's skills page walks through a first skill that summarizes the uncommitted changes in your git repository and flags anything risky. The steps are short.

    Step 1: create a folder for the skill inside your personal skills folder, for example ~/.claude/skills/summarize-changes. Step 2: save a SKILL.md file in that folder. Anthropic says a skill file has two parts, "YAML frontmatter between --- markers that tells Claude when to use the skill, and markdown content with the instructions Claude follows when the skill runs." The example's description reads "Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff."

    Step 3: test it two ways. Ask something that matches the description, such as "What did I change?", or type /summarize-changes. Anthropic says that either way "Claude should respond with a short summary of your edit and a list of risks." Anthropic's page also notes that the folder name, or the name field when you set one, becomes the command you type.

    plain answer

    Save it in a personal, project or plugin skills folder

    Anthropic's skills page lists the locations. A personal skill lives at ~/.claude/skills/<skill-name>/SKILL.md and loads in all your projects on that machine. A project skill lives at .claude/skills/<skill-name>/SKILL.md, and the page says "Commit it so your team gets it too." A plugin skill lives at <plugin>/skills/<skill-name>/SKILL.md and loads wherever the plugin is enabled, as /plugin-name:skill-name.

    The page also lists an enterprise location in the managed settings directory. Anthropic's platform docs say Claude Code skills are "separate from both claude.ai and the API", so a skill you add in Claude Code does not appear in those products.

    Two details trip people up. In a repository with subfolders, Anthropic says a skill in a .claude/skills/ folder below where you started "load the first time Claude reads or edits a file in that subdirectory and stay available for the rest of the session." And a skill that exists only in ~/.claude/skills/ on your machine is not found by a cloud scheduled task, because each run starts as a fresh cloud session. Desktop scheduled tasks run on your machine, so they do load it.

    plain answer

    The description is what Claude reads to decide when to use it

    Anthropic's skills page says "All fields are optional. Only description is recommended so Claude knows when to use the skill." The name defaults to the folder name.

    Anthropic's Extend Claude Code page warns that "If descriptions are vague or overlap, Claude may load the wrong skill or miss one that would help." Anthropic's platform overview, which lists name and description as required fields, says the description must include both what the skill does and when to use it. Writing both fields satisfies both pages.

    The skills page also says to "Put the key use case first", because the combined description and when_to_use text is truncated at 1,536 characters in the skill listing to reduce context usage.

    plain answer

    Claude can start a skill, or only you can

    Two settings at the start of the SKILL.md file decide who can start a skill: disable-model-invocation and user-invocable.

    By default Claude can load a skill when the task matches its description, and you can also type /skill-name. Anthropic's skills page says to set disable-model-invocation to true "to prevent Claude from automatically loading this skill" and suits workflows "you want to trigger manually with /name." It gives /commit, /deploy and /send-slack-message as examples and says "You don't want Claude deciding to deploy because your code looks ready." Anthropic's best practices page recommends it for a workflow with side effects, such as cutting a release.

    Setting user-invocable to false does the opposite: Anthropic says Claude Code hides the skill from the / menu and does not run it when you type /name. Anthropic suggests it for background knowledge, such as a skill that explains how an old system works.

    Anthropic's table sums it up. With neither setting, you and Claude can both start the skill and its description sits in context. With disable-model-invocation true, only you can start it and its description stays out of context. With user-invocable false, only Claude can start it.

    plain answer

    A skill can carry more than one file

    Anthropic's skills page says "Skills can include multiple files in their directory", with SKILL.md as the overview and other files for reference material, examples or scripts, and it advises "Keep SKILL.md under 500 lines." Its folder example marks SKILL.md as "required - overview and navigation" and a helper script as "executed, not loaded".

    On loading, Anthropic's best practices page says Claude sees only the name and description in every session and "only reads the full file when the task calls for it." The allowed-tools field lets a skill use named tools without asking permission for that turn; Anthropic says it "does not restrict which tools are available."

    plain answer

    When a skill is worth writing

    Anthropic's skills page says to create a skill "when you keep pasting the same instructions, checklist, or multi-step procedure into chat, or when a section of CLAUDE.md has grown into a procedure rather than a fact."

    The Extend Claude Code page gives the same advice as triggers. If you keep typing the same prompt to start a task, save it as a user-invocable skill. If you paste the same playbook into chat for the third time, capture it as a skill. It adds that "A workflow you keep tweaking by hand is a skill that needs another revision."

    plain answer

    A skill is not a subagent, an MCP server or a hook

    Anthropic's Extend Claude Code page separates them. Skills are "reusable content you can load into any context", and subagents are "isolated workers that run separately from your main conversation." A skill adds to your main context window, while a subagent uses a separate window with its own input and output tokens. They can combine: "A skill can run in isolated context using context: fork." Anthropic's subagents page says "Each subagent runs in its own context window with a custom system prompt, specific tool access, and independent permissions."

    MCP is the other neighbor. Anthropic says "MCP connects Claude to external services. Skills extend what Claude knows, including how to use those services effectively." Its example is an MCP connection to your database with a skill that documents your schema and query patterns.

    Our guide to Claude Code hooks covers the fourth neighbor. The short version from Anthropic is that a hook runs on its event every time, while a skill is instructions Claude reads and applies.

    plain answer

    Bundled skills work without setup

    Anthropic's skills page says "Claude Code includes a set of bundled skills, such as /doctor, /code-review, /batch, /debug, /loop, and /claude-api." It describes them this way: "Bundled skills are prompt-based: they give Claude detailed instructions and let it orchestrate the work using its tools."

    Two examples from the page. /doctor runs a setup checkup, and "Claude reports its findings first and asks for confirmation before changing anything." /run and /verify launch your app and confirm a change against the running app instead of tests alone. Reading the bundled skills is a quick way to see what a well-formed skill looks like.

    plain answer

    When two skills share a name, one wins

    Anthropic's skills page has a table for name clashes. Between two of the enterprise, personal and project locations, the answer is "Enterprise over personal, and personal over project." So a deploy skill in both ~/.claude/skills/ and the project's .claude/skills/ runs the personal one. A skill you write also replaces a bundled command of the same name: a project code-review skill replaces /code-review.

    Plugin skills avoid the clash. Anthropic says "Plugin skills are namespaced to avoid conflicts", which means a plugin skill is typed with the plugin name in front, as /plugin-name:skill-name, next to your own.

    plain answer

    If Claude does not use your skill, or drifts from it

    Anthropic's troubleshooting steps for a skill that does not trigger start with the description: "Check the description includes keywords users would naturally say." If the skill is user-invocable, try "/skill-name" directly. If it triggers too often, "Make the description more specific" or add disable-model-invocation: true.

    If Claude follows a skill at first and then drifts, Anthropic gives two causes. Claude Code adds a skill's content when the skill is invoked and "doesn't re-read the file on later turns", so guidance should be worded for the whole task. After the conversation is compacted, "invoke the skill again to restore its full content", and Anthropic advises putting the most important instructions at the start of SKILL.md. For a rule that must hold every time, it says to "move the rule into a hook."

    Every skill adds to your context on every turn. Anthropic says "Run /skill-doctor to see what each of your skills costs and how often it gets used, so you can decide which ones to turn off."

    limits

    Treat a skill like software you install

    Anthropic's platform docs say "Use Skills only from trusted sources: those you created yourself or obtained from Anthropic." They add that in Claude Code a skill has "the same network access as any other program on the user's computer."

    A skill is also an instruction, not a rule. Anthropic's Extend Claude Code page says a rule such as "never edit .env" in a skill is only a request that Claude may not always follow, and points to hooks for anything that must hold every time.

    Anthropic's skills page adds a review step for shared skills: "review the allowed-tools of skills checked into a repository before you run Claude Code there."

    Straight answers

    Frequently asked questions about A skill in Claude Code: what it is and where it goes

    What is the difference between a skill and CLAUDE.md in Claude Code?

    Anthropic's Extend Claude Code page says to put something in CLAUDE.md "if Claude should always know it" and in a skill if it is "reference material Claude needs sometimes" or a workflow you start with /<name>. CLAUDE.md loads every session; a skill loads on demand.

    Is a skill the same as a slash command?

    Anthropic's skills page says you can invoke a skill directly with /skill-name, so a skill can work like a slash command. It also says "Custom commands have been merged into skills. Your existing .claude/commands/ files keep working." Claude can load a skill when it fits the task, unless you turn that off.

    Should I use a skill or a hook?

    Anthropic says a hook "fires on its event without Claude deciding", while with a skill "Claude interprets the instructions; outcome can vary." Anthropic's guidance is to make a rule a hook if it must hold every time. Our guide to Claude Code hooks covers hooks.

    Do skills I add in Claude Code show up in claude.ai or the API?

    No. Anthropic's platform docs say "Claude Code Skills are filesystem-based and separate from both claude.ai and the API."

    Can I share a skill with my team?

    Anthropic's skills page says a project skill at .claude/skills/<skill-name>/SKILL.md can be committed so your team gets it too. It lists three ways to share: "Commit .claude/skills/ to version control", put a skills folder in a plugin, or deploy through managed settings for the whole organization. Anthropic's platform docs also say Claude Code skills can be shared through Claude Code plugins.

    Do skills only work in Claude Code?

    Anthropic's skills page says "Claude Code skills follow the Agent Skills open standard, which works across multiple AI tools." It adds that Claude Code extends the standard with features such as invocation control, subagent execution and dynamic context injection, so a skill that uses those extras may not behave the same elsewhere. The Agent Skills site describes the standard as "a lightweight, open format for extending AI agent capabilities with specialized knowledge and workflows."

    Can a skill run in its own subagent?

    Yes. Anthropic's skills page says "Add context: fork to your frontmatter when you want a skill to run in isolation." The subagent does not see your conversation history, so the skill's instructions have to stand on their own. Anthropic warns that this only makes sense for skills with explicit instructions: a skill of guidelines with no task returns without meaningful output.

    Can too many skills cause problems?

    Anthropic's skills page says "Every skill in the skill listing adds to your context on every turn, whether or not Claude ever uses it." It also says that with many skills, Claude Code drops some descriptions to fit the listing's character budget. Anthropic points to /doctor and /skill-doctor to find the skills worth turning off.

    Talk to the team that would do the work

    Bring your requirements to a working session with the person who'll actually deliver.

    Book a Discovery Call