Agent Skills: Equipping Claude with On-Call Specialized Abilities

📚 Series Navigation: The previous post 25 Memory System discussed "passively remembering facts"—writing project preferences and conventions into CLAUDE.md so Claude doesn't have to ask every time. This post changes direction to talk about "actively encapsulating capabilities": packaging a whole set of operation steps into Agent Skills, so Claude can automatically bring out the corresponding abilities when they are needed.

"Isn't a Skill just a renamed slash command? I type /deploy and it runs deployment, what's the difference from the old .claude/commands/deploy.md?"

"There's a huge difference. A slash command only moves when you actively call it; you don't have to call a Skill—when Claude sees that your task matches, it brings it out automatically. Moreover, it usually only takes up one sentence of space and only expands into the full text when used."

"...Brings it out automatically? Wouldn't that cause a mess, how would I know when it's going to move?"

This is a very common misunderstanding, and exactly what I thought when I first started using it—I stuffed the existing commit.md command into .claude/skills/, it ran exactly the same as before, and I wondered "Isn't this just changing a folder?". Later I realized the problem was stuck at: treating a Skill as a vest for a slash command. In fact, the official team merged custom commands into the Skills system long ago—your .claude/commands/ files still work, but Skills have three more things: they can carry supporting files, can be triggered automatically by Claude on demand, and usually take up almost no context.

Official statement: "Custom commands have been merged into skills. Files in .claude/commands/deploy.md and the skill in .claude/skills/deploy/SKILL.md will both create /deploy and work in the same way."

In this post, I will thoroughly explain what a Skill actually is, why it can "bring itself out" without exploding the context, where it comes from, and how it is triggered.

After reading this post, you will get:

• What a Skill actually is—how a SKILL.md plus supporting resources becomes a capability of Claude
• How it achieves "on-demand loading" (progressive disclosure): the secret behind why it usually takes up only one sentence and expands only when used, saving context
• The positional differences among Skills, slash commands, and Subagents, clarified in one table (the complete decision guide is left for post 30)
• Where Skills come from (built-in, bundled with plugins, self-written), and how the directory they are placed in determines who can use them
• How to trigger them (via automatic description matching, without memorizing commands), and how to check which ones are currently available

---

01 Understand First: What Exactly is a Skill

Let's give the conclusion first: A Skill is essentially an instruction file called SKILL.md, plus a few optional supporting files, packaged into a set of "specialized abilities" and handed to Claude.

Analogy: Shortcuts on your phone. You create a "Going Home Mode" in iPhone "Shortcuts"—turn on lights, adjust AC, play music. Once programmed, you don't need to manually operate step by step; you just say "Going Home Mode", and it automatically runs through the sequence you arranged. A Skill does the same thing: you write a fixed process (like "summarize uncommitted changes and flag risks") into SKILL.md, and after that, this process becomes an action Claude can easily call, saving you from retyping the steps every time.

What does SKILL.md look like? It consists of two parts, clearly explained in the official docs (this example is saved at ~/.claude/skills/summarize-changes/SKILL.md, the directory name summarize-changes is the command name you will type later):

---
description: 总结未提交的改动并标出风险。当用户问改了啥、想要提交信息、或让我审查 diff 时使用。
---

## 当前改动

!`git diff HEAD`

## 说明

把上面的改动用两三个要点概括，再列出你注意到的风险，比如缺失的错误处理、写死的值、需要更新的测试。如果 diff 是空的，就说没有未提交的改动。

The part framed by --- above is called YAML frontmatter (metadata at the beginning, the configuration area written between two --- lines at the top of the file), it tells Claude what this Skill does and when to use it; the markdown text below are the instructions Claude will actually follow when called.

Notice the middle line !`git diff HEAD`—this is a quite brilliant design called dynamic context injection: Claude Code will first run this command, replace this line with its output, and then Claude sees the Skill content. So what Claude receives is not "go run a diff", but your actual current changes already filled in. This is preprocessing, not executed by Claude itself.

A Skill is more than just one SKILL.md file, it is a directory. The official standard appearance looks like this:

my-skill/
├── SKILL.md           # 主说明（必需）
├── template.md        # 让 Claude 填的模板
├── examples/
│   └── sample.md      # 给它看的示例输出
└── scripts/
    └── validate.sh    # 它可以执行的脚本

Only SKILL.md is required, the rest are optional. This is where Skills are stronger than old slash commands: they can bring templates, examples, and scripts—scripts can be in any language, Claude is responsible for orchestration, and the scripts do the heavy lifting.

Three real-world scenarios where you can immediately think of what a Skill can do:

• Every time you ask Claude to commit code, you have to remind it to "run tests first, write a Chinese commit, use feat as a prefix"—write this set into a commit Skill, and handle it in one sentence from then on.
• The team has agreed on a set of API conventions (RESTful naming, unified error formats, mandatory validation)—write it into an api-conventions Skill, and it will automatically follow this set when writing interfaces.
• You want to generate a visual structure diagram of the codebase—the official codebase-visualizer Skill bundles a Python script, and opens an interactive tree diagram directly in the browser when finished.

💡 One-sentence summary: A Skill is a set of abilities packaged as "SKILL.md (saying when to use + how to do) + optional supporting files"—write it once, and Claude can easily call it later, it can also bundle templates and scripts.

---

02 The Lifeline: Progressive Disclosure, the Secret to Saving Context

This is the most crucial section to understand in this entire post. Why can a Skill pack so much content while taking up almost none of your context? The answer is one phrase: progressive disclosure (meaning "expanding step by step on demand", not loading the full text when irrelevant).

First, let's talk about why this is critical. As discussed earlier in 19 Context Management, Claude's "workbench" is only so big, every word stuffed into it spends the budget and squeezes the room it has to think. If the full text of every Skill is piled in at the start of a conversation, installing ten Skills would waste half of your workbench.

Analogy: The menu and kitchen of a restaurant. You sit down, and the waiter first hands you a menu—each dish has one line of name and one sentence of introduction, you know what's available at a glance. You order "Kung Pao Chicken", and the detailed recipe full of steps in the kitchen is then dug out to follow. The recipes for un-ordered dishes remain pressed in the drawer, taking up no space on your table. This is how Skills operate:

• Normally: Claude can only see that one sentence of description for each Skill (the dish name on the menu).
• When relevant: What you ask matches a certain description, and the full text of that Skill is then loaded in (digging out the corresponding recipe).

The official documentation explains this rule very straightforwardly:

In regular conversations, the skill description is loaded into context so that Claude knows what is available, but the full skill content is loaded only when invoked.

So you can confidently write long reference materials and detailed checklists into the Skill's main body—it costs almost nothing before it's used. This is exactly why the official advice is "make content into a Skill instead of stuffing it all into CLAUDE.md": CLAUDE.md is resident throughout the conversation from the start, while the Skill's main body only comes when used.

This image clearly illustrates the two stages of "progressive disclosure": on the left is the normal state of the conversation—three Skills each take up only one description sentence in the context, and the workbench is still quite empty; on the right, after a description is hit by your question, only the full text of that one Skill is loaded in, while the other two remain just one line. It's easy to see where it "saves".

However, there is an associated cost you must know, otherwise you'll fall into a trap: once a Skill is loaded, its main text will reside throughout the rest of the conversation—Claude will not reread it in every subsequent turn. Official words:

When you or Claude invoke a skill, the presented SKILL.md content enters the conversation as a single message, and remains there for the rest of the session.

This means two things: first, every line in the Skill's main text is a recurring token cost, don't inflate it, the official advice is to keep SKILL.md under 500 lines, and split long references into separate files to load on demand; second, write "resident instructions" instead of "one-off steps"—because it's there the whole time, it should be written as "guidance applicable to the entire task", not something that expires after use like "step one do X".

Here is a related little stumble I actually experienced myself: I wrote a Skill, it followed it for the first few turns, but later in the chat it felt like "it seems to have forgotten these instructions", my first reaction was that loading failed, and I repeatedly restarted Claude to make it reread. Checking the official docs made me understand—the content is usually still there, the model just turned around and chose another tool. The solution is to make the description and instructions clearer, leaning it to continue favoring this Skill, instead of doubting the loading mechanism.

💡 One-sentence summary: Progressive disclosure = usually exposing only a description sentence, expanding full text only when used, so installing any number of Skills won't burst the context; but after expansion it will reside throughout, the main text must be concise and written as resident instructions.

---

03 Skill, slash command, Subagent: What's the Difference Exactly

The core of the debate at the beginning is this section. Many people mix these three up, but their positioning is completely different. Here I will first unpack the most easily confused points, the complete "which one to choose" decision table is left for post 30, this section only aims to "tell them apart".

Let's first align the three terms:

• slash command: A segment of operations you actively trigger by typing /xxx.
• Skill: A packaged set of abilities, you can actively call it, and Claude can automatically invoke it on demand.
• Subagent: A sub-assistant with an independent context, the main conversation delegates tasks to it, it finishes in its own small world and brings back the results (discussed in detail earlier in 23 Subagents).

Here is a crucial realization, specifically to break the misunderstanding at the beginning: slash commands and Skills are not antagonistic; a slash command is actually one way to call a Skill. The official team merged custom commands into Skills—you build a commit Skill, and it naturally can be called with /commit. The real difference is not in "what it's called", but in who can initiate it and whether it takes up context:

Dimension	slash command (Old .claude/commands/)	Skill	Subagent
Who can initiate	Only you (trigger by typing /)	You + Claude can both (can trigger automatically)	Delegated by main conversation
Runs in which context	In the current conversation	In the current conversation (default)	Independent sub-context
Takes up context normally	——	Only takes one description sentence	Does not take up (spun up on demand)
Can bring supporting files	Cannot	Can (templates / scripts / examples)	Depends on its own definition
Best suited for	Fixed operations where you want to manually control the timing	Specialized abilities you want Claude to use when appropriate	Running independent, heavy subtasks in isolation

Understanding this table resolves the debate at the beginning: that understanding of "slash command" is the manual trigger gear of a Skill; it didn't realize the same Skill can also let Claude trigger automatically.

Then will "automatic triggering" cause a mess? No, because you can precisely control who has the right to call it. The official docs give two frontmatter switches:

• disable-model-invocation: true: Only you can call it. Used for tasks with side effects where you want to manually control the timing—like /deploy, /commit, sending Slack messages. You definitely don't want Claude to autonomously deploy just because "your code looks like it's done".
• user-invocable: false: Only Claude can call it. Used for "background knowledge" type Skills—like a legacy-system-context that explains how the old system runs, Claude just needs to know it when appropriate, but /legacy-system-context is not a meaningful command for you.

So the "mess" is controllable: if you're afraid it will act recklessly, add disable-model-invocation: true to lock it to pure manual; this is exactly the trick to use for the misunderstanding above.

💡 One-sentence summary: A slash command is the manual trigger gear of a Skill, a Subagent is a sub-assistant with an independent context—the positioning of the three is different; if you're afraid a Skill will act automatically and recklessly, use disable-model-invocation: true to lock it so only you can call it.

---

04 Where do Skills Come From: Built-in, Plugin-bundled, Self-written

Now we know what they are, where do Skills pop out from? Three sources, from near to far.

Source One: Built-in (Bundled) Skills—available out of the box, present in every conversation. Claude Code comes with a batch of bundled Skills, you don't need to install them. The officially listed ones are /code-review, /debug, /batch, /loop, /claude-api, etc. There are also three complementary ones for "running to verify": /run (start and drive your app to see if changes are effective), /verify (build and run to confirm changes work as expected), /run-skill-generator (teach the first two how to build and start your project). You can see these in the menu just by typing /.

Note: Bundled Skills are not the same thing as built-in commands like /help or /compact. Built-in commands directly execute fixed logic; bundled Skills are prompt-based—giving Claude detailed instructions to orchestrate and complete using its own tools. The calling method is the same, both are typing / plus the name.

Source Two: Plugin-bundled—install a plugin, Skills come along with it. As discussed earlier in 24 Plugins, plugins can package a bunch of extensions. Skills are one of the things plugins can bring: create a skills/ directory inside a plugin, and those Skills will become available wherever the plugin is enabled. Plugin Skills use the plugin_name:skill_name namespace (e.g., /my-plugin:review), so they will never clash names with your own Skills.

Source Three: Self-written—this is the main stage for Skills. You write the instructions, checklists, and multi-step processes you repeatedly paste into a SKILL.md, and it becomes your exclusive ability. The official criterion is very practical:

When you keep pasting the same instructions, checklists, or multi-step procedures into the chat, or when a part of CLAUDE.md has evolved into a procedure rather than facts, create a skill.

This sentence breaks through the division of labor between Skills and CLAUDE.md, connecting exactly with the previous post: CLAUDE.md holds "facts" (what tech stack the project uses, what conventions exist), Skills hold "procedures" (how to do this in steps). When you find yourself writing "Step one... Step two..." in CLAUDE.md, that part should be moved into a Skill.

The table below helps you check your seat:

Your situation	❌ Stop doing this	✅ Time for a Skill
Reminding the same process for every commit	Manually typing the steps every time	Write a commit Skill, call it in one sentence
Team has fixed API conventions	Stuffed into CLAUDE.md, occupying context throughout	Write as a Skill, load when used
Want some kind of visual report	Describing the desired chart every time	Bundle a Skill that generates via script

💡 One-sentence summary: Skills have three sources—built-in bundled (out of the box), plugin-bundled (comes with what you install), self-written (main stage); there's only one rule to decide whether to write one yourself: are you repeatedly pasting the same set of steps?

---

05 Placement Determines Who Can Use + How to Trigger, How to Check

This last section lands on the three most practical things: where to put your self-written Skills, how they are triggered, and how to see what you have on hand right now.

Which Directory to Place In Determines Who Can Use It

This is the official location table, wrong place = the right people can't use it, just copy it:

Scope	Where to Put	Who Can Use
Personal	~/.claude/skills/<skill-name>/SKILL.md	All your projects
Project	.claude/skills/<skill-name>/SKILL.md	Only this current project
Plugin	<plugin>/skills/<skill-name>/SKILL.md	Wherever the plugin is enabled
Enterprise	See managed settings	Everyone in the organization

The logic is very intuitive: if only you use it and it's universal across projects (like your personal commit habits), put it in the personal level ~/.claude/skills/; if it's exclusive to this project and you want the team to use it too (like the deployment process of this project), put it in the project level .claude/skills/ and commit it to the repository.

Who wins in a name clash? The officially stipulated priority is Enterprise > Personal > Project (plugins do not participate in name grabbing because they carry namespaces). There is also a security tip worth highlighting: after a project-level Skill is committed to the repository, others pulling it down must first pass a "Workspace Trust" dialog box—because allowed-tools inside a Skill can authorize a batch of tools for itself, look at what the Skill in the project writes before trusting the repository, so you don't get permissions secretly opened by an Skill of unknown origin.

How to Trigger: Via Automatic Description Matching, No Need to Memorize Commands

This is the most comfortable point about Skills: you don't need to remember /something-something, just speak normally. Claude will take what you say and compare it against the description of each Skill, and if there's a match, it automatically brings out that Skill.

Taking the summarize-changes Skill from Section 01 as an example, its description says "use when the user asks what changed...", so both methods can trigger it:

我改了什么？

/summarize-changes

The first is letting Claude call it automatically (you didn't even mention the Skill name at all, it matched it itself); the second is calling the name directly. For daily use, the first is more recommended—just state your need, leave the triggering to it. This inversely tells you how important the description is when writing a Skill: the description must contain "keywords the user would naturally say" for it to match accurately. The official first step to troubleshoot "Skill didn't trigger" is to check this:

Check if the description contains keywords the user would naturally say.

How to Check: What Skills are Actually Available Right Now

Installed a bunch, built-in a bunch, how do you know what you have on hand right now? The most direct way is to ask it in one sentence:

现在有哪些 Skill 可用？

It will list all currently available Skills for you. This is also one of the standard actions for troubleshooting Skill problems officially—first confirm if it's actually in the list, then talk about triggering. Additionally, typing / to bring up the command menu will also show you the ones you can manually call, and /doctor can help you check "whether Skill descriptions are truncated because too many are installed" (if the number of installed Skills reaches a certain point, descriptions get compressed to save character budget, which might shave off the keywords used for matching).

💡 One-sentence summary: Put personal-level in ~/.claude/skills/, project-level in .claude/skills/, priority for same names: Enterprise > Personal > Project; triggering relies on automatic description matching, no need to memorize commands; one sentence of What skills are available? can check what is currently available.

---

06 Hands-on: See "Automatic Triggering" and "Progressive Disclosure" in 5 Minutes

Just reading without practicing won't stick in your memory. The following minimal set of operations, without writing any complex scripts, will let you see two things with your own eyes: how a Skill is automatically triggered by one sentence, and how it normally only takes up one line. The whole process can be run in an empty directory.

Step One: Create a Personal-Level Skill Directory (Mac / Linux)

mkdir -p ~/.claude/skills/explain-self

Windows Users: Just create an explain-self folder under C:\Users\YourUsername\.claude\skills\.

Expectation: An empty explain-self directory has appeared under ~/.claude/skills/.

Step Two: Write the Simplest SKILL.md

Using your handy editor, save the following content to ~/.claude/skills/explain-self/SKILL.md:

---
description: 用大白话解释一段代码或一个报错。当用户说「这段代码啥意思」「这个报错咋回事」「帮我读读这个」时使用。
---

## 说明

把用户给的代码或报错，用初学者能懂的大白话讲清楚：
1. 这东西整体在干啥（一句话）
2. 逐行 / 逐段拆开说
3. 如果是报错，指出最可能的原因和怎么改

不要堆术语，能用生活类比就用。

Notice its description specifically wrote "what does this code mean" "what's going on with this error"—these are things you would actually say—these are the hooks for automatic triggering.

Expectation: The explain-self directory now has a SKILL.md.

Step Three: Start Claude and Confirm It Recognizes This Skill

claude

After entering, type:

现在有哪些 Skill 可用？

Expectation: In the returned list of available Skills, you can see explain-self, and next to it is the description sentence you wrote. Seeing it in the list = the Skill has been loaded correctly. (This step also incidentally verifies progressive disclosure: at this moment in the context, there is only its one description sentence, and those few lines of instructions in the main text haven't been loaded in yet.)

Step Four: Don't Call the Name, Use "Human Language" to Trigger It

Deliberately do not type /explain-self, but say a sentence that matches the description:

这段代码啥意思：print(sum([1,2,3]) / len([1,2,3]))

Expectation: Claude will automatically invoke this explain-self Skill (you can see the prompt that the Skill was triggered in its response), and then explain it following the three steps you wrote—first state the whole thing in one sentence (calculate the average of these three numbers), then break it down segment by segment, with few jargon terms. It brought out the corresponding ability without waiting for you to call a command, this is automatic triggering.

Step Five: Compare with Calling the Name Directly

Try the manual gear once more, type directly:

/explain-self 这个报错咋回事：ZeroDivisionError: division by zero

Expectation: Triggers this Skill just the same, with identical effects to Step Four—the only difference is that this time you actively called it. Two roads lead to the same ability, which perfectly corroborates "You + Claude can both initiate" in the table in Section 03.

By running through these five steps, you have personally verified the two most core things about Skills—"description matching automatic triggering" and "normally only takes up one description sentence".

💡 One-sentence summary: Create ~/.claude/skills/explain-self/SKILL.md, use What skills are available? to confirm loading, then trigger once each with "human language" and /name—seeing with your own eyes that automatic triggering and manual triggering lead to the same ability is more solid than memorizing ten lines of documentation.

---

07 Summary

This post has combed through Agent Skills from "what they are" to "how to use them"—they ensure Claude is no longer a blank slate, but takes up its post carrying a set of specialized abilities that can be called on demand.

Reviewing the core points strung together:

What You Want to Clarify	Answer	Key Point
What is a Skill	SKILL.md + optional supporting files packaged together	frontmatter says when to use, main text says how to do
Why doesn't it burst context	Progressive disclosure	Normally exposes only a description sentence, expands full text only when used
Difference from slash / Subagent	Different positioning	slash is manual gear, Subagent is an independent context (decision table in post 30)
Where do Skills come from	Built-in / plugin-bundled / self-written	Repeatedly pasting the same set of steps = time to write it yourself
Where to put, how to trigger, how to check	Directory determines scope	description matches automatically; check with What skills are available?

You should now be able to: Clearly explain what a Skill is made of, its principle of saving context via "progressive disclosure"; distinguish the positioning of Skills, slash commands, and Subagents; know the three sources of Skills and how the directory they are placed in determines who can use them; and understand that triggering it relies on automatic description matching, without memorizing commands. This set of "bringing out specialized capabilities on demand" abilities is a crucial step for you to train Claude from a "general assistant" into an "expert who understands your line of work."

---

Next post 27 "Skill Usage Examples"—this post was all concepts and mechanisms, the next post is real action: taking you to install a genuinely useful Skill from scratch, triggering it yourself, and watching it finish the job. Think about it, what is that one thing in your daily life where you repeatedly remind Claude of the same process? In the next post, we will operate on this type of task and seal it into an ability that can be called in one sentence.

---

Recommended Reading

• Chrome: Letting It Operate the Browser
• API Configuration: Subscription Login or API key, How to Choose, How to Switch
• CLAUDE.md Usage Guide: Writing Project Rules into Its Memory