Anthropic has finally 공개 their internal Skill methodology

I read a blog post 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’ve seen so far regarding skills.

Skills are actually not complicated, but I think it’s not that easy to do them well.

I remember when skills first became popular, everyone loved creating various stylistic skills and writing skills. It seemed that as long as you embed your writing style, the model could reliably output in that style.

But I later experimented and found that many times, it’s simply not feasible.

Because a stylistic skill might contain just a few thousand or even tens of thousands of words. Once a skill is loaded, it takes up a large portion of the context. When the context is crowded, the model’s reasoning ability tends to decline.

The common outcome is: the style is learned, but the content becomes shallow, and analytical ability weakens.

Another common scenario.

Many people write skills by stuffing in various operational instructions—what to do first, second, third. As a result, when running, the model’s execution becomes unstable.

Later, I gradually understood that many of these repetitive tasks are better suited to be encapsulated as scripts rather than long instructions.

After reading this article from Anthropic, my biggest takeaway is that many people are actually using skills, but may not truly understand what a skill is.

Fundamentally, a skill is about Context Engineering. When should you embed knowledge into a skill? When should you split it into references? When should you write it as a script? When should you use gotchas to constrain the model? There’s a lot of experience involved here.

Once you understand how skills work, looking back at excellent skills, you’ll find they’re never about fixing prompt wording issues, but about solving problems related to context, experience sedimentation, and capability reuse.

If you want to deeply study skills, I highly recommend two articles:

#01 Don’t Waste Words

A skill is essentially about sedimenting the “tacit knowledge” within an organization. So, don’t repeat common knowledge that the model already knows. The truly valuable information is often what the model doesn’t know.

Anthropic often emphasizes that what really needs to be written into a skill are gotchas—common pitfalls.

For example:

1. This table should not be sorted by created_at.

2. Returning 200 from staging does not mean success.

3. request_id and trace_id are the same thing.

Because these details are often based on employees’ experience, it’s crucial to remember what a skill fundamentally is.

Skill = writing down the experience of seasoned experts.

Through skills, we sediment the experience that was previously scattered across different minds.

#02 Skills Are Actually Context Engineering

This might be one of Anthropic’s most profound insights.

A skill is not just a markdown file, but a folder. For those who have used skills, this might sound like nonsense.

But over the past couple of days, I’ve been pondering and gradually realized: they are trying to use the folder structure to express the concept of Context Engineering.

Let’s revisit a typical skill structure:

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

When invoking a skill, the model first reads SKILL.md. If all information is stuffed into this file, the context will quickly explode.

Suppose this is a payment troubleshooting skill, containing Stripe error codes, historical failure cases, troubleshooting scripts, and final report templates.

If all these are piled into SKILL.md, every time the skill is invoked, Claude has to re-read it.

Even if the user just wants to confirm what a certain error code means or check why a payment status hasn’t updated, a lot of irrelevant information will also be included in the context.

Anthropic’s approach is completely different.

SKILL.md acts more like a navigation page. Its role is to tell the model that when encountering a Stripe error, it should look into references for explanations.

When referencing historical cases, check examples; when performing actual troubleshooting, run scripts in the scripts folder; and when generating a report, use templates from assets.

This process is gradually exposed.

I strongly recommend everyone save the diagram below.

#03 Use Scripts as Much as Possible

Don’t let the model waste its limited context and reasoning power on repetitive tasks. Delegate these to scripts.

For example, many people write skills like this:

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

This approach is fine, and the model can handle it. But each time it runs, it has to redo the entire analysis process from scratch.

Querying data, organizing data, handling various edge cases—these are repetitive tasks.

Since these capabilities have been validated countless times, why reinvent the wheel each time? It’s better to provide specific scripts.

Moreover, executing scripts makes the skill more accurate and saves tokens.

From this perspective, scripts in skills are sedimented organizational capabilities. Behind each script are best practices accumulated from past pitfalls.

By solidifying these capabilities, Claude can work based on these experiences instead of starting from zero every time.

So I increasingly believe that instructions and scripts in skills address two different levels of problems.

Instructions provide experience and judgment; scripts provide capabilities and execution.

For example, in a payment troubleshooting skill, you might have a line like:

If Stripe returns 200, don’t assume payment succeeded; further check the payment_events table.

This is an instruction—based on experience. The function check_payment_events() is a script—an execution capability.

If only scripts are provided, the model knows how to check but may not understand why.

If only instructions are provided, the model knows what to check but has to re-implement each time. Both are essential.

#04 Descriptions as Routing Rules

Many people write skill descriptions in a way that’s inherently wrong.

Because they tend to describe what the skill does—e.g., PR Management Skill helps monitor PR status, handle CI issues, and automatically merge.

But the problem is, the model doesn’t find skills based on functions. When Claude Code starts, it scans all skill names and descriptions.

Then, based on the user’s current question, it decides which skill to load.

So, the most important part of the description isn’t what the skill can do, but under what circumstances it should be loaded.

Descriptions essentially serve as routing rules for skills.

In the real world, few people say, “Help me call a PR management tool.” More likely, they say, “Keep an eye on this PR,” or “My CI failed again.”

Therefore, a good description should focus on describing the user’s intent, not listing features.

I even suggest a simple test:

After writing the description, delete the entire skill, leaving only this line. Then ask yourself: after seeing the user’s question, can the model tell when to load this skill?

If not, it probably needs further refinement.

#05 Skill Management and Distribution

Another aspect is skill management.

For an individual, using skills is straightforward—write a few, maintain, upgrade as needed. But I believe most teams will face the same challenge.

When skills grow from a few to dozens or hundreds, how should they be managed? How to upgrade? How to distribute them among team members?

Anthropic’s experience here is quite instructive.

In small teams, skills follow the code repository—placed in a .claude/skills directory within the project. Everyone shares the same skill set and working methods.

But as the number of skills increases, a new problem emerges.

Claude Code, on startup, scans all skill names and descriptions to decide which skill to invoke. The more skills, the higher the routing cost.

This is why Anthropic later started building a marketplace. But even more interesting is how they manage the marketplace.

Many companies respond to this problem by establishing approval workflows: who wrote the skill, submit for approval; after review, it enters the official skill library. We’ve done this internally too, but it’s very bureaucratic—overly so.

Anthropic’s organization is much more lightweight.

New skills are first deployed in a small scope, allowing colleagues to install and test them themselves.

If more people start using a skill, it indicates that it truly solves a real problem. At that point, the author can submit it to the official marketplace.

They don’t first debate whether the skill is valuable; instead, they let it undergo real-world testing. If it’s used widely, it naturally becomes part of the official system. The skills that remain are those genuinely needed by the team.