skill-description
Skill0 starsChanged 29 days agoMITView on GitHub
Checks that a skill's description fires on the right prompts and not on near misses, in each tool, and rewrites it until it does. Use when a skill won't fire or misfires.
- Installs packages
In this repository19 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- skill-benchSkill
- skill-checkSkill
- skill-competeSkill
- skill-createSkill
- skill-evalSkill
- skill-factsSkill
- skill-improveSkill
- skill-learnSkill
- skill-packageSkill
- skill-planSkill
- skill-pluginSkill
- skill-publishSkill
- skill-releaseSkill
- skill-repoSkill
- skillSkill
- skill-tidySkill
- skill-tokensSkill
The file
We split this skill into the rules it gives an agent
1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 14
Use the skill's evals/triggers.json if it has one.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Tune a description
A skill fires when the model, reading its name and description among all the others, decides it fits. This finds out what really happens in each tool, then improves the description without fitting it to the prompts you looked at.
The engine runs as npx -y @thenavidm/skill-builder@latest. Where skill-builder is installed (npm install -g @thenavidm/skill-builder), run skill-builder instead: it's the same engine, without the download.
1. The prompts
Use the skill's evals/triggers.json if it has one. Otherwise write one with them:
- 8 to 10 prompts that should fire it, said the way people really talk: casual and formal, with typos and abbreviations, some that never name the skill, a few where another of their skills is also plausible but this one should win.
- 8 to 10 near misses that share its words but need something else. An unrelated prompt tests nothing.
Show them the list before running it: a bad set produces a bad description.
2. Measure
Say how many runs it takes, then:
npx -y @thenavidm/skill-builder@latest trigger <skill> --set <triggers.json> --runs 3 --split--split holds back 40% of the prompts. For each tool you get which prompts fired the skill, which near misses fired it wrongly, and which other installed skill took a prompt instead. A run marked blocked stopped on a permission and doesn't count.
3. Find the cause
| Pattern | Usual cause |
| Misses across every tool | The description doesn't use the words people say, or the name says nothing |
| Misses in one tool only | That tool's list is crowded: check skill-builder tokens |
| Another skill takes it | The two overlap; add a boundary to each ("Not for X, use Y") |
| Fires on near misses | Too broad: say what it's not for |
4. Rewrite and prove
Rewrite the description (what it does, when, one boundary, about 300 characters) and, if it says nothing, the name. Run trigger again on the same set. Keep the version that scores best on the held-back prompts, not the ones you studied, so the improvement holds for prompts nobody has written yet. Stop after three rewrites that don't improve the held-back score, and say which version is best.
Show the old and new description side by side with the scores in each tool.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.