AI has gradually entered our daily work: writing code, generating content, and even making some decisions automatically.

But the more we use it, the more one problem becomes obvious:

AI is powerful, but not always stable.

Think about our experiences using Doubao or Qianwen. Even with the same prompt, you might get different results. The same workflow, executed again after some time, might also perform differently.

This uncertainty makes it hard to confidently use AI in production environments.

If you've been using AI for a while, you've probably noticed another problem: you're always repeating the same things.

To solve these problems, Anthropic launched Agent Skills in 2025, later releasing it as an open standard. Today, agents compatible with this standard, such as Claude and OpenAI Codex, can encapsulate reusable working methods through Skills.

Of course, domestic agent tools like Trae and CodeBuddy also support it.

Current agent tools can scan each other's directories. For example, if you already have Cursor installed and now want to try Trae, when you install Trae, it will automatically scan Cursor's user directory and retrieve Skills from there.

In the following articles, we will discuss what Agent Skills are, how they work, and how to correctly create and use a Skill.

But before understanding Skills, let's start with the problem itself.

Why You Are Always Repeating Yourself

Suppose you are using AI to review Pull Requests.

You usually don't just say "Help me review this code." Instead, you add more requirements: check for performance issues, follow project conventions, point out potential risks, and give improvement suggestions.

The next time you review code, you have to repeat all these requirements. And the next time, the same thing.

Over time, two situations usually occur:

• You repeatedly enter the same requirements every time;
• To save effort, you shorten the prompt, and the output quality drops accordingly.

Even if you are willing to enter the full requirements every time, the results might still be unstable.

The same task, with just a slight difference in the prompt, can lead to a completely different final output.

At this point, you might even start to wonder: are you training the AI, or is the AI training you?

We clearly need a more suitable way to organize these repeatedly used experiences and requirements.

This is the problem that Skills aim to solve.

What Exactly Is a Skill

A Skill is a set of reusable instructions that tell the AI how to handle a specific type of task. Of course, that might sound vague. More precisely, a Skill is usually organized as a directory, where the SKILL.md file carries metadata and core instructions. The directory can also contain scripts, reference materials, and other resources as needed.

In the past, we needed to rewrite prompts in every conversation; with Skills, these requirements can be defined once and then reused.

You can think of it as: organizing a piece of prompt into a workflow.

This workflow can clearly specify:

• What task to complete;
• What steps to follow;
• What format the final result should use.

Doing this reduces repetitive input, makes the output more stable, and makes it easier to share a mature working method with others.

However, a Skill is not just a saved prompt. It has two other very important characteristics: portability and composability.

Why a Skill Is More Than Just a Prompt

Portability

Agent Skills use an open file format. A Skill written according to the standard can be recognized by compatible agents like Claude Code and OpenAI Codex, without needing to rewrite a completely different workflow for each platform.

However, "portable" here means that the Skill's organizational format and core instructions can be reused. It does not mean it will produce exactly the same results on all platforms.

Different agents use different models, tools, permission mechanisms, and runtime environments. If a Skill depends on a tool or API specific to one platform, it will still need adaptation after migration.

Composability

An agent can discover multiple Skills and load the necessary parts based on the current task.

For example, in the same session, it can first use the code-review Skill to review code, then use the release-notes Skill to generate release notes based on the changes.

Two Skills, each responsible for a clear workflow, can also cooperate within the same task. It is portability and composability that make a Skill more than just a convenient piece of text to copy, but a long-term, accumulable workflow infrastructure.

Next, let's look at how a Skill actually works inside an agent.

How a Skill Is Loaded

At this point, you might have a question:

If dozens of Skills are installed, will the agent read all the instructions at once, not only consuming context but also confusing the model?

Usually not, because Agent Skills adopt a very important design: Progressive Disclosure.

In the initial stage, the agent typically only reads the name and description of each Skill and uses that to determine which Skill might be needed for the current task.

Only when a Skill truly matches the current task will the agent further read the complete SKILL.md. If it also references references/, scripts/, or other resources, those will be loaded or executed further as needed by the task.

In other words, agents using this loading mechanism do not stuff all complete instructions into the context at once. The initial names and descriptions still consume a small amount of context, but the truly detailed content is only loaded when needed.

Regarding this loading mechanism and how a standard Skill directory should be organized, we will continue the discussion with practical examples in subsequent articles.

What's the Difference Between Skill, Prompt, Tool, and MCP

When discussing AI Agents, you often see Prompt, Tool, MCP, and Skill mentioned together. These concepts are easily mixed up, but the problems they solve are actually different.

Concept	Main Role
Prompt	The requirements and context provided by the user for the current task, usually serving only this one interaction.
Tool	The actual capabilities an agent can invoke, such as accessing APIs, querying databases, running commands, or manipulating files.
MCP	An open protocol for connecting AI applications with external data, tools, and services.
Skill	Tells the agent how to organize instructions, materials, and tool calls for a specific task, forming a reusable workflow.

To put it more intuitively:

• Tool provides capability;
• MCP establishes the connection;
• Skill organizes the workflow.

A Skill does not replace Prompts or Tools; its main responsibility is to organize these elements into a repeatable working method.

After understanding these differences, the next question naturally arises: should every task be written as a Skill?

When Is It Worth Creating a Skill

Not every task needs a Skill.

If you only occasionally ask AI to write a birthday greeting, there's obviously no need to package it as a formal workflow.

But if a task fits the following situations, you can consider creating a Skill:

• The same instructions are repeated frequently;
• The task contains multiple fixed steps;
• You want relatively stable and predictable output.

The judgment criterion is actually simple: can it reduce repetitive work and improve the reliability of the work results?

If the answer is yes, then this task might be suitable for organizing into a Skill.

Three Types of Skills in Reality

From actual usage scenarios, Skills can be roughly divided into three categories.

1. Document and Asset Creation

This type of Skill is used to stably produce documents, presentations, design drafts, or code.

For example, a company can create a report generation Skill so that the agent always follows established brand guidelines; a frontend team can also create a component generation Skill so that the output code conforms to their design system and project structure.

2. Workflow Automation

This type of Skill is suitable for tasks that involve multiple steps and need to follow a fixed method, such as Sprint planning, material research, or customer onboarding processes.

A Skill saves not only the task goal but also the correct practices already validated by the team.

3. Enhancing MCP Usage

This type of Skill is built on top of MCP integrations, used to tell the agent how to correctly use an external service.

MCP is responsible for connecting the service, while the Skill is responsible for providing the operation sequence, judgment conditions, and domain experience.

If you are only creating Skills for yourself, the most common ones are usually the first two types. If you need to provide capabilities to other users, especially when also providing an MCP Server, then the third type of Skill can often be the part that truly makes a difference.

Now, we know what a Skill is, roughly how it works, and under what circumstances it's worth creating one. Let's tie these concepts together with a simple example.

A Simple Code Review Skill

Without a Skill, we might enter the following prompt every time:

Review this code, check for performance issues, confirm if it follows best practices, and give improvement suggestions.

The next time we encounter the same task, we enter it again.

With a Skill, these requirements can be defined once. A minimal Skill looks roughly like this:

---
name: code-reviewer
description: Reviews pull requests for performance issues, code style, and best practices. Use when the user says "review code", "check PR", or "analyze function".
---

# Code Review Skill

When reviewing code:

1. Check for potential performance bottlenecks;
2. Read `references/style-guide.md` to confirm if the code complies with project conventions;
3. For complex performance issues, run `scripts/analyze_perf.py --file {filename}`;
4. Propose improvement suggestions with specific examples;
5. Flag potential security risks.

## Output Format

- Issue overview;
- Line-by-line comments for key issues;
- Modification suggestions including code examples.

If you prefer the English version:

---
name: code-reviewer
description: Reviews pull requests for performance issues, style violations, and best practices. Use when user says "review this code", "check this PR", or "audit this function".
---

# Code Review Skill

When reviewing code:
1. Check for performance bottlenecks
2. Verify style guide compliance by consulting `references/style-guide.md`
3. For complex performance analysis, run `scripts/analyze_perf.py --file {filename}`
4. Suggest specific improvements with examples
5. Flag any security concerns

## Output format

- Summary of findings
- Line-by-line comments for critical issues
- Suggested fixes with code samples

Where to Put It

Take Codex as an example: if you want team members to be able to use the code review Skill in this project, you can place it under .agents/skills/code-reviewer/ in the repository root directory:

your-project/
└── .agents/
    └── skills/
        └── code-reviewer/
            ├── SKILL.md
            ├── references/
            │   └── style-guide.md
            └── scripts/
                └── analyze_perf.py

When you start Codex in this repository or its subdirectories, it will scan .agents/skills/ between the current directory and the repository root, thus discovering this Skill.

If you want to use it for yourself across all projects, you can also place it in the user directory, i.e., ~/.agents/skills/. Skills placed in the user directory can be used anywhere, not just limited to projects.

.agents/skills/ is a common project-level directory for Agent Skills. Compatible agents that follow this convention and scan this directory can discover the Skills within; however, the discovery locations and loading rules may still differ between tools, so it's best to check the corresponding tool's documentation before use.

As you can see, a Skill is not just SKILL.md. It can also contain reference materials like references/style-guide.md and executable scripts like scripts/analyze_perf.py.

The agent will first read SKILL.md, and then, based on the instructions within, continue to read reference files or execute scripts when truly needed.

As for how a Skill directory should be organized, we will expand on that in Part 2.

One more easily overlooked issue to note here: a Skill can contain scripts and can also guide the agent to access files and external services. Therefore, do not directly install Skills from unknown sources. Before using one, you should at least check the SKILL.md, scripts, dependencies, and the resources it intends to access.

At this point, a reusable code review Skill is complete.

The same task, the same inspection standards, no longer require repeatedly entering a long prompt. More importantly, this method can be continuously modified and improved through use.

To Be Continued

Now, we have understood what a Skill is, why it is worth using, and how progressive disclosure reduces context pressure. These contents are the foundation for subsequent practice.

The following articles will discuss:

• Creation: Writing the first SKILL.md, designing trigger descriptions, and correctly organizing instructions, examples, and directory structure;
• Testing: Measuring the Skill's trigger accuracy, handling edge cases, checking output consistency, and confirming whether it truly works as expected;
• Expansion: Sharing, version management, team deployment, and how to avoid common pitfalls.

The ultimate problem this series aims to solve is simple:

Don't stay stuck writing prompts repeatedly. Instead, gradually solidify validated methods into workflows that are truly reusable, testable, and shareable with confidence.

In the next article, we will start actually creating the first Skill.