Complete Beginner's Guide to Agent Skills: Building Your First Skill

Everyone working with AI has encountered this problem:

You teach it something, start a new conversation the next day, and everything resets to zero.

You spend three days fine-tuning a workflow, going back and forth with Claude to get it right, only to have to explain it all over again the next day.

You save prompts in your notes and paste them every time, but pasting a 500-word instruction every day for a month makes you wonder: is this really how AI should be used?

Skill was born specifically to solve this problem.

It was launched by Anthropic in October 2025 and became an open standard in December.

Today, the whole internet is shouting "Skills change productivity," but most people have only heard of it without truly understanding the difference between Skills, prompts, knowledge bases, MCP, and agents—let alone building one themselves.

This article explains it all at once.

First, understand one thing: Skills are not tied to any specific AI.

Many people hear "Claude Skills" and think it's a Claude-exclusive feature, but it's not. Agent Skills is an open standard launched by Anthropic; Claude is just the leading implementer.

The same Skill folder can be placed in ~/.claude/skills/ for Claude Code, ~/.cursor/skills/ for Cursor, or used with OpenAI Codex, Gemini CLI, VS Code Copilot, and JetBrains Junie.

The Skill you write today can be seamlessly moved to another Agent tomorrow; your investment won't be locked into one company.

This article will primarily use Claude Code as an example (since it's the standard-setter with the most complete ecosystem), but all principles, writing methods, and troubleshooting experiences apply to all AI tools that support Agent Skills.

When you see "Claude Skill," think "Agent Skill."

1. What Exactly is a Skill?

Definition in one sentence:

A Skill is a folder, centered around a Markdown file called SKILL.md, that tells an AI how to stably execute a specific type of professional work according to an SOP you define.

It encapsulates "how a certain type of thing should be done" into a reusable, automatically triggered capability module.

Essentially, it's an "expansion pack" for general-purpose AI.

General AI is like a bare-bones machine—intelligent but lacking domain knowledge. A Skill is a plug-and-play module: install a "Xiaohongshu Style Skill," and the AI immediately becomes an editor who understands your brand; install a "Weekly Report Skill," and the AI immediately generates reports in your company's format.

And this "expansion pack" isn't picky about the AI: Claude Code, Codex, Cursor, Gemini CLI, and Junie all recognize the same format.

You are making an Agent Skill, not a Claude-exclusive script.

Boundaries with four other concepts:

Many people mix up Skills with prompts, knowledge bases, MCP, and agents, but they are distinct:

Common analogies:

• Prompt = Sending a WeChat message to an employee; they forget it once it's done.
• Skill = Writing a manual for the employee and putting it on their desk, along with a toolbox.
• Knowledge Base = A library that tells you what exists in the world.
• MCP = Various kitchen utensils that solve the "can it be done" problem.
• Agent = The entire employee system, with memory and decision-making; a Skill is just one part of it.

These four are not mutually exclusive.

In actual work, they are often combined: MCP lets Claude connect to Reddit to scrape data, a Skill teaches it how to filter/classify/recommend that data, a Knowledge Base provides brand materials, and the Agent is the entire system running the process.

2. Architecture and Operating Mechanism

File Structure

Each subdirectory solves a different problem but serves the same goal—saving context and stabilizing quality:

• scripts/: Accurate calculations without consuming context.
• references/: Loaded on demand to avoid wasting space.
• assets/: Standardizes output formats.

Three-Layer Progressive Disclosure—The Soul of Skill Design

The core mechanism of a Skill is three-layer loading, which is why a dozen Skills can coexist without blowing up the context:

For example:

When Claude starts, it only flips through the "covers" of all Skills to decide which one to use; only when it's time to work does it open the main text; and only when it needs to check an appendix does it flip to the references.

This mechanism allows you to have 17 Skills active simultaneously without clogging the 200K context window.

YAML Metadata

Field descriptions:

Description Determines Success or Failure

In the three-layer architecture, the L1 description is the most critical—it determines whether your Skill will be triggered.

Key facts:

1. Claude only reads the descriptions of all Skills at startup.
2. It makes semantic judgments based on the description, not keyword matching.
3. Claude tends to be conservative: if unsure, it won't trigger. In tests, vague descriptions had a trigger accuracy of only 55%.

Negative example (will never be triggered):

[Vague description]

Positive example (Anthropic's recommended "pushy" style):

[Specific description]

Three Golden Rules for writing descriptions:

1. Write WHAT + WHEN together: Say what it does and when to use it.
2. List trigger words in both Chinese and English: Match whatever the user says.
3. Be pushy rather than conservative: Anthropic explicitly states that the main problem is under-triggering.

3. Core Principles for Writing Good Skills

Three Main Principles

How to handle freedom:

Five Design Patterns

Anthropic summarized five Skill design patterns from early users:

Useful Skills often mix multiple patterns. You don't have to follow them strictly, but knowing they exist helps you design with more structure.

Golden Rule: Use "Why" instead of "Must"

This is a quote from the skill-creator (Anthropic's official meta-skill for making Skills) source code:

"Try to explain to the model why things are important in lieu of heavy-handed musty MUSTs."

Negative example:

[Strict MUST rules]

Positive example:

[Explaining the reasoning]

In the first case, Claude will only follow those two rules. In situations not covered by the rules (like a seemingly safe but risky command), it gets stuck. In the second case, Claude understands "why safety is important" and will lean toward caution even in gray areas.

Reasons allow the model to generalize; rules only cover scenarios you can think of. The only exception is output format: mechanical requirements like "output must use this template" have no "why" to explain, so just hardcode them.

Information Ownership: Don't Repeat Yourself

skill-creator also has an ironclad rule:

"Information should exist in SKILL.md or references—not both."

SKILL.md should only contain basic procedures; move details to references/. Duplicate storage leads to inconsistencies when you update one place but forget the other.

Files to Avoid

Skills are for AI, not humans. Don't add README.md, INSTALLATION_GUIDE.md, QUICK_REFERENCE.md, or CHANGELOG.md. These human documents just waste context.

4. Building Your First Skill

Anthropic's Official Six Steps

The standard process defined inside skill-creator:

1. Capture Intent: Clarify what to do / when to trigger / output format / testing needs.
2. Interview & Research: Edge cases / I/O formats / example files / dependencies.
3. Write SKILL.md: Write the draft.
4. Test Cases: Write 2-3 real test cases.
5. Run & Evaluate: Run with-skill and baseline (no skill) side-by-side for a benchmark.
6. Iterate: Modify based on feedback and rerun until satisfied.

Four Fast Paths for Regular Users

skill-creator: The Meta-Skill for Writing Skills

I highly recommend installing Anthropic's official skill-creator first. It's a Skill designed to help you make Skills. Once started, Claude will interview you—asking about your workflow, trigger conditions, and boundaries—then automatically generate the SKILL.md and folder structure.

Installation command:

[Command]

It doesn't just produce output; it also helps you:

• Eval: Automatically generate test cases to verify if the Skill triggers correctly.
• Improve: Automatically optimize descriptions and instructions based on test results, using a 60/40 train/test split to prevent overfitting.
• Benchmark: Track success rates and token usage, even running A/B tests between two versions.

A Minimal Example

Suppose you are a Xiaohongshu food blogger who wants to rewrite regular recipes into Xiaohongshu style:

Place it in ~/.claude/skills/xiaohongshu-recipe/SKILL.md. In the future, saying "convert to Xiaohongshu version" will automatically trigger it.

From creating the file to using it takes less than 20 minutes.

5. Installation, Storage, and Cross-Tool Usage

Loading Priority (4 Levels)

Claude Code searches in the following order; more specific locations have higher priority:

Tip: Unless it's project-specific, keep them in the personal ~/.claude/skills/ directory for unified management.

Three Installation Methods:

Remember to restart Claude Code after installation.

Cross-Tool Compatibility (Emphasized Again)

As mentioned, Skills aren't tied to Claude. Here are the path comparisons:

Operational significance: You can symlink the same SKILL.md folder to different tool directories. This is the biggest benefit of Agent Skills as an open standard.

Domestic User Pain Points

• Official Claude is expensive: Use proxy APIs for better cost-performance.
• CC Switch: An open-source tool to manage and switch multiple API configurations (github.com/farion1231/cc-switch).
• Native installation is more stable than npm: curl -fsSL https://claude.ai/install.sh | bash.

6. Advanced—Multi-Skill Collaboration Architecture

Granularity

Core Principle: One clear task per Skill. Don't make a "universal Skill."

If the granularity is too coarse, the description becomes unclear and triggers are imprecise. If it's too fine, management costs rise. A reasonable granularity is one Skill per category of problem, with a SKILL.md body of about 200-500 lines.

Case Study: Blog Writing Skill Suite

Don't make one "All-in-one Writing Skill." Split it into 5 collaborating Skills:

Collaboration mode: The main Skill explicitly calls other Skills in its ## Steps section.

Benefits of this split:

Five Engineering Experiences

1. Fine granularity: One clear task per Skill.
2. Explicit collaboration: Use ## Steps in the main Skill to call others.
3. Scripts for calculation: Use scripts for SEO character counts or link statistics; don't let the model estimate.
4. Independent style guides: Put stable knowledge (writing style/brand specs) in references/ so you only change one file to update the style.
5. Template fallback: Templates provide a baseline guarantee so the output isn't too far off.

7. Professional Evaluation and Iteration

Eval System:

The standard process from skill-creator:

1. Write test prompts in evals/evals.json.
2. Run with_skill and baseline (no skill) simultaneously for a double-blind comparison.
3. Score each assertion using agents/grader.md.
4. Use aggregate_benchmark to output a report on pass_rate / time / tokens.

Automatic Description Optimization

The most valuable part of skill-creator is Description Optimization:

• Write 20 trigger eval queries (8-10 should trigger + 8-10 should not).
• Difficulty: "Near misses" for non-triggers—queries that share keywords but need other tools.
• Optimization script: 60% train + 40% held-out test to prevent overfitting.
• Run 5 rounds and pick the description with the highest test score.

Good examples of triggers: Don't just write "extract PDF table"; write like a real user:

"ok so my boss just sent me this xlsx file (it's in my downloads, called something like 'Q4 sales final FINAL v2.xlsx') and she wants me to add a column that shows the profit margin as a percentage."

This includes file paths, personal context, column names, casual language, and potential typos.

Iteration Mindset

Four points from skill-creator:

1. Generalize from feedback: Don't add fiddly rules for a single case. If a problem recurs, try a different metaphor or workflow.
2. Keep it lean: Check transcripts for time-wasting instructions and delete parts that don't help.
3. Explain why: LLMs have a theory of mind and can generalize.
4. Find redundant work: If every sub-agent is writing create_docx.py independently, bundle it into scripts/.

The first version is never perfect.

A real iteration case: An author's /daily skill took 6 versions to stabilize.

• v1: Unclear steps, wrong paths.
• v2: Added content discovery system integration.
• v3: Fixed weekly progress calculation errors.
• v4: Added auto-triggers (Tuesday reminders, end-of-month archiving).
• v5: Added iPhone light mode (skipping Python steps on mobile).
• v6: Finally "good to use."

A Skill is not a set-and-forget config file; it's a living document of your workflow.

8. When Should You Make a Skill?

Not everything is worth a Skill. Only act when one of these three signals appears:

Conversely: When NOT to make one

• One-off tasks: Just use a prompt.
• Over-encapsulation: Splitting Skills after only three uses; maintenance costs outweigh benefits.
• Chasing perfection: Trying to make v1 perfect; you'll find the needs were imaginary once you actually use it.

9. Pitfall Checklist

10. Ecosystem and Must-Have List

Skill Resource Map

Must-Have Skill List

11. Commercial Potential of Skills

Skills are more than personal efficiency tools; they are redefining how AI applications are produced.

In the past, developing a vertical AI app required long cycles, high costs, and technical teams. Now:

• Zero-code threshold: Build vertical Agents without coding.
• Rapid validation: Development cycles compressed from weeks to minutes.
• API Service: Package a Skill as an API to empower existing products.
• Skills as products: Similar to selling prompt collections, but with higher value.

Real cases:

• Article-Copilot: A single Skill for the entire chain from material cleaning to writing.
• AI Partner Skill: Gives general Agents deep memory to become true companions.
• Interview Prep Skill: Generates full reports based on company/job/resume. Someone used this to get an interview at Hithink RoyalFlush.
• Super Huang's method: Dozens of Skills + cron jobs running hourly reports while he sleeps.

Anyone deep in an industry can distill their experience into a Skill to save time or sell as a product.

Conclusion

If an Agent is the body of the AI world, a Skill is the soul injected into it.

It's like the relationship between Steam and the Workshop; extensible architecture gives games infinite life.

Skills aren't hard—they are just Markdown with some structure. But the trend they represent is vital: AI moving from "you have to teach it every time" to "you only teach it once."

And the standard is open. The Skill you write for Claude Code today can be moved to Cursor or Gemini tomorrow.

To those still watching:

Skills aren't designed; they grow out of repeated labor.

Run one thing first, then encapsulate it. Good workflows are iterated, not planned.

Open your terminal, install skill-creator, and turn that paragraph you've repeated three times today into your first SKILL.md.