Why solo developers end up with a messy skills folder
Claude Code skills start simple. You write one for your deploy process, one for your test conventions, one for how you like commit messages. Six months later you have thirty of them, half of them overlap, two of them contradict each other, and you cannot remember which one is actually loaded.
This is not a discipline problem. It is a naming and ownership problem. Nobody told you which skills belong to you, which belong to a project, and which should have been deleted after the migration finished.
The three scopes, and why mixing them breaks things
Every skill belongs to exactly one scope. Pick the scope before you write the skill, not after.
- Personal – how you personally like work done. Commit message style, your review checklist, your tone. These travel with you across every project.
- Project – facts about one codebase. The build command, the deploy target, the naming convention that repository actually uses. These die when the project dies.
- Task – a one-off. “Convert the payment provider”, “migrate the database”. If it will be irrelevant in three weeks, it is not a skill, it is a checklist item.
The most common failure is writing a project fact as a personal skill. Then you start a second project, the skill still loads, and it confidently tells the agent something untrue about a codebase it has never seen.
What to build first
If you are starting from zero, resist the urge to write twenty skills. Write four, use them for two weeks, and only then decide what is missing.
- The build and run skill. How to install, run and test this project. One command each. This removes the most repeated question you will ever ask.
- The conventions skill. Naming, file layout, error handling, and what you do not want touched. Be specific about the things you have had to correct more than twice.
- The boundaries skill. What the agent must never do: no force pushes, no editing these directories, no changing that config. This is the one people skip and later regret.
- The workflow skill. How a change goes from idea to merged: branch naming, what a commit looks like, whether tests are required.
How to audit a skills folder that has grown wild
You cannot fix what you cannot see. Before deleting anything, build a list of every skill with four columns: name, scope, what triggers it, and the last time it actually changed your output.
That last column is the useful one. Most skills were written once, never edited, and have been silently influencing every session since. A skill that has not been read in three months is either perfect or wrong, and it is usually wrong.
Then check permissions. Skills that can touch your filesystem, run shell commands or reach the network deserve a second look. A skill is code you agreed to run without reading it again.
Signs a skills folder needs a cleanup
- Two skills give the agent conflicting instructions and you cannot tell which wins.
- A skill references a tool, service or folder that no longer exists.
- The same instruction appears in four skills because you kept copying it forward.
- You cannot answer “what is loaded right now” without opening a file browser.
What I sell, and why I am telling you
I built the Agent Skills Registry Kit, a spreadsheet that tracks skills across the three scopes with a version column, a permission column and a 23 item audit checklist. It is what I use to keep my own folder from turning into the mess described above, and it costs $19 once.
Everything in this article works with a plain text file and a spare hour. The spreadsheet only exists to make the audit repeatable.
Common questions
How many skills should a solo developer have?
Most solo developers run well with between four and eight. Beyond that you are usually maintaining duplicates. The number matters less than being able to say what each one does.
Should skills live in the repository or in my home directory?
Both, for different things. Project facts belong in the repository so collaborators and future you get them automatically. Personal preferences belong in your home directory so they follow you between projects.
When should I delete a skill?
When it describes something that is no longer true, or when it duplicates another skill. Do not keep a dead skill around as documentation. Delete it and write a comment in the commit instead.
Leave a Reply