The playbook pattern
I have recently refactored my Claude Code skills to use what I call the playbook pattern.
The problems
At its core the playbook pattern helps to solve two problems with agentic skills:
- Context bloat
- Duplication
Context bloat
When your coding agent session starts up, it preloads some initial context into its model's context window. This includes some metadata telling it when to load some skill.
You can see the state of your context window in Claude Code by running the following:
/contextIn Claude Code the skills are defined as markdown files with front matter. Claude Code uses the description field to extract triggers to know when to load the whole skill. A typical skill will look something like this:
---
name: foo
description: Foo does bar. Load it when baz.
---
Do the following ...If you have a lot of skills, your context window can be significantly filled up, making it not as effective.
You can get around this by setting disable-model-invocation: true in the front matter. This will stop Claude preloading the context window with triggers for this skill. However, this will also stop Claude being able to directly invoke it itself - you (the human driving the session) would need to explicitly invoke it by typing /foo.
Duplication
The other problem with skills is duplication.
When adding skills, sometimes you want to be able to share context around something that you don't want to expose as a skill in its own right.
For example, you might want several skills to be able to drive a particular command-line tool but don't want to create a separate skill for that tool. The only way to currently get around this is by duplicating the content.
Wouldn't it be nice to have some way to DRY up your skills, by being able to privately share resources without publicly exposing them?
The solution
The solution I have landed on is to have a centralised monolithic playbook skill. The skill acts as a router to plays - each one taking the place of a skill. You can think of a play as being a sub-skill.
You can invoke a play in the following manner:
/playbook play-name arguments...Helper skills for discoverability
Surrounding the playbook skill are what I call helper skills. All of these skills have disable-model-invocation: true - their only job is:
- To delegate to a corresponding play - so
/foo arguments...delegates to/playbook foo arguments.... - To provide a discoverability mechanism - so you can take advantage of the autocomplete in your Claude Code chats.
DRYing things up with private plays
We can DRY up our plays by using private plays whose name starts with a _. These plays have no corresponding skill and are only to be shared between plays.
When to use it
I would only use this pattern if you have a significant number of skills. At the time of the refactor my skills plugin had 42 skills.
So far this pattern has been working well. So, if your skills are piling up - give it a go.