I Wrote This Blog in Just 10 Minutes Using Skill | A Beginner's Guide to Skill

Author: I Love Delicious Crab Burgers Tags: AI Programming

After reading this, you will understand what Skill really is, how it is triggered, and why it can't be 'long and comprehensive'; then follow along with me to write a mini Skill that you can directly copy into .claude/skills/; finally, take away a judgment—when not to write a Skill.

Background and Motivation

After using Claude Code for a while, I found myself doing repetitive tasks: organizing random notes into blog drafts, structuring scattered thoughts into document outlines, and running certain checks according to a fixed process. Every time, I had to re-explain the background, steps, and tone requirements—very annoying, and when the explanation wasn't clear enough, the results were inconsistent.

Skill is here to solve this: Write the process for doing a certain type of task into a 'manual for Claude,' write it once, and use it repeatedly.

But the most frustrating part when starting out isn't the lack of documentation—it's that there's piles of documentation, yet you don't know 'how this thing actually works, or how to write one that works.' This article is for you at that stage: it doesn't aim to cover every detail, only to make you truly able to use it, truly able to write your first Skill.

Target Audience: Developers who know a bit of Claude Code and are just getting started with Skill.

Three things you'll take away after reading:

1. Use existing Skills correctly (know how they are triggered, how to choose them, and what pitfalls to avoid)
2. The ability to write your first Skill (with a complete, copyable file attached)
3. A set of criteria for deciding 'whether to write a Skill, and which mechanism to use'

---

What Exactly Is Skill

In one simple sentence: A Skill is a 'manual for Claude' stored on disk—telling it what task to handle, what process to follow, and which tools to use. Write it once, and it will stably perform this type of task for you repeatedly.

The smallest Skill consists of just one file:

.claude/skills/<name>/SKILL.md

It is divided into two parts:

---
name: note-to-draft
description: One sentence explaining what this skill does + trigger scenarios
allowed-tools: [Read, Write, Edit]   # Optional, restricts available tools
---

## Workflow

1. What to do in the first step
2. What to do in the second step
...

• name: The skill name. Used for manual invocation (/note-to-draft).
• description: The trigger switch. This sentence is semantically matched to decide when Claude should think of using this Skill.
• allowed-tools: Principle of least privilege (optional). Restricts which tools this Skill can use, leaving it no room for shortcuts.

Note: The frontmatter must be wrapped by --- top and bottom, missing one --- means it won't work—this is the number one pitfall for beginners, which will be mentioned again in the pitfalls checklist later.

Core Mechanisms

Understanding why Skill is designed this way is the prerequisite for writing and using it correctly. This section covers three things: how it is triggered, why you can't stuff all the content into the context at once, and the boundaries between it and rules/hooks.

Trigger Mechanism: Description is the Switch

The biggest misconception for beginners is: Thinking the description manages the process and the body manages the trigger—it's actually the opposite.

• description manages the trigger: Claude reads your input, semantically matches it with a Skill's description, and then 'invites it on stage.'
• The body manages the behavior: After triggering, the workflow in the body takes effect.

So when writing a Skill, description is the top priority. It needs to satisfy two things:

1. Clearly state the function in one sentence—'Organize casual notes into a structured blog draft'
2. Include trigger words—'organize notes,' 'notes to blog,' 'turn ideas into articles,' 'polish into prose'

Don't be greedy with trigger words; stuffing in too many dilutes the precision of semantic matching and easily causes false triggers.

Besides automatic semantic matching, you can also manually call it by name: enter /skillname to bypass semantic matching and trigger it directly. This is the most reliable way when testing a Skill.

Progressive Disclosure: Why You Can't Stuff Everything In at Once

This is the most ingenious design of the Skill mechanism, and the key to understanding 'why Skills should be written small.'

Let's do the math first. Suppose you have accumulated 20 commonly used Skills, each ranging from dozens to over a hundred lines, roughly a few thousand tokens. If you stuffed the entire content of all Skills into the context every time:

• 20 × several thousand tokens ≈ tens of thousands of tokens of context, carrying this burden at the start of every conversation;
• And the vast majority of Skills aren't needed this time—unneeded things are pure noise for the model, and will also interfere with its judgment on the current task.

So Skill uses progressive disclosure, loading in three layers:

1. At the start of the conversation, only the description of all Skills is loaded—occupying very little;
2. After a Skill is triggered, its body is loaded;
3. Auxiliary files mentioned in the body (references/, scripts/), are read only when needed.

The essence of this design is to improve the signal-to-noise ratio of the context and save tokens. It also directly derives the first iron rule of writing Skills:

'Small and precise' > 'Long and comprehensive'.

Progressive disclosure is the guarantee at the mechanism level, and 'writing small' is the author's conscious effort—two sides of the same coin.

The Three Brothers: Skill / Rule / Hook

When starting out, it's easy to mix up the several mechanisms under .claude/. I use 'three brothers' to remember them:

The three mechanisms do not replace each other; their applicable scenarios differ:

• rule (standing orders): Project-recognized norms, expected to take effect by default in every conversation—use a rule.
• Skill (on-demand manual): An SOP crystallized for a specific task, loaded only when needed—use a Skill.
• hook (node interceptor): Scenarios requiring 100% triggering, such as intercepting dangerous commands like rm -rf—must use a hook.

Here lies the most important judgment: Hooks are deterministic, Skills are probabilistic.

Skill triggering relies on LLM semantic matching—it can miss triggers and also falsely trigger. Hooks, on the other hand, are attached to lifecycle nodes and will inevitably trigger at that point. Therefore, any scenario that 'must be intercepted, cannot be gambled on,' cannot be patched up with a Skill; a hook must be used. Use a Skill only where probability is tolerable.

Practical Example

Theory is done, let's get hands-on. This section walks you through writing a real Skill, seeing its evolution from an incorrect version to a correct version, and the most common pitfalls for beginners. After reading, you'll have something directly usable.

Hands-on: Write Your First Skill

I'll walk everyone through a real example: 'Organizing casual notes into a blog draft'—this is exactly what I do every day.

Create the file .claude/skills/note-to-draft/SKILL.md under your project, with the following content (you can copy it directly):

---
name: note-to-draft
description: Organize casual notes, scattered thoughts, and meeting records into a structured blog draft. Trigger scenarios: organize notes, notes to blog, turn ideas into articles, polish into prose.
allowed-tools: [Read, Write, Edit]
---

## Workflow

1. **Collect Raw Material**
   - Read the note content provided by the user (text, files, or snippets from the conversation)
   - Identify core viewpoints, key arguments, and ideas to be expanded
   - First, paraphrase to confirm understanding; proactively ask questions if material is insufficient or key information is missing

2. **Refine Theme and Structure**
   - Deduce a clear theme and title from the material
   - Plan the structure: Introduction → Body (2–4 paragraphs) → Conclusion
   - If the material cannot support a complete article, clearly tell the user what is missing

3. **Expand into a Blog Draft**
   - Write according to the planned structure, colloquial but organized
   - Supplement transition sentences and contextual connections
   - Retain the original text's unique expressions and personal viewpoints; do not over-'officialize'

4. **Output and Confirmation**
   - Output the complete draft, marking what is retained from the original and what is supplemented and expanded
   - Ask if adjustments to style, additions/deletions of paragraphs, or further polishing are needed

How to verify it actually works after writing?

1. Save the file;
2. Enter /note-to-draft in the conversation to manually trigger it, or directly say 'Help me organize my notes...' to see if it is triggered by semantic matching;
3. See if it strictly follows the 4-step process, and whether it skips the 'paraphrase to confirm' step.

This cycle of 'write → test trigger → retest' is recommended to be included in version control, retesting after every change.

Wrong Way vs. Right Way

The Skill above wasn't written in one go; it was revised from several typical mistakes. Listing them out is more useful than a hundred theoretical statements:

Wrong Way	Right Way	Explanation
Description writes 'Trigger when the user says...'	Directly list trigger scenarios	Meta-wording provides no matching information, purely takes up space
Frontmatter missing --- wrapping	Wrapped by --- top and bottom	Won't work without wrapping
Body only has 4 words like 'Collect material, Refine theme...'	Each step gives executable actions	The model then knows specifically how to work
Body written long and comprehensive	Small and precise, auxiliary content placed in references/	Burns context, lowers signal-to-noise ratio

Pitfall Checklist / FAQ

Q: Where is the Skill placed? Personal level: ~/.claude/skills/; Project level: .claude/skills/. Don't put it in .claude/rules/—that's where rules go, not Skills.

Q: Is Skill triggering 100% reliable? No. Semantic matching is probabilistic; it can miss triggers and falsely trigger. For scenarios requiring determinism (like intercepting dangerous commands), use hooks; don't gamble on Skills.

Q: What prerequisite knowledge is needed to write a Skill? None. It's just a plain text markdown manual; if you can write documentation, you can write a Skill. The hard part isn't writing the file, it's figuring out what problem this Skill should solve, and how to break down the process into steps the model can follow.

My Thoughts: The Moat Isn't in the Skill, It's in the Methodology

A Skill file is essentially plain text, its replication cost approaches zero. Anyone can copy your SKILL.md—so the Skill itself has no barrier.

The real barrier lies in three things that cannot be copied:

1. Knowing what Skill to write (insight into one's own workflow);
2. Knowing how to write it well (how to polish trigger words, how to break down steps, how to add guardrails);
3. Knowing how to iterate (finding it doesn't work well after one run, how to modify it).

Some might retort: Isn't a Skill just a markdown file, what methodology is there to speak of? My answer is: Precisely because it's plain text, any single Skill is worthless; what's valuable is the tacit knowledge crystallized around it.

But here's a dose of cold water: A Skill won't run more accurately on its own. It's just a text file; it won't update itself. The so-called 'running more accurately over time' relies on someone manually writing back the experience from each execution—which plan won the last A/B test, and why—into the SKILL.md.

So a more precise statement is:

The Skill is the carrier, the feedback loop is the moat; and the prerequisite for the loop to hold is maintenance discipline.

When Not to Write a Skill

Knowing when to write is important, but knowing when not to write is even more so. Judge with three questions:

Worth writing a Skill for are those things that are high-frequency, reusable, and have a relatively stable process. Beginners are advised to first write 1–2 'small and precise' process Skills used daily, polish the description trigger words well, and then gradually expand.

References

• Claude Code Official Documentation · Skills Section: The authoritative source on the mechanism; worth reading through the frontmatter field descriptions once before writing a Skill.

Final Words

This blog itself is a live demonstration of a Skill—'organizing notes into a draft' is exactly what the note-to-draft Skill does. The learning curve for Skill isn't long, the hard part is writing the first one.

I strongly suggest you do one thing right now: pick one of the most annoying repetitive tasks you have, write a mini Skill following the structure in this article, place it in .claude/skills/, then enter /skillname to test it once. Once it runs through, you have your first Skill.

Due to the length and positioning of the article, more advanced content was not written: how to improve the accuracy of semantic matching, how to split tasks, how to allocate tasks (which mechanism to use), how to use tools well (including MCP). If you want to know, tell me in the comments—if many people want to see it, I will write a separate article; your feedback determines what I write next.