Using skill-creator: Building Your Own skill With a skill

📚 Series Navigation: In the previous article [27 Using Skills Examples], we taught you how to make good use of skills created by others—how to install them, make them trigger automatically, and use them smoothly. This article goes the other way around: it teaches you how to build your own. And not by writing it by hand, but by using the official skill specifically designed for building skills—skill-creator.

People say SKILL.md is just a markdown file, just write it by hand, why bother using another tool?

To tell the truth, this statement is only half right. The file is indeed simple, but "building a skill that can be triggered accurately" is not simple at all—and 90% of those who fail by writing it by hand stumble in the same place: the description is written improperly, resulting in the skill never being invoked.

My very first hand-written skill failed exactly like this. At the time, I wanted to create a skill that "generates a commit message conforming to team standards". I set up the directory, wrote the body clearly, and casually filled in the description with "Commit message helper". The result? Every time I asked Claude to commit, it completely ignored that skill and wrote a version according to general habits. I insisted that it was not installed properly, tossed and turned for a long time with /doctor, restarting, and reinstalling, but it was all useless. Only later did I figure it out—the problem was not "whether it was installed or not", but "there were no words the user would say in the description". You can't see this kind of pitfall at all when writing by hand; you need something to force you to get it right.

skill-creator is exactly that thing.

After reading this article, you will get:

• Why writing SKILL.md by hand seems easy but is actually the easiest to fall into pitfalls, and what exact things skill-creator helps you get right.
• The complete process of building a skill with skill-creator: scaffolding → guiding to write name / description / body → organizing scripts and references → packaging.
• The most valuable section in the whole article: how to write a description so that it can be triggered accurately (including trigger scenario keywords, and it must be a bit "proactive").
• Which directory personal skills and project skills should be placed in, and who can use them.
• A hands-on practice that you can follow and run: use skill-creator to set up a minimal skill, and verify with your own hands that it is actually triggered.

---

01 Counter-consensus: Writing SKILL.md by hand is not hard, the hard part is "making it responsive"

Let's pick up the foundation from the previous article first. In article 27, you already knew: a skill is just a directory, the core is the SKILL.md inside it, with a piece of YAML at the top writing the name and description, and the body below for Claude to read. The official documentation's exact words:

Every skill needs a SKILL.md file that contains two parts: YAML frontmatter (between --- markers) that tells Claude when to use the skill, and markdown content containing instructions for Claude to follow when invoking it.

Looks super simple, right? Create a folder, write a file, and you're done. So a novice's first reaction is always: just write it by hand, why need a tool.

This is the counter-consensus point: writing by hand itself is indeed not difficult, what's difficult is that the hand-written skill is "unresponsive"—you think it will appear automatically when it should, but it just sleeps in the corner all the time.

Analogy: A "tool-building wizard" filling out a form. You've seen that kind of wizard when installing new software, right—it doesn't let you blindly fill in a blank configuration file, but asks you page by page "what is this tool called", "under what circumstances should it be used", "what does the input look like, what format should the output be". You answer a few questions, and it puts the directory structure, scaffolding, and the positions of all fields right for you behind the scenes. skill-creator is this kind of wizard in the skill world: you answer a few of its questions, and it does those things that "you simply wouldn't think of managing when writing by hand" correctly for you.

Specifically, what pitfalls of hand-writing that are easiest to fall into does it help you cover? Look at this comparison table—this is what you should remember most in this section:

Prone to fail step	❌ Common result of pure hand-writing	✅ What skill-creator helps you get right
description	Writing like "Commit helper", missing trigger words, never triggered	Guides you to clearly write "what it does + when to use", containing keywords users would say
Directory structure	Stuffing scripts and reference docs all into SKILL.md, long and messy	Helps you sort them into scripts/ references/, keeping the body concise
Trigger verification	After writing, you don't know if it triggers at all, relying entirely on metaphysics	Gives you test cases to run once and see if it can actually be invoked
Improvement	You can only stare blankly if it doesn't trigger, not knowing where to fix	Has a dedicated description optimization link, tuning based on the trigger rate

Did you notice? The pitfalls of writing by hand are all things "you didn't manage because you couldn't see them". The value of skill-creator is not to help you type (it's not much faster at typing), but to force you to do these invisible things correctly without missing a single one.

💡 One-sentence summary: Writing SKILL.md by hand is not hard, the hard part is making it actually trigger when it should; skill-creator is like a wizard for filling out forms to build tools, covering those things like description, directories, verification, and improvements that are "invisible when writing by hand" for you.

---

02 What skill-creator is, and how to invite it out

Let's give the conclusion first: skill-creator itself is a skill, and its specialty is "building other skills". Sounds like a tongue twister, but the logic is smooth—since a skill is used to extend Claude's capabilities, then the repetitive work of "building a skill" is itself worth being made into a skill.

It does not come with Claude Code out of the box (unlike those bundled skills like /code-review and /debug), it needs to be installed separately—by placing the skill directory into ~/.claude/skills/ (personal global) or the project's .claude/skills/ (takes effect only for this project), this mechanism was covered in article 27. In the official plugin marketplace (claude-plugins-official), the toolkit corresponding to "creating plugins" is called plugin-dev, while skill-creator is an independently published skill, and the installation method is to directly clone or download the directory to the skills path:

# Put the skill-creator directory into the personal skills directory
cp -r skill-creator ~/.claude/skills/

Expectation: After placing it, you can see skill-creator in the /skills list, with the description saying "Create new skills, modify and improve existing skills...".

After installation, there are two postures to invite it out, exactly the same as the "using skills" talked about in article 27:

Posture 1: Call its name directly (explicit instruction).

/skill-creator

Posture 2: State what you want to do in plain language (let it trigger automatically). This is also the more commonly used one—because the description of skill-creator is written very "comprehensively", it catches on when you say "I want to build a skill to do XX":

I want to make a skill that helps me summarize git changes into a standardized commit message every time.

Regardless of the posture, next it will not blindly throw a file at you, but will start asking you questions like a wizard. In the official skill-creator instructions, the first step is called "Capture Intent", and it will ask you these things:

1. What should this skill enable Claude to do?
2. When should it trigger? (What phrases would users use / in what scenarios)
3. What is the expected output format?
4. Should test cases be created to verify that it works properly?

Notice the 2nd question—it will specifically ask you "when it should trigger" again. This is the biggest difference from hand-writing: when hand-writing, nobody forces you to answer this question, you casually slap on a description and pass; skill-creator treats it as a top priority because it knows that if this question is not answered well, the skill built will be useless.

Analogy: A wedding planner questions you thoroughly before taking an order. A reliable planner doesn't just throw out a proposal right away; they first ask "what is the budget", "how many people to invite", "want a Chinese style or outdoor", "any taboos". Only after thoroughly asking these will the proposal match your needs, rather than just applying a template. The "Capture Intent" of skill-creator is this process of "asking for requirements"—understand what you want first, then start assembling the skill.

💡 One-sentence summary: skill-creator is a "skill for building skills", installed from the official plugin marketplace (requires a proxy); calling /skill-creator or stating your needs in plain language can summon it. The first thing it does when it appears is to ask you questions in return, especially asking "when should this skill trigger".

---

03 The complete process it walks you through

skill-creator doesn't just generate a file for you and let go; it will accompany you through the entire assembly line of building a skill. Breaking down its process, you'll know what it covers for you in each step.

The official skill-creator summarizes the whole process into a loop, which I will translate into plain language for you:

1. Think clearly about what to do: First talk with you clearly about what this skill does and roughly how to do it (that is, the "Capture Intent" in the previous section).
2. Write the first draft: Fill in the name, description, and body based on your answers, generating SKILL.md.
3. Build test cases: Write 2-3 "things real users would say" as test prompts, asking you "do these tests look decent, do you want to add them".
4. Run once + evaluate: Take these prompts and actually run them, letting you see if the result is good—both checking "is the output correct" and checking "did it trigger when it should".
5. Revise based on feedback: Turn back and modify the skill based on your evaluation and test results. After revising, run another round, until you are satisfied.
6. (Optional) Optimize description: There is a dedicated link to optimize the description to tune the trigger accuracy upwards.
7. Package: Finally, pack the entire skill directory into a .skill file to make it convenient for you to distribute or install.

See the trick of this assembly line? When writing by hand, you only did step 2 (writing a file), and skipped 3-7 entirely—so whether your skill triggers is all up to luck, and you don't know how to fix it if it doesn't trigger. The value of skill-creator is that it treats those steps after 2 as required courses, especially the loop of "running tests to see if it triggers" and "revising based on feedback".

Here is an interjection of the directory structure it gets right for you. The directory example given in the official documentation's "Adding Supporting Files" section looks like this:

my-skill/
├── SKILL.md           # Main instructions (required)
├── reference.md       # Detailed reference documentation, loaded on demand
├── examples.md        # Example outputs, loaded on demand
└── scripts/
    └── helper.py      # Scripts Claude can execute

Key cognition: SKILL.md should be short, heavy stuff goes outside. The official exact words point it out very thoroughly:

Keep SKILL.md under 500 lines. Move detailed reference material into separate files.

Why divide it like this? Because once a skill is triggered, the content of SKILL.md will enter the context entirely and stay there throughout the whole conversation—every line is a repeated token cost. While scripts in scripts/ are "executed but not loaded", and documents in references/ are "read only when needed". The easiest mistake to make when hand-writing is pasting a three-hundred-line API documentation directly into SKILL.md, which takes up context and is messy. skill-creator will guide you to categorize these into the right places—the body only keeps "what it does and where to find it", heavy materials are moved into references/, and executable tasks are moved into scripts/.

Analogy: Writing the table of contents and appendix of a book. You wouldn't pile all the content on the table of contents page; the table of contents only writes "what chapter N is about and on which page", while the detailed content is in the main text and appendix. SKILL.md is exactly that table of contents page—it tells Claude "what materials are available and when to look at which one", and the materials themselves are placed in references/ and scripts/.

💡 One-sentence summary: What skill-creator accompanies you through is a complete assembly line of "thinking clearly → writing first draft → running tests to see triggers → revising on feedback → optimizing description → packaging"; hand-writing often only does the second step, it completes the subsequent steps, and it will also guide you to separate heavy materials into references/ and scripts/ to keep SKILL.md concise.

---

04 The most valuable section of the entire article: How to write description so that it responds

If you only remember one thing from this article, remember this: description is the "master switch" that decides whether a skill triggers or not.

Why it? Because in every conversation, what Claude sees is not the full text of your skill—what it sees first is just a list of "skill name + description", and then based on this description, it judges "whether to bring out this skill this time". Whether the description is written correctly directly determines if it will be thought of. In the official troubleshooting for "Skill not triggering", the first item is directed at this:

Check if the description includes keywords a user would naturally say.

My flipped commit skill at the beginning had its root cause right here. It was written as "Commit message helper"—there was not a single "word a user would say" in this sentence. What usually pops out of my mouth is "help me commit", "write a commit", "generate commit message", but there were none of these words in the description, so naturally Claude couldn't match them up. Later, I had skill-creator change the description to the following, shouted "help me commit" again, and it immediately caught on.

Comparing these two writing styles, the gap is obvious at a glance:

❌ Common useless descriptions when hand-writing	✅ Good descriptions guided by skill-creator
Commit message helper	Summarizes staged changes into a commit message conforming to team standards. Use when the user says "help me commit", "write a commit", "generate commit message", or asks you to review changes in preparation for a commit.
Only says "what it is"	Says both "what it does" and "when to use, how the user would say it"
Missing trigger words, never triggers	Contains real trigger words, appears on time when it should

Refined into a mnemonic formula: good description = what it does + when to use (including those exact words users would say). "What it does" lets Claude know what this tool is for, and "when to use" is the real trigger hook—and this part should be written as much as possible in plain language that would pop out of the user's mouth, not the terminology in your head.

There is also a counter-intuitive point that can be learned from skill-creator: the description should be a bit "proactive", even slightly "pushy". Because currently Claude has a tendency called "undertrigger"—it often can't be bothered to call it out when a skill can clearly help. The internal instructions of skill-creator specifically exhort to combat this:

Claude currently has a tendency to undertrigger skills—not using them when they would be useful. To combat this, please write the skill description a bit more "proactively".

What is "proactive"? Let's take the flavor of an example it gives: instead of dryly writing "builds a dashboard to display internal data", it's better to write it as "...whenever a user mentions dashboards, data visualization, internal metrics, or wants to show any company data, even if they don't explicitly say 'dashboard', this skill should be used". Explicitly write in the scenarios of "even if the user doesn't state it explicitly, it should appear"—this move can significantly increase the probability of it being invoked.

Analogy: Writing copy for a signboard in front of a store. If the signboard only says "Zhang's", passersby don't know what you sell and won't come in; if you write it as "Zhang's Beef Noodles · Free extra noodles · Spicy and non-spicy available", laying out all the words customers might search for, the people entering the store immediately increase. The description is exactly the signboard of your skill—the signboard must have the words customers will mutter in their mouths, and it must proactively greet.

💡 One-sentence summary: The description is the master trigger switch, the formula is "what it does + when to use (including exact keyword phrases the user would say)", and it must be written a bit proactively, laying out the scenarios of "should appear even if not explicitly stated" into it—only if this sentence is written well can the skill be responsive; if it's written poorly, no matter how beautiful the body is, it's useless.

---

05 Which directory to drop into: personal skills vs. project skills

Once a skill is built, where to store it? The location it is stored in directly determines who can use it. skill-creator will ask you this, but you need to have a clear idea yourself.

The location table given officially, picking out the two tiers most commonly used by beginners:

Location	Path	Who can use it
Personal	~/.claude/skills/<skill-name>/SKILL.md	All projects on your computer
Project	.claude/skills/<skill-name>/SKILL.md	Only this current project

How to choose? Just one judgment criterion: Is this skill "your private habit" or "the rule of this project"?

• Things you want to use everywhere—like "write commits in my preferred style" or "translate selected text to Chinese"—put them in the personal directory (~/.claude/skills/), settling in one place, universally applicable to all projects.
• Things tied specifically to a project—like "generate interfaces according to this repo's API specifications" or "run this project's unique deployment process"—put them in the project directory (.claude/skills/), and commit them to Git, so that everyone in the team automatically has this skill after cloning.

Analogy: A carry-on tool bag vs. a construction site tool room. That Swiss Army knife you are used to using, you keep in your pocket and carry wherever you go (personal skill); but a certain large equipment dedicated to a construction site is locked in the tool room of that site, you can't use it if you change sites, and you can't take it away (project skill). The basis of judgment is "does this tool follow the person, or does it follow the venue".

A simple and easy-to-remember division: Universal habits all go into ~/.claude/skills/, project-specific ones go into their respective .claude/skills/ and are committed to Git. Skills like translation skills and commit skills stay in the personal directory year-round, following you across all projects; while those "dedicated to this project" skills in every team project are all committed to the repository without exception—this way, when newcomers clone, the skills are in place together, no need to orally instruct "remember to install those few skills".

There is another benefit the official documentation pointed out: project skills will search all the way up to parent directories from your starting directory, so if you start Claude in a subdirectory, project skills defined in the root directory can still be picked up. Different sub-packages in a monorepo can even have their own skills without fighting each other.

💡 One-sentence summary: Personal skills are placed in ~/.claude/skills/ and follow you across all projects; project skills are placed in .claude/skills/ and committed to Git, taking effect only in this project and shared by the team; the judgment is just one sentence—does this tool follow the person, or does it follow the project.

---

06 Hands-on: Use skill-creator to set up a minimal skill and verify its trigger

Just reading without practicing is useless. Below, I will take you to really build a minimal skill using skill-creator, and the most critical part is to verify with your own hands that it is indeed triggered—this step is exactly where hand-writers are most likely to skip and most prone to fail. The whole process does not depend on any complex projects.

Our target skill to build is very small: let Claude summarize the uncommitted changes in the current git repository into a few bullet points.

Step 1: Confirm that skill-creator is in place

After starting Claude Code, type:

/skills

Expectation: You can see skill-creator in the list. If you can't see it, go back to section 02 and copy the skill-creator directory into the skills path to install it (remember to turn on proxy).

Step 2: Let it start building in plain language

In the input box, clearly state what you want (also state "when it triggers" along the way, to save it from asking further):

Help me create a skill using skill-creator.
Function: Summarize the uncommitted changes in the current git repository into 2-3 bullet points.
Trigger scenario: When I ask "what did I change", "summarize my changes", or "what things did I touch this time".
Name it summarize-changes.

Expectation: skill-creator is summoned and starts confirming your intent—it might ask you back about output formats or whether to build test cases. Just follow along and answer what it asks, focusing on whether it has written those trigger words like "what did I change" and "summarize changes" into the generated description (this is the lifeline in section 04).

Step 3: Let it drop the files into the personal directory

Confirm that it will write the skill to ~/.claude/skills/summarize-changes/ (personal directory, available for all projects). The SKILL.md it generates roughly looks like this—you should mainly check the frontmatter:

---
name: summarize-changes
description: Summarize the uncommitted changes in the current git repository into a few bullet points. Use when the user asks "what did I change", "summarize my changes", "what things did I touch this time", or wants to quickly understand the current state of the working tree.
---

## Current Changes

!`git diff HEAD`

## Your Task

Summarize the above changes clearly with 2-3 bullet points. If the diff is empty, just say "There are currently no uncommitted changes".

That line !`git diff HEAD` is the official "dynamic context injection" syntax: Claude Code will run this command first, replace this line with the actual diff, and then let Claude see the skill content. So what it gets is the actual changes in your working tree, not guessed out of thin air. This syntax was mentioned in article 27, and it comes in handy right here.

Step 4: Create some changes so the skill has something to summarize

Find any git project (if you don't have one, git init an empty one) and casually modify a file. For example:

cd ~/some-git-project
echo "// test change" >> README.md

Expectation: git status can see that README.md was modified and is in an uncommitted state.

Step 5 (The most critical): Verify that it actually gets "triggered"

This step is divided into two kinds of verification, the official documentation explicitly provides these two paths:

Verification A—Automatic trigger: Ask in plain language inside Claude Code (note, don't mention the skill name, just use natural phrasing and see if it thinks of it itself):

What did I change?

Expectation: If the description is written correctly, Claude will automatically invoke summarize-changes, spitting out a few points about the changes (e.g., "Added a line of comment at the end of README.md"). It being able to catch it itself = trigger successful, your description has passed the test.

Verification B—Direct call: In case it doesn't trigger automatically, hard-point it once again using the name:

/summarize-changes

Expectation: This time it will definitely run, similarly spitting out points about the changes.

How to judge success or failure:

Phenomenon	Explanation	What to do
Both Verification A and B output points	Perfect trigger	Call it a day
A does not trigger, B can run	description keywords are insufficient, the body is flawless	Let skill-creator optimize the description and add trigger words
Neither A nor B outputs points	File not created correctly / problem in the body	Check the path and SKILL.md body

Deeply comprehend the middle row—A does not trigger but B can run, which precisely proves the core argument of this article: the skill itself has no problem, the problem lies in "whether it is responsive", and being unresponsive is almost always the fault of the description. This is exactly the pitfall hand-writers have stepped into countless times without ever realizing it. At this time, letting skill-creator run through a "description optimization" can rescue it.

Running through these five steps, you have personally verified the complete chain of "setting up scaffolding → writing the correct description → dropping into the correct directory → creating changes → verifying automatic trigger / direct call". From now on, building any skill is essentially swapping content on this set of processes.

💡 One-sentence summary: When getting hands-on, focus on two things—whether there are real trigger words in the generated description, and whether it will appear automatically when you ask it in plain language; if it doesn't trigger automatically but /name can run, it's the fault of the description, let skill-creator optimize the description to add keywords.

---

07 A bonus: Package into .skill to distribute to others

Once a skill is built and its trigger is verified, if you want to send it to colleagues or the team, skill-creator can also help you package it into a .skill file—the other party can install it just by getting one file, without you holding their hands to teach them how to create directories.

What runs behind the scenes is a packaging script. You don't need to remember the commands, just let skill-creator help you package it:

Help me package this skill into a .skill file

Expectation: It will run the packaging script, compress the entire summarize-changes/ directory (including SKILL.md and all scripts/, references/) into one summarize-changes.skill file, and tell you the file path.

The significance of this step lies in distribution: the previous article 27 taught you how to "install others' skills", and the skill you built in this article, after packaging, happens to be exactly the thing others need to install over there—front and back are closed in a loop. Passing skills internally within a team is usually done this way: whoever builds a handy one packages it and tosses it into the group chat, others download it and have it upon installation, which is much more reliable than verbally instructing "you just set up the directory according to mine".

💡 One-sentence summary: Let skill-creator package the built skill into a .skill file, one file is enough for distribution; this perfectly connects with article 27 "installing others' skills"—what you build is what others install.

---

08 Summary

In this article, we walked all the way from "why you shouldn't just write by hand" to "personally building a triggerable skill" — the core is just one sentence: the difficulty of building a skill is not in writing the file, but in making it responsive, and skill-creator specializes in curing this.

Stringing the main points together for review:

What you need to do	Use what	Key point
Install the tool to build skills	Clone / copy the directory to the skills path	cp -r skill-creator ~/.claude/skills/ (independently published skill, not built-in to the marketplace)
Summon it to start building	/skill-creator or state needs in plain language	It will ask you back "what to do, when to trigger"
Make the skill responsive	Write a good description	What to do + when to use (including exact user words), slightly proactive
Choose storage location	Personal vs. Project directory	If it follows the person, put it in ~/.claude/; if it follows the project, put it in .claude/ and commit to Git
Confirm success or failure	Auto-trigger + direct call via /name	Auto-trigger failure = description's fault
Distribute to others	Package into .skill	A single file is enough to install, connecting with article 27

You should now be able to: Understand why writing SKILL.md by hand easily fails on triggers, use skill-creator to walk through the entire process of "setting up scaffolding → writing the correct description → testing triggers → packaging", personally write a "responsive" description, put the skill into the right directory, and verify that it is actually triggered. This ability to "build it right, make it responsive" is the watershed for you to upgrade from 'using others' skills' to 'forging your own toolchain'.

The commit skill that failed at the beginning was later rebuilt using skill-creator, and only a single sentence of description was changed before and after, and it has never dropped the ball since then. This is exactly where this tool is most valuable—it doesn't make you type more, it makes you step less into that invisible pitfall.

💡 One-sentence summary: Building a skill is hard because of the trigger, skill-creator completes things like "writing the correct description, running tests, revising on feedback" that are easily skipped when hand-writing—the key to knowing how to build skills is learning to clarify the trigger conditions, not just explaining the functions clearly.

---

Next article 29 "Agent teams" (Experimental, subject to change) — Up to this point, your Claude Code has always been acting as a "lone soldier": one conversation, one assistant, you one-on-one with it. But some tasks are too slow for one person to shoulder — can we assemble a project group and let multiple agents collaborate with labor divided, one managing architecture, one writing code, one running tests? The next article will take you to step from "lone soldier" to "team combat". Think about it: if you could have three Claudes working for you simultaneously at hand, what three things would you most want them to divide and conquer first?

---

Recommended Reading

• Web Version and Cloud: Putting Claude Code into the Browser and Phone
• VS Code Integration
• Slash Commands: One / to invoke all of Claude's quick actions