Choosing agent skills from a directory

Read the file the skill is made of

To choose an agent skill, open the SKILL.md that defines it and read the whole thing. A skill is a set of instructions a model loads, so the file is the skill: its name and short description at the top decide when the model reaches for it, and the text below decides what it does. Then check who published it, whether the repository is still maintained, and try it on a task where you already know the right answer.

This is easier than vetting a server because there is less to vet. A skill reaches nothing and asks for no credential. The question is whether its instructions are any good and whether they say what you expect, not what it can touch.

Why directory counts differ so much

Skill indexes disagree wildly about how many skills exist. Some list every name they have ever seen mentioned, including entries that point at no repository and entries attributed to a publisher whose own repository holds far fewer. A big number is easy to produce and hard to check.

The skills directory (skills on record: 3,022) only counts one when it resolves to a SKILL.md file that was actually read, with that file's own address beside it. Its page says plainly that other indexes list far more, and that part of the gap is a limitation rather than a virtue: some publishers named elsewhere resolve to no repository it can find yet, so their skills may exist and are simply unread.

For choosing, the smaller list has one advantage: every row links to a file you can open and judge.

What to look for in the SKILL.md

Start with the description in the front matter, the short block at the top of the file. The model uses it to decide whether the skill applies, so a description that is vague will fire at the wrong time or not at all. A good one names the task and the situations it covers in a sentence or two.

Read the body as you would read a colleague's checklist. Does it say what to do, in what order, with what checks? Does it name files, commands or formats that exist in your setup? Instructions written for someone else's project will be confidently wrong in yours.

Check the length too. A skill that runs to many pages may cover a lot, but the model has to read and follow all of it, and long instructions are easier to follow partly.

Look for anything the skill tells the model to run. A skill cannot reach a service by itself, but its instructions can tell a model to call tools you have already connected, or to run commands in a terminal it has access to. Those lines are where a skill stops being only text, so read them twice.

Publisher, repository and licence

Each skill in the directory is listed as publisher and name, read from the repository that holds it. Publishers often ship many skills from one repository, so maintenance is a property of the repository: if it has gone quiet, every skill inside it has gone quiet with it. The directory counts its maintenance signals by repository for that reason, so one large repository does not decide the whole picture.

Some skills are marked as a vendor's own, published by the company whose product the skill is about. That tells you who wrote it, which is useful when the skill describes how a specific product works. It is not a quality grade. The licence, where the front matter or repository states one, tells you what you may do with the file.

Test on a task you already know

Pick a job you have done by hand recently, load the skill, and ask for the same job. You know what good output looks like, so you can see whether the skill helps, gets in the way, or fires when you did not want it. One honest test tells you more than the description.

Then try a request that should not trigger it. A skill whose description is too broad will try to take over unrelated work. If that happens, edit the description in your own copy or leave the skill out. The agents layer covers the frameworks that load skills, if you need to see where they plug in.

Keeping a short list rather than a long one

Every skill you install adds a description the model has to weigh before it starts work. A handful of skills with sharp descriptions are easy for a model to choose between. A large pile of overlapping ones makes it more likely the wrong one fires, or that two give conflicting instructions for the same task.

Keep the skills you actually use and remove the ones you tried and forgot. When two skills cover similar ground, keep the one whose instructions match how you work and delete the other, or merge the useful lines into one file of your own. A skill is plain text, so editing a copy is allowed wherever the licence permits it, and often the best version of a published skill is the one you trimmed.

Note where each one came from. Recording the publisher and the repository next to your copy means you can check later whether the original changed, and decide whether to take the change. The directory's use-case pages are a reasonable place to look for a replacement when a skill you rely on stops being maintained.