Skills contain assumptions about how you work. That is what makes them useful, but it is also what makes them hard to share.
I keep thinking about the difference between personal skills and skills for command-line tools. At first that sounds like a clean split. A personal skill describes how I work. A command-line skill describes how a tool works.
But even that is too simple. A skill is never neutral. Even a tool skill quietly contains assumptions.
Too much context can make a skill worse
Take a skill for bkt, a Bitbucket command-line tool. You could
make a big skill that describes all the commands for Bitbucket Cloud and
Bitbucket Data Center. That sounds complete. It also sounds useful in the
way documentation usually wants to be useful: cover everything, mention every
option, leave nothing out.
But if I only use Bitbucket Cloud, then the Data Center commands are not useful context. They are noise. Worse, they give the agent extra paths to choose from. Agents are very good at confidently walking into the wrong hallway.
So the useful skill is not really “how to use Bitbucket.” It is more like:
“how we use bkt for Bitbucket Cloud in this environment.”
Personal skills have the same problem, only more so
With personal skills, this problem becomes even bigger. A personal skill may contain file paths, scripts, preferred tools, private conventions, publishing habits, or boundaries around what the agent should and should not do.
That is exactly why the skill is useful. It lets the agent start closer to how I actually work. But it also means the skill may be immediately wrong for someone else.
If my skill says the blog lives in a certain directory, or that I publish with a certain script, or that I prefer a certain way of editing HTML, then that is not general knowledge. That is local practice.
Start by growing the skill
This makes me think skills should start local. You grow them next to your own software, with your own tools, and your own habits. You do not need to begin with a universal skill that works for everyone.
A prompt like this is enough to start:
Build a skill for
bkt, the Bitbucket command-line tool. Runbkt --helpand gather information about that tool. Focus on the commands that work with the Cloud version of Bitbucket. Do not mention Data Center commands; we do not use Data Center.
That prompt does two things. It asks the agent to inspect the tool, but it also defines the boundary. It says what world this skill belongs to.
After that, you use it. The agent will still get things wrong, but the mistake has somewhere to land. You look at what happened and change the skill. With use, the skill starts to match how and where you work. It stops being a generic manual.
Share prompts, not finished skills
I am not sure the goal should be to make these skills general. Maybe the better thing to share is the prompt that creates the skill.
A skill can become a black box. It may contain hidden assumptions, old habits, local file paths, or features that only made sense for the person who wrote it first. When you install that skill, you also inherit those choices.
A prompt is different. It is just text. You can read it before running it.
You can change the parts that do not match your work. If someone shares a
prompt for building a bkt skill, I can adjust it before it turns
into my local skill.
That feels healthier. We do not have to pass around finished skills as if they are universal packages. We can share starting points, then let each environment grow the skill it actually needs.
Skills as part of the local environment
I like the idea that a project can have code, scripts, documentation, and skills. The skills explain how this particular project is operated. Not how every possible project could be operated. This one.
That is also how this blog is working. It is not a general publishing platform. It is a small HTML site, some scripts, and a growing set of habits around editing and publishing it with an agent.
The skill belongs there first. Close to the work. Close to the assumptions. Close enough that when it is wrong, you can fix it.