This analysis examines why i Turned Seven Workflows into Skills, what evidence supports the argument, and where the conclusion still has limits.
Read the evidence below as a decision trail: what changed, why it matters, which trade-offs shaped the result, and where the conclusion still depends on context.
Claude Code's customization mechanism has 5 layers - CLAUDE.md, Skill, Subagent, Hook, and MCP. The most pragmatic starting point is Skill: it is simpler than Hook, more direct than Subagent, and lighter than MCP. I have written 7 Skills, and three judgment criteria have emerged from this process - what should be extracted as Skill, what should be left in CLAUDE.md, and what should be extracted as shared-rules.
After talking about CLAUDE.md in the previous article, I left a hook at the end: "Write CLAUDE.md if it should always be loaded, and write Skill if it should be loaded on demand." This article spreads out this trade-off - why I did not write 7 things into CLAUDE.md and rewritten them as Skills.
Claude Code sounds like it has many customization options - CLAUDE.md, Skill, Subagent, Hook, MCP - but after actually using it, you will find that Skill is the first and most cost-effective option for most people. The reason is simple: it is easier to set up than Hook, more sticky to the main session than Subagent, and does not require external dependencies than MCP. I have accumulated 7 Skills and figured out the criteria for judging whether they should be written as Skills, and I will share them in this article.
The real difference between Skill and CLAUDE.md: always-on vs on-demand
The course describes Skill as a module that "has a name, a permanent description, and the complete content is loaded only when Claude determines that it is needed." The design focus of this mechanism is not on "how complex steps can be written", but on the fundamental difference between it and CLAUDE.md — always-on vs on-demand。
CLAUDE.md is always-on: every time the session starts, it is appended to the prompt. No matter what you want to do this time, it will be eaten into the context first. Skill is different: name and description are permanent (let Claude know that this tool exists), but full content is only fully expanded when Claude determines that it is needed.
From a context budget perspective, this is the difference in "tax rates". Writing it into CLAUDE.md means paying the context tax once per session; writing it as Skill only pays it in the triggered session. If a certain specification only appears once a month in a certain type of task, putting it in CLAUDE.md will make hundreds of other sessions silently pay this tax, but it will be completely useless.
Another angle: CLAUDE.md is suitable for "Things you should know no matter what you do》 — Project stack, commit specifications, and security rules that cannot be violated. Skill is suitable for "Things that should only be known in certain situations" — SOP for certain types of tasks, format specifications for certain files, and troubleshooting procedures for certain errors. The former is the constitution and the latter is the manual.
Which 7 Skills did I write: distributed in 3 projects
I currently have 7 Skills, distributed in 3 main projects:
knowledge-vault：vault-agent
vault-agent It is a Skill dedicated to the personal knowledge base. The user can issue commands. ingest <Tags> or query <Keywords> Trigger, do vault material precipitation and query. Why is Skill and not CLAUDE.md: The vault operation process is very complicated (proposal system, multi-level division of labor, edge case), and resident will dilute the entire CLAUDE.md, and most of my sessions are not ingest - loading on demand is more reasonable.
outsidewriter: 3 writing-related skills
- writing-style: Load every time you rewrite an article to ensure consistent style.
- fact-check: The verification process that is mandatory after the transcription is completed.
- output-formats: Format specifications for four output formats (WP/FB/Threads/LinkedIn), which are loaded during the output stage.
What these three have in common is that they are all used in the task type of "writing articles". If written into CLAUDE.md, context tax will be paid for every conversation with outsidewriter (including debugging, planning, and discussion), but 90% of conversations do not use these specifications.
gwarket-site: 3 technology-related Skills
- code-conventions: Technical conventions to consider when modifying or creating code.
- deployment-troubleshooting: Troubleshooting guide for issues such as abnormal front-end display, incorrect API, and routing failure after deployment.
- ui-design: Used when making interface design decisions, creating new components, and discussing visual style.
The judgment logic of these three is the same - it is a waste to store details that are only needed for a specific task type in CLAUDE.md. The seven Skills together cover the customized needs of three main projects. The next paragraph lays out the judgment criteria precipitated in this process.
Three Judgment Criteria: What should be drawn as Skill
Guideline 1: Things that are needed by multiple projects are not included in the CLAUDE.md of a single project.
The first signal isRepeat. If the same specification is needed by both insidewriter and outsidewriter, or by gwarket-site and publish-tools, it will split sooner or later if it is placed in two places.
I have tried it myself: the writing style specification was originally placed in SKILL for outsidewriters, but later it was also used by insidewriters. The first instinct is to make a copy of the past - but copying means that the next time you change the specification, you have to change it twice, and if you miss one change, you will split. Last drawn shared-rules/ In this independent layer, writing-style.md, fb-writing.md, threads-writing.md, and reading-protocol.md are all there. CLAUDE.md and SKILL of each project are only references and do not overlap.
NOTE: Something that is required by multiple projectsIt does not have to be written as Skill — It may be a pure markdown specification file in shared-rules. Skill is one form of encapsulation, shared-rules is another. Guideline 1 deals with "should not be tied to a single CLAUDE.md", not "must be written as Skill".
Principle 2: Specifications that only appear in specific task types, do not put permanent memory that is read every time
The second signal isTask frequency is not equal. The content of fb-writing.md only appears in the task "Write FB Posts". Put it into outsidewriter's CLAUDE.md, and pay a context tax for each session (including topic selection, transcription, review, publishing, and debugging), but it is only used in the publishing phase.
The opposite is also true:Things you should always know should not be written as Skill. The "four iron rules of publishing" of publish-tools (no new category tags, default drafts, passwords read from.env, safe word confirm) are always-on - no session can be violated. Writing it as Skill is risky (what if Claude doesn't load it automatically?). This one stays at CLAUDE.md.
Principle 3: The more detailed the specification, the more independent skills should be drawn.
The third signal isword count pressure. Skills have no word limit - they can include complete processes, specific cases, and edge case processing. Writing these details into CLAUDE.md would dilute the entire file and drown out the important rules.
deployment-troubleshooting is the best example. It is written in 15KB and covers various types of Cloudflare Worker / Pages routing failure, troubleshooting steps for WordPress headless API exceptions, and common errors in DNS settings. These details are useful, but they are only used in those few moments when the package is deployed. Writing into CLAUDE.md is equivalent to paying the 15KB tax for each session. It is a more cost-effective design to write it as Skill and load it completely when needed.
Taken together, the three principles are essentially the optimization of the context budget - put the right things at the right level, keep only the necessary ones in the always-on layer, and leave the optional things to on-demand.
Pitfall case: Skills are not useful just because they are written
My most representative pitfall is "Even the person who wrote it will misremember which file the specification is in.」。
In 2026, when I was writing a FB post-related task, I gave Claude Code an instruction saying "Please refer to the FB specifications in outsidewriter/CLAUDE.md." When Claude Code is executed, the file is actually read and the FB specification is found.Not here outsidewriter/CLAUDE.md, but in outsidewriter/.claude/skills/output-formats/SKILL.md. It stopped and asked three true-false questions and waited for my confirmation before continuing.
This case was later classified in my vault as a sub-pattern of "summary distortion" - "source pointer missing". The problem is not the wrong content, but the "wrong pointing": the vault wrote the content description of the FB specification, but did not clearly indicate which file the source is in; after a while, my memory misplaced it and I thought it was in CLAUDE.md.
This pitfall brings out a discipline:After major changes to SKILL.md, first run dry-run with "Main Agent Acting" and then load it officially.. The reason is: when "playing" is executed, the main agent will read the specification as a "description" and will stop questioning when encountering ambiguities; after loading, the execution of SKILL is closer to "command-style", and the main agent tends to run along the process without questioning. Dry-run is equivalent to "standard review", and official launch is equivalent to "standard being used" - the two have different abilities to detect defects.
Writing Skill has higher benefits than writing CLAUDE.mdSilent distortion risk, because its contents are not viewed every time. CLAUDE.md will be read at the beginning of each session; Skill is only used when triggered. When it is not triggered, the specification becomes old and out of touch with the actual situation. You will not notice it immediately. Dry-run discipline is the engineering layer of defense against this risk.
My point of view: Skill is cost-effective, but the boundaries must be honestly marked
Skill is the most cost-effective starting point for Claude Code customization. It is easier than Hook (no need to touch settings.json), more direct than Subagent (shares the main session context, and can see the conversation context), and is lighter than MCP (no external server is required). The problem it solves is "conditional loading specification", which is a problem that most users will encounter.
But this article has a boundary that I must honestly mark—I haven't actually used Hook, Subagent, or MCP yet.。
When writing vault-agent, I evaluated Subagent and finally chose SKILL. The reason is that the ingest process of vault needs to capture content from the current conversation context, and Subagent cannot see the main conversation and SKILL capabilities. This can be regarded as a decision-making record of "selecting SKILL after evaluation". but iNever used Subagent before, so it is impossible to write a trap layer of "I used it and then cut it off".
I haven’t taken over any server in MCP. Even publish-tools directly uses the WordPress REST API. Hook None of my settings.json has a hooks section. For scenarios that require "post-execution inspection" (such as Auto-Lint in the vault), I use prompt rules to write them into CLAUDE.md for processing.
I deliberately did not write these three in this article. The reason is simple: judgments without empirical evidence have no weight. Writing "Should I go to MCP?" and I have never used MCP, it is just a listicle, not a judgment. I won’t write until I really need to deal with it, step into pitfalls, and have choices to make.
This is also my overall philosophy on Claude Code customization:If it can be solved with CLAUDE.md, there is no need to use Skill; if it can be solved with Skill, there is no need to use Hook; if it can be solved with prompt rules, there is no need to use MCP. Each additional layer of mechanism is an engineering cost, and it depends on whether you need that level of stability and automation.
Practical questions and boundaries
What is the difference between Skill and prompt template?
Prompt template is a block of text that you paste into a conversation every time. It is up to you to remember to use it and paste it in the right place. Skill is a module that Claude automatically determines whether it should be loaded after seeing the dialogue content - you do not need to manually trigger it. The difference is "passive vs active": Claude only uses the template when you give the command, and Claude determines the situation and then pulls the Skill. Skills can also contain scripts and structured frontmatter (name, description, trigger conditions), and prompt templates are usually just plain text.
How many skills are too many?
There is no absolute number, but the signal is very specific: when you can’t remember which file a certain specification is in and have to open a folder to search, it means there are too many Skills or they are too fragmented. I have stepped on this trap - I thought that the vault had written the specifications, but I ended up misremembering the location a few months later. The more skills you have, the more discipline you need: an index file to record the trigger conditions of each skill, dry-run SKILL.md for major changes, and regularly check whether the trigger description still matches the actual situation. There is a real risk that too many skills will interfere with each other, but there is no need to set an upper limit before management discipline is in place.
This is Part 3 of the Claude Code 101 series (series finale):
- Article 1:Claude Code is not a stronger completion - it runs an Agent loop that verifies itself
- Article 2:Context is the scarce resource of Claude Code
- Article 3: Why I wrote these 7 things as Skills - a PM’s customized judgment (this article)
The three articles strung together actually form the same narrative: Claude Code is not about learning a tool, but about learning a collaboration model. The first article talks about the essential difference between Agent and completion, the second article talks about how to manage the scarce resource context of collaboration, and the third article talks about how to layer customization. People who know how to use it do not necessarily memorize more instructions, but know better how to configure the long-term memory around the Agent - CLAUDE.md is the constitution, Skill is the manual, and shared-rules is the cross-project consensus. Each layer should be collected cleanly and placed in the right position.
Some of the concepts in this article are based on the Anthropic open course Claude Code 101 (https://anthropic.skilljar.com/claude-code-101). The content of the article is the author's own study notes and observations, not a translation or paraphrase of the course.
What to take away
The useful decision is not to accept the headline at face value, but to test whether the evidence supports i Turned Seven Workflows into Skills in the reader's own context.