Guide

Claude Code skills

Harrowtech.ai · last checked 13 October 2026

Claude Code skills are saved sets of instructions that Claude loads when a task needs them, or that you run by typing /skill-name. This page covers where they live, how they get triggered, how to write a small one, and how they differ from slash commands and subagents.

What a skill is

A skill is a folder containing a file called SKILL.md. The file holds instructions. Anthropic's advice on when to make one: when you keep pasting the same procedure into chat. The body of a skill loads only when it is used, so long reference material costs little until it is needed. Skills follow an open format called Agent Skills, with some Claude Code additions.

Where skills live

Personal skills in ~/.claude/skills/ do not reach Cowork or cloud sessions. For those, enable the skill on your claude.ai account, or, for cloud sessions, commit it to the repository’s .claude/skills/.

If two skills share a name, enterprise beats personal and personal beats project. A skill also beats a file of the same name in .claude/commands/, and a skill with the same name as a bundled skill replaces it. In a local terminal session the same goes for a built-in command. In both cases the original’s aliases still run the original. Plugin skills carry the plugin name, so they do not clash.

How a skill is triggered

• By Claude. Claude reads each skill's description and loads the skill when your request matches it. This makes the description the most important line you write. Put the main use first, because the description and the optional when_to_use text together are cut off at 1,536 characters in the listing. With many skills installed, Claude Code may also drop whole descriptions to keep the listing within its budget, 1% of the model’s context window, starting with the skills you use least.
• By you. Type /skill-name, with arguments after it if you like. $ARGUMENTS in the skill body receives them.

Two settings in the file's header change this. disable-model-invocation: true means only you can run the skill. Anthropic recommends it for steps with side effects, such as a deploy or a commit, where you want to choose the timing. user-invocable: false does the reverse: the skill is hidden from the / menu and only Claude calls it.

Writing a simple one

The header between the --- lines must start on the file's first line. Every field is optional, but Anthropic recommends a description. If you leave out name, the folder name is used. This is Anthropic's example, saved as ~/.claude/skills/summarize-changes/SKILL.md:

---
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
---

## Current changes

!`git diff HEAD`

## Instructions

Summarize the changes above in two or three bullet points, then list any risks you notice such as missing error handling, hardcoded values, or tests that need updating. If the diff is empty, say there are no uncommitted changes.

The line starting ! and a backtick is a command. Claude Code runs it before Claude sees the skill and puts the output in its place, so Claude starts with the real diff already in front of it.

What a test run showed

Tested on Claude Code 2.1.296 on 13 October 2026: a similar skill was made in a throwaway project at .claude/skills/commit-summary/SKILL.md, with a description and a !`git status --short` line. Running claude -p "/commit-summary" returned a one-sentence summary of the two untracked files and a suggested commit message. That confirms a skill with only a description works, and that /skill-name works in print mode, which Anthropic says it does. The test did not check whether Claude picks the skill up by itself from a plain question.

Extra files and limits

A skill folder can hold more than SKILL.md, for example reference.md, examples.md or a scripts/ folder. Mention each file from SKILL.md so Claude knows when to open it. Anthropic suggests keeping SKILL.md under 500 lines. Scripts are run rather than read into context. Anthropic’s longer example bundles a Python script that writes an interactive HTML map of a codebase. The skill tells Claude to run it with ${CLAUDE_SKILL_DIR} in the path, so it resolves whether the skill is installed as personal, project or plugin.

Other header fields include model, effort, hooks and allowed-tools. That last one lets Claude use the listed tools without asking during the turn that invokes the skill, and the grant clears when you send your next message. Anthropic warns that workspace trust does not gate it: a project skill’s allowed-tools applies even in a -p run in a folder you have never trusted. Review that field in any skill checked into a repository before you run Claude Code there.

To switch skills off for a session, start with claude --disable-slash-commands. Claude's own help text for that flag says it disables all skills.

Skills compared with commands and subagents

• Custom commands. A file at .claude/commands/deploy.md is the older format. Anthropic says commands are now merged into skills: both create /deploy and work the same way, and old command files keep working. A skill adds a folder for supporting files, control over who may invoke it, and automatic loading. For the built-in slash commands, see Claude Code commands and shortcuts.
• Subagents. A subagent is a separate assistant with its own context window. See Claude Code subagents explained. The two can be combined. A skill with context: fork runs as the task inside an isolated subagent that cannot see your conversation. Going the other way, a subagent can preload skills as reference material.

Short version: a skill is a set of instructions Claude can pick up or you can start by name, and a subagent is a separate worker with its own context.

What this guide does not cover

It does not cover bundling skills into plugins, the full list of header fields, skills from extra folders added with --add-dir, or running skills in a monorepo's nested folders. Anthropic's skills page covers each.

Sources

• Anthropic: Extend Claude with skills, read 13 October 2026.
• Anthropic: Run Claude Code programmatically, for skills in print mode, read 13 October 2026.
• Commands run on Claude Code 2.1.296 on 13 October 2026.

Related: All Harrowtech.ai guides · Claude Code hooks · Claude Code MCP servers · Claude Code best practices