Complete Guide to Teaching AI Your Workflow with Claude Code Skills

"I'm worried if I can use AI because I have zero programming knowledge..."

"I'm scared of looking at the black terminal screen and don't feel like it."

"But I'm anxious about being left behind by the AI trend 😱"

Even in that state, by letting Claude Code learn my "own action patterns," a task that used to take 30 minutes every time now takes 5 minutes.

In fact, the opportunity is coming precisely for non-engineers.

The key is Skills.

In Pokémon terms, it's a "Technical Machine" (TM).

When using Claude Code, have you ever felt like this?

• It's certainly smart. But every time, I have to set up the format, judgment criteria, and background information myself.
• Even though it's AI, there's a lot of manual work. "Isn't this the same as doing it all myself?"
• Are other people using it more effectively?
• I'm using it, but not mastering it. I don't know what the difference is.

By the time you finish reading this article, you will be able to create an environment where you just set your workflow in the AI once, and the same quality output comes out every time.

Santiago (@santtiagom_), an engineer at MercadoLibre, the largest EC company in South America, published a complete guide to Skills in Spanish that is currently going viral with over 580,000 views.

He says he created over 50 Skills himself and deleted most of them in two days. This guide is based on his real-life experience of what remained and completely changed how he works with Claude.

I have two requests before we start.

1. Save this article and secure 20 minutes this week.
2. If you know anyone using Claude Code, please share it with them.

This time, I will explain the content in an easy-to-understand way.

Here is the original post.

https://x.com/santtiagom_/status/2030305647535751338

Why Claude Needs Setup Every Time

First, let me talk about the major premise.

Claude Code is very smart. However, it doesn't know "your way of working."

This is not a performance issue, but a matter of how it works.

Claude starts from a blank slate every time you open a new session. Unless you tell it every time, Claude doesn't know what format you prefer, what kind of report your boss wants, or what tone you use in emails to customers. These are "your unique judgment criteria."

This mechanism causes three problems.

Problem 1: Lack of Consistency

Even with the same request to "create a weekly report," today it might be a 2,000-character detailed version, and tomorrow it might be three bullet points. Since your desired format isn't set, Claude has to decide on its own every time.

Problem 2: Your Unique Judgment Criteria are Missing

Claude is excellent in general. But it doesn't know rules that only apply in your environment, like "in your company, you must start with the conclusion" or "your boss doesn't read documents longer than 3 pages."

So every time, you need to set up that background from scratch.

Problem 3: The Effort of Setup Adds Up

Typing out format specifications, explaining judgment criteria, and sharing background information.

How much time do you spend on this "setup" in a day? Even though you're using AI, you get tired just from the preparation.

santtiagom_ writes:

"What if you could write an instruction once and have it done perfectly from then on without giving instructions again? That's what Skills are."

Skills is a mechanism where you write your workflow in a single file and set it in Claude. Once set, Claude will act according to it from the next time without you saying anything.

From here on, I will explain the overall picture of Skills in order.

Skills are Claude's "Technical Machines"

Have you ever used a "Technical Machine" (TM) in Pokémon?

Just by loading one disk, that Pokémon learns a new move. Once learned, the move can be used as many times as you want in every battle. Forever, unless you make it forget.

Skills are exactly like these "Technical Machines."

You create one file called SKILL.md and set it in Claude.

Then, Claude will act according to those instructions every time it opens a session. You no longer need to set things up every time.

To organize the correspondence simply:

• One TM → One SKILL.md file
• A Pokémon that learned a move uses it in every battle → Claude with a Skill set applies it in every session
• Replaceable (can relearn) → Skills can also be added/deleted/replaced freely
• Compatibility exists (some moves can't be learned) → Some Skills don't fit the project

The important thing is that your work also has "tasks that can be turned into TMs."

For example, when making a report:

"Write the conclusion first. Use no more than 3 data points. Use a format that the boss can judge in 5 seconds."

If you set this as a Skill, Claude will automatically follow this rule from the next time.

When making a weekly report:

"Three parts: Last week's results → This week's plans → Issues.

Write numbers as a week-over-week comparison." You can also set this as a Skill.

When writing an email to a customer:

"Express gratitude at the beginning. Keep the main point within 3 lines. Clearly state only one next action." This too.

Let's compare a world with Skills and a world without them.

[Without Skills]

You ask to "create a weekly report" → Claude outputs in its own format → You correct it: "No, conclusion first," "Limit data to 3 points" → Next week, you start from scratch typing everything again.

[With Skills]

You ask to "create a weekly report" → Claude outputs according to the Skills → From the start, it's in the "Conclusion → 3 Data Points → Issues" format → Corrections are almost zero.

santtiagom_ repeatedly emphasizes this way of thinking in his article:

"A 5-line working Skill is more valuable than a perfect Skill with 80 rules."

You don't need to create perfect instructions. Even just two lines like "Write from the conclusion. Up to 3 data points" will be effective if set as a Skill.

And this is the part I personally want to convey the most.

The essence of Skills is not "automation of work."

It is the "act of verbalizing your judgment criteria and setting them in the AI."

"Write from the conclusion," "Limit data to 3 points." These are not work procedures, but your judgment criteria. Which information to prioritize, in what order to convey it, and how detailed to write.

You leave those judgments in a file. Just as a move learned from a TM becomes a Pokémon's strength, verbalized judgment criteria become Claude's strength.

Assetization of judgment. If I were to describe Skills in one word, this is it.

All You Need is One File: SKILL.md

The mechanism of Skills is much simpler than you might think.

All you need is one file called SKILL.md.

The content of this file is divided into two parts.

Part 1: The "Cover" with Name and Description

At the top of the file, you write the name of the Skill and a description of "when it should be used."

Claude looks at this "cover" and judges "whether it should use this Skill for the current task." If this is ambiguous, Claude won't find the Skill you worked hard to create.

For example, with just the name "Report Creation," Claude will wonder "Which report? When do I use it?"

If you write "Create a weekly sales report for Manager Tanaka. Structure: Conclusion → Numbers → Issues," Claude will automatically select this Skill the moment a request for a weekly report comes in.

In TM terms, this cover corresponds to the judgment of "which Pokémon can learn this move."

Part 2: The "Body" with Specific Instructions

This is your actual way of working.

You write specific procedures and rules like "Write in this order," "Follow this format," and "Be sure to check only this point."

Skills work with just these two parts.

It's faster to look at an actual file, so here's an example. It assumes a situation where a sales team submits a weekly report to their boss every week.

1---
2name: Weekly Sales Report
3description: Use when creating the weekly report for the sales team every Monday. For Manager Tanaka.
4---
5
6# Weekly Sales Report
7
8## Format
9- Write the conclusion (expected landing for this week) on the first page
10- Always include numbers as a week-over-week comparison (e.g., +12% vs last week)
11- Classify deals into three levels: A/B/C
12- Limit issues to one, and add a one-line specific action for next week
13
14## Manager Tanaka's Rules
15- He doesn't read more than 3 pages. Keep it within 2 pages
16- He prefers tables over graphs
17- Don't write "under consideration." Always convert it to "what will be done by when"

This is the overall picture of SKILL.md.

Looking at the description on the "cover" saying "every Monday... for Manager Tanaka," Claude automatically judges, "Oh, this is about the weekly report."

Then, following the instructions in the "body," it creates a report of 2 pages or less starting with the conclusion in the same format every time.

Rules like "Manager Tanaka's Rules," which only apply in your workplace, are the true value of Skills. No matter how smart Claude is, it won't know Manager Tanaka's preferences unless you teach it.

There are two ways to activate it.

The first is to call it directly yourself, like "/report-creation." Use this when you want to ensure it activates.

The second is for Claude to read the cover description and automatically judge that "this should be used now." If the description is well-written, it will activate on its own without you giving any instructions.

If it becomes a larger Skill, you can add auxiliary folders for reference materials and templates, but one SKILL.md is enough at first.

Claude Won't Slow Down Even with 50 Skills

"If I put in a lot of Skills, won't Claude's movement slow down?"

I think this is a question everyone has at first.

The answer is: it won't slow down.

Claude doesn't load all Skills at once; it's designed to load only what's necessary in stages.

In TM terms, a Pokémon isn't thinking about all its moves all the time. It chooses the move to use based on the battle situation. Claude is the same.

Level 1: First, glance at the names

It first lightly checks only the "name and description" of all Skills. It hasn't read the file contents yet.

Level 2: Read the full text of only what's necessary

If it finds a Skill that seems related to the current request, it reads the full text of only that Skill. it doesn't touch the rest.

Level 3: Read additional related materials if necessary

If the Skill specifies "please also read this reference material," it reads that file as well.

In other words, even if there are 50 Skills, only the "1 or 2 related to the current job" are actually loaded. It has almost no impact on performance.

However, there is one thing to watch out for.

If the "description" on the cover is sloppy, Claude won't be able to find the necessary Skill.

At Level 1, it might be misjudged as "this doesn't seem related this time" and skipped.

That's why I said the cover description is the most important. It's vital to clearly write "when and for what kind of task this Skill should be used."

As a practical guide, there's no problem at all as long as the total of all Skill names and descriptions is within 15,000 characters. You're unlikely to ever reach this limit with normal use.

Your First Skill is Completed in 6 Steps

Now for the practical part.

I'll break down the "6 steps to create your first Skill" introduced by santtiagom_.

However, first identify the timing to create a Skill. If even one of the following three conditions applies, it's time for a Skill:

• There is background information you are typing manually (format, rules, tone, etc.)
• There is a task you want produced with the same quality every time
• There is a step you always forget

Conversely, Skills are not suitable for one-off tasks or jobs where the conditions are completely different every time.

Let's look at the 6 steps in order.

1️⃣ The seeds of Skills are in repetition

"If you've typed the same background information 3 or more times, it's a candidate for a Skill."

santtiagom_ asserts this.

Meeting minute formats, report structure rules, email tones. If there's background info you type every time, that's a sign it should be set in a Skill.

Starting today for one week, try taking notes on what you type manually into Claude. You'll find things you repeat 3 or more times.

2️⃣ Ready with one folder and one file

Create a folder called .claude/skills/ within your Claude Code project, create a folder with the Skill's name inside it, and place the SKILL.md file there.

1.claude/skills/
2  └── weekly-report/
3        └── SKILL.md

That's all you need to get ready.

3️⃣ 5 lines are enough at first

Remember santtiagom_'s words: "A 5-line working Skill is more valuable than a perfect Skill with 80 rules."

Don't aim for perfection from the start.

Even for the weekly report example earlier, this is enough at first:

1---
2name: Weekly Sales Report
3description: Use when creating the weekly report for the sales team every Monday
4---
5
6Write the conclusion first. Numbers are week-over-week. Limit issues to one. Within 2 pages.

Done. The body is just one line.

How about it? If it's just this much, you could do it starting today, right?

As you use it, if you notice "Manager Tanaka likes tables better than graphs" or "If I write 'under consideration,' it gets sent back," you can just add those each time.

The finished version from earlier is the result of growing it like this.

4️⃣ Effect is clear with comparison tests

Try the same request both with the Skill turned on and with it turned off.

If there's a clear difference in the output, it's proof the Skill is working.

If there's no difference, the Skill content might only contain things "Claude already knows." Try adding judgment criteria that only you would know.

5️⃣ Skills grow every time they fail

If you feel "this part is still wrong" after testing, add that to SKILL.md each time.

To borrow santtiagom_'s words, "If you've made the same correction 3 times, add it to the Skill."

A perfect Skill isn't something you make from the start; it's something you grow as you use it. This process of "learning from failure and growing" is the act of making your judgment criteria more and more precise.

6️⃣ Claude itself will give improvement suggestions

This is the interesting part.

Using the skill-creator Skill provided officially by Anthropic, Claude itself will suggest things like "How about doing this to make this Skill even better?"

Once you set your workflow in the AI, the AI then comes back with "It would be more efficient to do it this way." This cycle is the fun and strength of Skills.

3 Red Flags for Growing Useful Skills

Once you've made a Skill, you need to check if it's working properly.

santtiagom_ lists only one judgment method.

If you run the same task 3 times and get different results every time, that Skill needs improvement.

Specifically, watch out for these three red flags:

Red Flag 1: Instructions are ignored

This happens when the Skill's wording is ambiguous.

For example, even if you specify "write clearly," the criteria for "clear" are unclear to Claude. In this case, Claude has no choice but to write based on its own judgment.

"Write the conclusion first. Keep one sentence within 40 characters. Don't use technical terms."

If you write specifically to this extent, Claude won't hesitate. The trick is to write with numbers and specific rules rather than ambiguous adjectives.

Red Flag 2: Skill doesn't activate

This is a case where there's a problem with the "cover" description.

Remember the staged loading talk from earlier. Claude judges by looking only at the "name and description" at Level 1. If the description here is ambiguous, it will be skipped as "doesn't seem related this time."

Check if the description makes it clear at a glance "when and for what task it should be used."

Red Flag 3: Output is generic, no difference with/without Skill

This is a state where the content written in the Skill is only things "Claude already knows."

Claude is smart, so it can judge general things on its own without being taught. The correct way is to write judgment criteria that only you know in the Skills.

"The boss reads from the conclusion," "He skips data if it exceeds 3 points," "He gets angry if it's not written as a week-over-week comparison." These rules, necessary precisely because of your environment, determine the value of a Skill.

From santtiagom_'s best practices, I've selected 4 particularly important points to introduce.

① Claude is smart. No need to teach it what it knows.

General instructions like "output in JSON format" are unnecessary. Claude already knows. Please teach it the judgment criteria of your work, like "why you do it that way" and "in what order you do it."

② Split if it exceeds 500 lines

He says 500 lines, but in actual operation, around 100 lines for skill.md itself is good. If the volume increases too much, the quality of Claude Code's judgment will drop.

So, if a Skill gets too big, store reference materials in a separate folder. The trick to long-term use is to keep the SKILL.md body focused only on the core instructions.

③ Test with actual cases, not ideals

Testing with a fictional request is meaningless. Try it with a job you actually do on Monday using Skills. It's in real work that you'll see the missing instructions.

④ Grow it as you use it rather than aiming for perfection

If you make the same correction 3 times, add it to SKILL.md. This repetition is the shortest route to growing a Skill dedicated to you.

For Those Who Want to Use It More Deeply

This is the advanced section.

Not everyone needs to do this right away, but I'll introduce it for those who want to "utilize it further."

1️⃣ There are official Skills you can use immediately

Anthropic, the developer of Claude, has officially released 5 types of Skills.

Word file processing, Excel file analysis, PDF reading, PowerPoint generation, and front-end design. You can use them immediately just by installing them from GitHub.

There is also a site called skills.sh that collects Skills made by the community. However, since these are made by third parties, I recommend checking the contents before using them. There's a possibility risky things are included, so pay close attention there.

2️⃣ There are two storage locations: for yourself and for the team

Skills have two storage locations.

For yourself only:

If you place it in .claude/skills/ in your home folder, it becomes a Skill dedicated to you that can be used regardless of which project you open.

For team sharing:

If you place it in .claude/skills/ within a project, it's included in version control, so everyone on the team can use the same Skill.

Personally, I think this team sharing is the hidden essence of Skills.

The fact that your judgment criteria become a file means that even if someone on the team changes, the quality of work is maintained. Judgment criteria no longer depend on individuals. This is a fairly large change for an organization.

3️⃣ Skills also connect with external services

By combining Skills with MCP, a mechanism for connecting to external tools, Claude becomes able to interact directly with external services.

santtiagom_ describes this as "becoming able to delegate processes instead of instructions."

However, this is an advanced usage for engineers. I recommend starting from the basic 6 steps introduced in the previous section.

Summary

I'll summarize the points of this article into 6 items. Please save it so you can look back at it.

• Skills are "files for setting workflows in AI." Like a Pokémon TM, once set, it activates every time.
• Claude is smart but doesn't know "your way of working." Without Skills, you have to set everything up yourself every time.
• All you need is one file: SKILL.md. The content is just "Name + Description + Instructions."
• It's okay to put in 50. Claude selects and loads only the necessary Skills.
• Starting small and growing is the right way. A 5-line working Skill beats a perfect Skill with 80 rules.
• The essence of Skills is not automation of work but "assetization of judgment." The act of verbalizing your judgment criteria and setting them in the AI.

To those who found this article even slightly helpful.

The University of Tokyo Claude Code Laboratory (@ClaudeCode_UT) is an account that posts daily, centered on members who are hardcore Claude Code enthusiasts and current UTokyo students.

We deliver "genuinely useful" information and know-how specialized for practical business every day.

By following, you can get information like this 👇

• Practical guides for "techniques to make AI learn work" such as Skills and CLAUDE.md
• Explanations of the latest AI utilization topics from overseas for non-engineers
• This is the only place where you can receive "genuinely useful" Claude Code skills for free

If you're interested, please follow and check it out! 👀

Also, we've started an official LINE, so if you want to get limited information quickly, please join! Let's accelerate our learning and overcome the AI agent era together! ❗️

https://lin.ee/quYxNMc