Note: Claude is the LLM (AI model) that enables Claude Code to generate code/text and use tools.
In the first post of this journal I talked about how skills can be used to make Claude “function” in a certain way in Claude Code (CC from here on), and lesson 5 there was that skills should be built based on a workflow. Here I want to go a little bit deeper into the topic, because it really makes a huge difference working with and without skills.
Context context context!
Imagine you, as a fresh graduate, have just started in a Fortune 500 company (like this is your first day) and your first task is to evaluate and report the usage of software X in the department for the past year and whether it makes sense to continue using it. Now, without any context, I would say an approach would be to go to the software admins, get the usage logs, put them into charts, identify trends, and make a recommendation on whether it is worth continuing to use it. Sounds easy, right?
But… Are there actually logs from software X? Can the admin give the logs to you (data security)? Are you allowed to use them (data confidentiality)? What are the indicators that you used for your final recommendation? And the list of questions goes on and on. Why? Because, as mentioned, you lack context! You don’t know how software X operates. You don’t know how the company processes work. You don’t know what the procurement metrics for the company are.
Now going back to CC, we can see the exact same issue happening. Every new session in CC starts with a fresh new context (for now we ignore memories and CLAUDE.md files). It knows how to tackle a task, but it has no idea: [1] “how to do it your way” and [2] “what is your definition of done”. If we compare it with the example above, Claude is that highly trained newbie starting work at the big company. Sure, it knows how to “tackle the task itself”, but it doesn’t know how to “tackle the task in the company” ([1] & [2]). The former requires expertise and the latter requires context.
And this is where skills come into play. They provide the missing context to allow Claude to know how to do things “your way”. Essentially, skills are part of context engineering, where we try to present Claude with the correct pieces of information, in the correct order, in the optimal granularity, so that it can tackle a task in a way that satisfies both [1] and [2].
Context in a plain text file
If we go check the official specifications for skills, we can see that a skill is nothing more than a predefined prompt. Like, it is literally just a plain text file written in markdown format! Inside this file we can write anything that we want to provide as context to Claude. For example, instructions on how to do things (in the example above this would be the steps to follow to get logs from the admin), examples of what a good output is vs a bad one, good to knows, things to avoid and so on. It is more or less like a workshop transcript on how to use X.
And before you start shouting: but a skill can contain scripts, references and other files! Yes, it “can” contain them, but ultimately only the SKILL.md file is mandatory and the rest are optional. If you look at how CC uses a skill, you can see that all the text files (with the exception of executables like scripts) are read alongside the skill, meaning that we could put everything into 1 single SKILL.md file and the result would still be the same. So a skill is essentially just a text file that CC reads and gives to Claude, a.k.a. a predefined prompt. Ok, saying that it is the same as a predefined prompt is an oversimplification. There is another crucial component to skills, which is that Claude can use them by itself without the user explicitly telling it to do so.
Just in time context
I think the main contribution of skills is the model invocation mechanism. The way it works is that during CC session startup, the description field in the frontmatter of SKILL.md gets loaded into the session, and during the session, Claude decides based on the description whether or not to use that skill. This is beneficial in 3 ways. Firstly, the token cost. The description field is essentially a short summary of what the skill is and when to use it. This avoids the whole skill file being loaded at session startup, which costs tokens if it goes unused. So loading only a short summary is a small price to pay in comparison. Secondly, the automation. Because Claude can decide when to use the skill, the user does not need to do so manually, which is a benefit, since who can remember the exact names of 100 skills? Having said that, CC has the option for the user to use a skill manually, just in case.
Thirdly, the just in time context. Since the full skill file is only loaded when Claude decides that it needs it to perform a task, Claude always has the content of the skill in its most recent context. This helps reduce hallucination and improves instruction following. Had CC just loaded the skill file at the very beginning, and the session had already filled up the context window, the skill would be “forgotten” or “blurred”, because CC would need to either compact the context or drop parts of it.
Fun fact: in CC, once a skill file is loaded, it will not be loaded again, even though Claude might think that a current task requires that skill again. This means that the third benefit is only true for the first usage of the skill in a session, because afterwards it has the same issue as “loading it all at session start”. I guess the CC devs don’t see this as an issue, since most sessions are short anyway.
Letting Claude decide when to use a skill sounds incredible in theory, but in reality there are indeed some downsides to it that, in hindsight, should be pretty obvious. The first is the “trust me bro” factor. Since Claude decides when to use the skill, we are at the mercy of Claude’s judgement. We could use scripts or hooks to “enforce” certain skill usage, but that is not always possible, for example when judgement is needed to determine which skill to use based on the user request.
You are probably thinking now: can we not just run evaluations on the triggering of the skill and improve the skill description (which can be done using the skill-creator skill in CC and also the plugin eval command)? Yes, and that is probably what most people are doing. But at the same time no, because there is no way to cover every single possible way of using a skill. Also, Claude models change so frequently that if you go the evaluation approach, you will need to do it for every new model release, since no 2 models behave the same way. This is in my opinion an open question, and I wonder: do we solve the evaluation issues first, or will skills go out of style first?
Build workflow based skills
So how do you write skills? A big mistake that I made when I first started working with skills was to write a gazillion skills. What I mean here is that I wrote a lot of skills for different topics, for example a skill for every single git command or a skill for every Python development topic. After the refactors, rewrites and migration I mentioned in the last post, I realized that “less is more” = fewer skills allow you to use them more. If you have a lot of skills, you will just forget that you even had them, meaning that a lot of them will just end up not being used. And as I said in the last post, a lot of best practices are, in my opinion, already trained into the model, so skills are not needed there. This is more or less the same conclusion that others have arrived at, where the advice is to cut down on the number of skills and only use those that are essential.
So if quantity is not the way to go, then what is? I believe, based on experience, the answer is based on workflow. Why workflow? Simple, because in a workflow, you know what you need to do. And when you know what you need to do, you can easily associate the skill needed with what you need to do (that’s a lot of needs!). And again, because you know what you need to do, you can build the skill based on a step in that workflow.
A few example projects that helped me shape my opinion: superpowers, mattpocock/skills, pstack, and gstack. All of them created skills around the software engineering process (a.k.a. a workflow), where each step of the process (spec, plan, build, review, test) is tackled by a skill (this is highly simplified, but I think if you go through them you will kinda agree with me). By “owning” a step of the process, each skill has a clear purpose, which is crucial to avoid confusing Claude.
A library of skills for the product development lifecycle
Following up on the previous section, I want to talk briefly about the skill library (a Claude Code marketplace) that I am building: ceh-claude-code-library. Why did I do it? The example projects that I just mentioned focus on building software, which, to be frank, is what tools like CC are built for. But I want to take it a step further and see if it can be used for the entire product development lifecycle, from the initial business planning to the development to the marketing of a product (which may or may not be a piece of software). This is what the library contains: a collection of skills to assist Claude in CC through the entire product development lifecycle. For now, I am still experimenting with the entire library.
In the library, I split my skills based on “moments”. A moment is the action(s) that you are taking in a step within a workflow, or in this case within the lifecycle. For example, writing a plan is one moment and reviewing that plan is another, and each has its own skill. By building skills that focus on the actions, we can then have a “standardized” way of writing skills. My skills are thus a collection of actions (what to do) for Claude. This made the creation and writing of skills a lot smoother and easier than before. And to keep track of things and for traceability, I made sure that all the skills output an artifact that acts as a form of report from that skill. The artifact is tracked, and anything that changed needs to be recorded there. Of course this is only where applicable, because a skill that involves a git operation doesn’t need a report, the git history is the report!
The closest project to my idea would be gstack, which contains skills covering the different roles of a traditional software company. In my opinion, separating skills by roles may not be the best approach. Why? Because when you build a product, will you stop and think who is responsible for xyz at every stage of the product development lifecycle? In a real world setting, yes, because everyone has a predefined role within a company, with certain expertise and certain resource allocation. But Claude, or agents in general, are “the” expert and consume only 1 resource: tokens. So instead of splitting by role, I split mine by moments, as mentioned above. Nevertheless, reading the different skill library projects really gave me a lot of inspiration, and it is definitely very cool to see that there are people out there who share your view on how to “maximize” the potential of agent skills =D