Author: AI Product Ayin

I read a blog written by the Anthropic team titled "Lessons from building Claude Code: How we use skills." This is probably the most in-depth practical summary I have seen about Skill so far.

Skill is not complicated, but I feel it's not that easy to really do Skill well.

I remember when Skill first became popular, everyone particularly liked to create various writing styles Skill, writing Skill. It seemed that as long as you input your writing style, the model could stably output in that style.

But later when I tried it myself, I found that many times it was simply unworkable.

Because a writing style Skill might involve inserting thousands or even tens of thousands of words. Once Skill is loaded, the context takes up a significant portion. When the context is heavy, the model's thinking ability tends to decline.

In the end, it often appears that while the style is learned, the content becomes shallow, and the analytical ability also weakens.

There's another common situation.

Many people like to stuff all kinds of operation instructions into Skill. What to do first, what to do second, what to do third. As a result, when you run it, you may find that the model's execution is unstable.

I slowly came to understand that much of this repetitive execution work is actually better suited to be crystallized into Script rather than written as long Instructions.

After reading this article from Anthropic, my biggest realization is that many people are actually using Skill, but may not truly understand Skill.

Skill is essentially about Context Engineering. When to put knowledge into Skill, when to break it into References, when to write it into Script, when to use Gotchas to constrain the model—there is a lot of experience in this.

Once you understand how Skill operates, looking back at those excellent Skills, you'll find that they are never solving the problem of prompts but addressing context, experience accumulation, and capability reuse issues.

If you want to study Skill in depth, I highly recommend reading two articles:

https://claude.com/blog/lessons-from-building-claude-code-how-we-use-skills

https://research.perplexity.ai/articles/designing-refining-and-maintaining-agent-skills-at-perplexity

#01 Do Not Write Nonsense

Skill essentially distills the "tacit knowledge" within the organization. So, do not repeat the common knowledge it already knows in Skill. What is truly valuable is information that the model does not know at all.

Anthropic often emphasizes that what Skill should really write are Gotchas, which are common pitfalls.

For example:

1. This table cannot be sorted by created_at

2. Staging returning 200 does not mean success

3. request_id and trace_id are the same thing

Because this information often exists within employees' experiences. So always remember what the essence of Skill is.

Skill = Writing down the experiences of skilled workers.

Through Skill, distill the experiences that were originally scattered in different people's minds.

#02 Skill is Actually Context Engineering

This might be one of Anthropic's most profound viewpoints.

Skill is not a markdown file, but a folder. For those who have used Skill, this may sound like nonsense.

But I have been pondering this for the past couple of days and gradually realized: they intend to use the folder format to express the idea of Context Engineering.

Let’s take another look at a typical Skill structure:

skill/ ├── SKILL.md ├── references/ Put detailed explanations, API references, boundary conditions ├── scripts/ Put executable scripts ├── examples/ Put examples ├── assets/ Put templates, images, fixed materials

When invoking a particular Skill, the model first reads SKILL.md. If we stuff all the information into this file, it will quickly lead to context explosion.

Assuming this is a payment troubleshooting Skill, it contains both explanations of Stripe error codes and historical fault cases, as well as troubleshooting scripts and final report templates.

If all this content is crammed into SKILL.md, every time the Skill is called, Claude has to read it again.

Even if the user only wants to confirm the meaning of an error code, or just check why a payment status has not been updated. A lot of unnecessary information will also be stuffed into the context.

Anthropic's thinking is completely different.

SKILL.md is more like a navigation page. Its job is to tell the model to look in references for corresponding explanations when encountering Stripe errors.

When historical cases need to be referenced, go to examples to check similar problems. When it's time to really execute troubleshooting actions, run the scripts in scripts, and finally use the templates in assets to generate the troubleshooting report.

The whole process is gradually exposed.

I strongly recommend everyone to save the following image.

#03 Try to Use Scripts

Do not let the model waste limited context and reasoning ability on repetitive labor. Leave these tasks to scripts.

For example. Many people write Skill like this:

1. Query registration data; 2. Query payment data; 3. Calculate conversion rate; 4. Analyze abnormal causes.

This writing style is certainly fine. The model can accomplish it. But every time it executes, it has to redo the entire analysis process from scratch.

Querying data, organizing data, handling various boundary situations—these tasks are all repetitive.

Since these capabilities have been validated countless times, why put the model through the process of reinventing the wheel? It’s better to directly provide concrete scripts.

Moreover, by using scripts, Skill execution will also be more accurate and save tokens.

From this perspective, the Scripts in Skill are actually crystallizing organizational capabilities. Behind every script, there are often best practices that the team summarized after encountering numerous pitfalls.

By solidifying these abilities, Claude can work based on these experiences every time instead of starting from scratch again and again.

Thus, I increasingly feel that in Skill, Instructions and Scripts address two different levels of problems.

Instructions provide experience and judgment, while Scripts offer capability and execution.

For example, a payment troubleshooting Skill might have a sentence like this:

If Stripe returns 200, do not directly assume the payment is successful; further check the payment_events table.

This belongs to Instructions because it is experience, while check_payment_events() belongs to Script because it is an execution capability.

If only Script exists, the model knows how to check but may not understand why to check.

If only Instructions exist, the model knows it should check but has to implement it anew each time. Both are indispensable.

#04 Description Is More Like a Routing Rule

Many people’s way of writing Skill Descriptions is inherently wrong.

Because everyone is used to writing functional introductions. For example: PR Management Skill helps users monitor PR status, handle CI issues, and automatically complete merges.

But the problem is that the model does not search for Skill based on function; when Claude Code starts, it first scans all Skill names and Descriptions.

Then based on the user's current question, it determines which Skill to load.

So the most important information in the Description is not what this Skill can do, but in what situation it should be loaded.

In fact, the Description takes on the entire routing work of the Skill.

In the real world, very few people would say, "Help me call a PR management tool." People are more likely to say: "Help me keep an eye on this PR," "CI is down again," and the like.

So a good Description should try to convey the user's intent rather than list functionalities.

I even think there is a particularly simple method to check this.

After writing the Description, delete the entire Skill, keeping only that one line of Description. Then ask yourself: after the model sees the user's question, can it know when to load this Skill?

If it can't, then it's likely that revisions are needed.

#05 Management and Distribution of Skills

Another point is about the management of Skills.

When one person uses a Skill, it's actually very simple. Just write a few Skills, maintain them, and upgrade them on your own. But I believe that most teams will encounter the same problem later.

When the number of Skills increases from a few to dozens, or even hundreds, how should these Skills be managed? How to upgrade them? How to distribute them to team members?

Anthropic's experience in this aspect I find quite worth referencing.

When the team is relatively small, Skills follow the code repository directly. They can be placed in the project's .claude/skills directory. Everyone shares the same set of Skills and the same working methods.

However, as the number of Skills increases, a new problem arises.

When Claude Code starts, it scans the names and Descriptions of all Skills and then determines which Skill should be called for the current task. The more Skills there are, the higher the routing cost.

This is also why Anthropic later began to create a Marketplace. But what's more interesting is their way of managing the Marketplace.

Many companies encountering this problem often respond by establishing a set of approval processes. Whoever writes a Skill must first submit an application; after passing the review, it enters the official Skill library. We did the same thing internally before, but it was quite heavy. Management for the sake of management.

I found that Anthropic's organization is much lighter.

Let new Skills spread within a small scope, allowing colleagues to install and use them on their own.

If more and more people start using it, it indicates that this Skill indeed solves a real problem. At this stage, the author can then submit it to the formal Marketplace.

So they do not first discuss whether the Skill has value; instead, they first let it go through the validation of real usage scenarios. As more people use it, it naturally enters the formal system. Thus, the Skills that remain are basically the Skills that the team truly needs.