Skills in Practice: Install One, Call It, Watch It Work

📚 Series Navigation: The previous article 26 What is a Skill explained the principles thoroughly—what SKILL.md is, and why description determines whether Claude uses it. This article is not about theory, but real practice: taking you through checking what skills you have on hand, calling one with a single sentence, and watching it finish the job, bringing "knowing how to use others' skills" down to earth.

For example, you need to rush out an architecture diagram of the codebase for a presentation to your boss. Normally, you'd have to sort out nodes in your head, draw a Mermaid sketch, adjust colors, and export a PNG, a whole set of processes that takes half a day. Now, just type one sentence to Claude Code, "Help me draw an architecture diagram for this project"—and Claude gets it done itself.

It asks no parameters, automatically loads a skill named baoyu-diagram, lays it out according to the hardcoded dark design system, generates an SVG, and converts it to a @2x PNG. In less than five minutes, the image is lying in docs/assets/.

At this moment you truly understand the value of a skill: It's not about "making Claude smarter", but "letting Claude do a certain thing following the same reliable process every time". Compressing half a day into five minutes, the difference is exactly this pre-written process.

From the previous article, you already know what a skill is. This article does only one thing: takes you through running this "half a day to five minutes" experience yourself.

After reading this article, you will get:

• Check out exactly what skills are available in the current conversation in one sentence, no more guessing.
• Understand what a real SKILL.md looks like, and know why the description line determines whether it triggers.
• Run a complete skill process using two methods: "natural language trigger" and "calling its name directly with /", with expected output for each step.
• A three-step troubleshooting checklist for when a skill won't respond (vague phrasing / unmatched description / not enabled at all).
• Specific practices on how to commit a skill into a project so that the whole team works according to the same process.

---

01 Don't Rush to Use It: See Exactly What Skills You Have on Hand

The first step in taking action is not "using a skill", but figuring out what skills you have available to use right now.

The most common mistake beginners make is guessing from memory—"I remember there's a drawing skill, right?" Then they shout at Claude for a long time with no response, thinking the skill is broken, when in fact it's not even installed. Checking your inventory first is better than anything.

Analogy: Before cooking with a recipe, first flip through your recipe book to see what dishes are actually in it. You wouldn't stare at an empty kitchen thinking "Let's make braised pork today", you have to first confirm that there is a "braised pork" page in the recipe book, and the ingredients and steps are all there. A skill is Claude's recipe, each SKILL.md is a pre-written dish—first check the table of contents, confirm the dish is listed, then turn on the stove.

The way to check is extremely simple, just ask it in plain language in the Claude Code conversation:

What skills are available?

The official documentation uses the English question What skills are available?, and it recognizes Chinese just the same. Expectation: Claude will list the skills available for the current conversation, each with its name and a one-sentence introduction. If you run it in this tutorial project, the drawing one will be in the list:

baoyu-diagram — Generate professional dark-themed SVG diagrams (architecture / flowchart / sequence / mindmap...)

💡 One-sentence summary: Before using a skill, ask "What skills are available?" in the conversation first to confirm the dish you want is listed, then turn on the stove, don't just guess at non-existent skills.

There are two other small actions to check your inventory, just note them in passing:

/skills menu — Type /skills in the input box and press Enter, a visual menu will pop up listing all skills, and you can also toggle the enabled state of each skill here (press Space to cycle through after highlighting, Enter to save). It's more intuitive than a plain text list.

/doctor checkup — This one is a bit advanced: If you installed a ton of skills, Claude might run out of "description budget" and truncate the descriptions of some skills, causing it to "not see the whole picture". /doctor can tell you if the budget overflows and which skills are affected. Beginners generally don't use it, but if one day you find a skill inexplicably stops triggering, run /doctor to take a look first.

---

02 Unpacking a Real Skill: What SKILL.md Looks Like

Just knowing "there is this skill" is not enough, you need to understand what it looks like inside to understand why it gets triggered and what it can do.

As it happens, there is a real skill lying in this tutorial project. Let's not look at the toy examples in the official docs, and directly dissect this baoyu-diagram that is actually being used to generate diagrams every day.

Its location in the project is:

.claude/skills/baoyu-diagram/
├── SKILL.md              # Main description (required)
├── references/           # Detailed layout rules for various diagrams (loaded on demand)
│   ├── architecture.md
│   ├── flowchart.md
│   └── sequence.md
└── scripts/
    └── main.ts           # Script for converting SVG to PNG (executed, not in context)

See the pattern? A skill is a folder, SKILL.md is the entry point, and reference docs and scripts can be hung alongside it. SKILL.md is required, the rest are optional "ingredients"—reference docs keep the main description concise (only loading what is needed for the type of diagram), and scripts are tools for Claude to run.

Open its SKILL.md, the block at the very top enclosed by --- is the lifeblood, called frontmatter (metadata placed at the very top of the file):

---
name: baoyu-diagram
description: Create professional, dark-themed SVG diagrams of any type — architecture diagrams, flowcharts, sequence diagrams... Also trigger when the user says "画个图" "画一个架构图" "diagram" "flowchart"...
version: 1.117.3
---

The big chunk of markdown below the --- is the actual "recipe body" Claude has to follow (design system, color scheme, typography rules, command to convert to PNG).

There's a key point discussed in the previous article, but you should see it for yourself now: That description line is Claude's core basis for judging "should I use this skill this time" (there is also an optional when_to_use field in the frontmatter to supplement trigger conditions, combined they are truncated to 1536 characters).

Did you notice—this description blatantly stuffs a bunch of Chinese trigger words: "画个图" (draw a picture), "画一个架构图" (draw an architecture diagram), along with English diagram, flowchart. This wasn't written randomly, the author deliberately paved in things the user might say, so that Claude reacts "it's my turn" as soon as it hears these words.

Analogy: The header on a recipe page saying "Suitable for: family dinners, hosting guests, pairing with rice". When you flip through recipes looking for a "guest-hosting dish", glancing at this line in the header tells you this dish is on point. description is the skill's header tag—Claude takes your words to compare against the description of each skill, and whichever tag matches best, it flips to that page.

So remember this chain of cause and effect, later troubleshooting relies entirely on it:

Your words → Claude compares them against the description of various skills → Matches successfully → Loads the body of that SKILL.md → Works according to the steps inside.

The closer the description is to your real phrasing, the more accurate the trigger. This is also why in the next section's troubleshooting for "not responding", the first thing to check is it.

This image breaks down "how a sentence turns into a skill working" into four steps: You speak → Claude compares it with the description of each skill → Upon a hit, it loads the corresponding SKILL.md body → Produces results following the hardcoded steps inside. Once you understand this chain, you'll know where to start troubleshooting.

💡 One-sentence summary: A skill is a folder with a SKILL.md, the description at the very top is the trigger lifeblood—Claude compares your words to it, and only opens this recipe page if it matches.

---

03 Running the First One: Call It in Natural Language, Watch It Produce

Inventory clear, structure understood, let's start. This section goes through the most common usage using baoyu-diagram: call it in plain language, let Claude judge whether it should be used.

This is the most satisfying part of skills—you don't have to remember any commands, Claude picks which skill to use itself.

Step one, start Claude Code in the root directory of the tutorial project:

claude

Expectation: Enters the conversation, input box appears at the bottom.

Step two, simply state the requirement in plain language—notice, not a single word mentions the name baoyu-diagram here:

Help me draw a diagram explaining Claude's "think→act→observe" agent loop

Expectation: Once Claude hears "draw a diagram", it goes to compare against the description of each skill, hits the diagram / "画个图" in the baoyu-diagram line, so it automatically loads it, then works according to the recipe body: reads the corresponding reference doc (for a flowchart, it reads references/flowchart.md), lays it out according to the dark design system, generates an .svg, and then runs a script to convert it to @2x.png.

When it's done, it will tell you where the output is, looking roughly like this:

Diagram generated:
  docs/claude-code/assets/27-agent-loop.svg
  docs/claude-code/assets/27-agent-loop@2x.png

Seeing these two files = skill triggered successfully, and the work is done. Throughout the process, you didn't touch any parameters, all based on a single sentence of plain language.

This is the biggest difference between a skill and a "normal conversation". Let's put up a comparison, the gap is clear at a glance:

	❌ Without a skill	✅ With a skill
What you have to say	Describe color scheme, font size, layout, how to convert to PNG in detail...	One sentence "Help me draw a diagram"
Output stability	Dark mode this time, light mode next time, style drifts every time	Always applies the same design system, stable and consistent
What you have to remember	A bunch of parameters and steps	Nothing to remember

To put it plainly, a skill hardcodes the "tedious process you have to explain every time" once and for all. You just say what you want, "how to make it professional" is the recipe's business.

Don't Want to Wait for It to Guess? Name It Directly

Sometimes you are very certain you want to use a specific skill, and too lazy to let it guess, calling its name directly with / is fastest:

/baoyu-diagram draw a sequence diagram for user login

Expectation: Skips the "matching description" step, directly loads baoyu-diagram and executes it, the string of text after the / is passed in as a parameter (here it tells it what diagram to draw).

When to use which method? Generally speaking:

• Exploring, unsure what to use → Use plain language, let Claude pick itself (it might pick better than you think).
• Knowing exactly which one you want, wanting it to execute immediately → Call it directly with /, especially for skills that "have side effects and shouldn't be triggered randomly" (like deploy, commit), officially it is recommended to only let you trigger these manually via /, don't let Claude take the initiative.

💡 One-sentence summary: Two paths to run a skill—plain language for Claude to pick itself, /name to call it directly; the former is for exploring, the latter is for "I want it, do it now".

---

04 No Response When Called? Three-Step Troubleshooting, Take Your Seat

Once you really get hands-on, you'll eventually encounter this: You called out, Claude didn't use a skill, and just painstakingly did it the normal way. Don't panic, and don't think the skill is broken—nine times out of ten it's one of the three situations below. The official troubleshooting just has these few points, sorted below by "most common".

Analogy: Cooking with a recipe, the dish fails, it's nothing more than three reasons—the dish name you said doesn't match the recipe header, the recipe isn't even in this book, or your words were too vague for the chef to understand. Check them one by one, you'll always catch which link it is.

Step 1: First suspect "your words are too vague" (most common).

Many times it's not the skill's fault, it's that your sentence is too far from the description. For example, the description for baoyu-diagram says "draw a diagram / diagram / architecture diagram", if you say "give me a visual thing", Claude might not map it to "draw a diagram".

Solution: Lean your words towards the description, say it again in a more straightforward way:

Help me draw an architecture diagram

With clear verbs like "draw" and "diagram", the hit rate goes straight up. This is the fastest trick, try it first.

Step 2: Confirm "is this skill actually in the registry".

Go back to the trick in section 01, ask:

What skills are available?

Expectation: If the skill you want is not in the list at all, then the problem is clear—it's not installed at all, or not loaded (e.g., a project-level skill hasn't passed trust, or your startup directory is wrong). Don't waste time on "how to trigger" in this case, install it / load it first (section 05 explains how to make project-level skills take effect).

Step 3: Confirmed it's in the registry, still won't trigger—use / to call its name directly as a fallback.

If step two confirmed it's in the list, and step one's change of phrasing still doesn't work, don't argue with it, directly call it manually with /name:

/baoyu-diagram draw an architecture diagram

As long as it's in the registry, calling it with / will definitely trigger it (/ means "I'm calling on you specifically", bypassing the "Claude judges for itself" link). This step is both a fallback and helps you locate the problem: calling it with / works = the skill itself is fine, it's purely the auto-trigger didn't match, then you just need to optimize the description later.

Organize these three steps into a troubleshooting table, follow it when it doesn't respond:

Phenomenon	What to Check First	How to Solve
No response when called, Claude does it the normal way	Is your phrasing far from the description?	Say it again in a more straightforward way (with clear verbs)
Changing phrasing still doesn't work	Is the skill in the "available list"?	Ask "What skills are available?"; if not, install/load it first
Confirmed in registry, still won't auto-trigger	Is it purely a matching failure?	Manually call with /name as fallback, optimize description later

⚠️ Conversely, there's also the annoyance of "triggering too frequently" — a certain skill keeps popping up on its own. The official solution is: write its description more specifically (don't use overly broad words), or add disable-model-invocation: true to it, outright forbidding Claude from auto-triggering it, only allowing you to manually invoke it with /. This fix falls under "creating/modifying skills", which will be expanded upon in the next article.

💡 One-sentence summary: Troubleshoot unresponsiveness in three steps—first suspect vague phrasing (switch to straightforward phrasing), then check if it's in the registry, finally fallback by calling its name directly with /; these three tricks cover almost all "non-triggering" issues you'll encounter.

---

05 Letting the Whole Team Use It: Committing Skills to the Project

By now you know how to use a skill. But there is a problem: the skills installed in ~/.claude/skills/ above, only exist on your own computer; colleagues won't have them when they pull the code.

To have the entire team working according to the same process, you have to put it somewhere else—a project-level skill.

Analogy: Don't just stick this dish's recipe in your own kitchen; print it into the "company recipe booklet" distributed with the project. Anyone who gets this booklet (clones the repository) can open it and cook the exact same dish. A personal skill is your private recipe; a project-level skill is a public recipe sent out with the code, a copy in everyone's hands.

There's only one difference: where to put it, and whether to commit it to Git. Look at this comparison:

	Personal Skill	Project-Level Skill
Where is it located	~/.claude/skills/<name>/SKILL.md	.claude/skills/<name>/SKILL.md inside the project
Who can use it	All your projects, but only on this machine of yours	Everyone who cloned this repository
Goes into Git?	Does not enter (in your home directory)	Enters, committed together with the code
Typical use cases	Your personal habit processes	Team unified standards (deployment, commit format, drawing style)

Exactly how to implement it, takes just three steps:

Step 1: Put the skill into the project's .claude/skills/ (instead of the home directory):

Your Project/
└── .claude/
    └── skills/
        └── team-commit/
            └── SKILL.md

Step 2: Commit into version control. Just like committing normal code:

git add .claude/skills/
git commit -m "feat: Add a team-unified commit skill"

Step 3: Colleagues can use it as soon as they pull it — this is the sweetest part of project-level: After others clone the repository and git pull, this skill is automatically in their conversation, without them needing to install it manually. From then on, the whole team "uses the same style for drawings" and "follows the same checks for commits".

There is an official, explicit security detail to remember here: Skills checked into someone else's project will pop up a "Workspace Trust" dialog asking for your confirmation the first time you open that project. Why this step? Because skills can grant themselves tool permissions (like automatically running commands), before trusting a repository, glance at what is written in its skills, don't just blindly click agree. Official words:

Review project skills before trusting a repository, as a skill can grant itself broad tool access.

When pulling external projects, you should follow this rule. For example, cloning an open-source repository, take a look at the SKILL.md under its .claude/skills/ before trusting; you might find one of the skills opens up a bunch of Bash permissions in allowed-tools — it's not necessarily malicious, but it's better to see clearly before clicking trust. This glance is worth taking.

💡 One-sentence summary: To let the whole team use the same skill, put it into the project's .claude/skills/ and commit to Git, others will have it automatically upon cloning; but before trusting another project's skills, first glance at what permissions it requested.

---

06 Hands-on: Install a Personal Skill from Scratch, Call It Yourself

Earlier we were using the ready-made baoyu-diagram. This section takes you to create the simplest skill from scratch and trigger it — not to build something complex, but to see with your own eyes the complete chain of "writing a file → it appears in the list → calling it with one sentence". The whole process relies on no complex environments.

We'll make a super simple one: let Claude explain a piece of code for you in a "coffee shop chat style".

Step 1: Create the skill directory (personal level, placed in the home directory, usable across all your projects). Mac / Linux:

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

Windows (PowerShell):

mkdir $HOME\.claude\skills\explain-casual

Expectation: An explain-casual folder appears under ~/.claude/skills/.

Step 2: Write SKILL.md. Using your preferred editor, paste this into ~/.claude/skills/explain-casual/SKILL.md:

---
description: Use a relaxed coffee shop chat style to explain a piece of code. Used when the user says "用大白话讲讲这段代码" (explain this code in plain language), "这段代码在干嘛" (what is this code doing), "讲讲这个函数" (talk about this function).
---

## Task

Explain the code provided by the user in the most colloquial, relaxed way, like chatting with a friend in a coffee shop, no academic tone. Requirements:

1. First clarify in one sentence what this code is doing overall.
2. Then pick out a few key lines and explain them one by one in plain language.
3. Finally, mention: is there anywhere that looks awkward or might have hidden traps.

Highlight: That description line deliberately packed full of things the user might say — "用大白话讲讲这段代码" (explain this code in plain language), "这段代码在干嘛" (what is this code doing), "讲讲这个函数" (talk about this function). This is the "header tag" mentioned in section 02, the closer it is packed to realistic phrasing, the more accurate the trigger.

Step 3: Confirm it entered the list. There's an official detail to note here: A "top-level skill directory" that didn't exist when the session started requires a restart to be monitored. We just created the explain-casual directory, so just to be safe, open a new session:

claude

Once inside, ask:

What skills are available?

Expectation: explain-casual appears in the list, carrying the Chinese description you wrote. Seeing it = the skill is installed and loaded.

Step 4: Call it in plain language (don't mention the name). Paste a piece of code in the conversation for it to explain, for example:

Explain this code in plain language:
def average(numbers):
    return sum(numbers) / len(numbers)

Expectation: Claude maps your sentence "Explain this code in plain language" to the description of explain-casual, automatically loads this skill, then follows its three steps: first stating in one sentence that it calculates the average; then explaining the sum(numbers) / len(numbers) line; finally reminding you that passing an empty list will crash with a division by 0 (this is exactly the "hidden traps" rule from task step 1 at work). The entire tone is a relaxed coffee shop style, not a dry documentation tone.

Step 5: Compare it with "calling by name". Try calling directly with / again:

/explain-casual def average(numbers): return sum(numbers) / len(numbers)

Expectation: The exact same effect, but this time you named the trigger — skipping the "Claude judges for itself" link, the code after the / is passed in as a parameter.

By running through these five steps, you have personally felt the complete lifecycle of a skill: writing SKILL.md → it appears in the available list → plain language can call it → / can also name it. In the future, using anyone else's skills is fundamentally this exact same mechanism, the recipe contents are just more complex.

⚠️ If you don't see explain-casual in the list at step 3: Nine times out of ten it's because you didn't restart the session (creating a new top-level directory requires a restart to be monitored), exit claude and re-enter once. If re-entering still doesn't show it, check if the file path and file name are exactly called SKILL.md (all caps) without a single letter wrong.

💡 One-sentence summary: Personally build and run the simplest skill — create directory, write SKILL.md (pack description with real phrasing), restart to confirm it's in the list, call it in plain language; once this chain is clear, you will know how to use others' skills as well.

---

07 Summary

This entire article has been hands-on, turning "knowing how to use others' skills" from a concept into muscle memory. Let's recap the core actions:

What you need to do	How to do it	Key point
Check what skills are available	Ask "What skills are available?" / /skills menu	Confirm it is in the registry before using
Understand a skill	Read its SKILL.md	The description at the very top is the trigger lifeblood
Trigger a skill	Plain language call / /name direct call	Use the former to explore, use the latter when you want it to act immediately
Troubleshoot unresponsiveness	Switch straightforward phrasing → Check registry → / direct call fallback	Nine out of ten times it's "phrasing too vague"
Let the whole team use it	Place in project .claude/skills/ and commit to Git	Before trusting another project's skill, see what permissions it requests

You should now be able to: Clearly check what skills you have on hand in any session, understand the structure of a real SKILL.md and why it triggers, run a skill using two methods, locate problems in three steps when it doesn't respond, and commit a skill into a project for the team to share. This ability to "use others' skills" is your ticket to free-riding the entire skill ecosystem — a massive amount of ready-made skills in the community; install them, call them with one sentence, and others' pre-written professional processes are yours to use.

That "half a day to five minutes" architecture diagram at the beginning came about exactly like this. You now hold the same key.

---

Next up is 28 "skill-creator: Build Your Own Skill" — now that you know how to use others' recipes, the next step naturally is writing your own recipes. Do you have a process where you have to repeat a long string of instructions to Claude every time? (Often, it's more than one process.) The next article will teach you how to use the official skill-creator to solidify these "repeatedly pasted tedious processes" into your exclusive skills once and for all, turning from "a person who uses recipes" into "a person who writes recipes".

---

Recommended Reading

• Environment Variables: The Row of "Master Switches" Hidden Behind
• Voice Mode: Speak Your Prompts Instead of Typing Them
• Plugin Reference Manual: Pack Your Own Configuration into a Distributable Bundle