Agents & Skills Reference

More skills can make an AI agent worse. Reusable skills are powerful because they turn repeatable work into structured workflows. But once an agent has many skills, the key question becomes:

Can it choose the right one?

Most systems don’t load every full skill instruction every time. They start with the skill name and description. Only when there’s a match does the agent load the full instructions, templates, scripts, or reference files. 

So the description is not just documentation. It’s part of the routing system.

A few things I’d pay attention to:

𝟏. 𝐖𝐫𝐢𝐭𝐞 𝐧𝐚𝐫𝐫𝐨𝐰 𝐝𝐞𝐬𝐜𝐫𝐢𝐩𝐭𝐢𝐨𝐧𝐬

The description should make it clear when to use the skill, and just as importantly, when not to use it.

𝟐. 𝐀𝐯𝐨𝐢𝐝 𝐨𝐯𝐞𝐫𝐥𝐚𝐩𝐩𝐢𝐧𝐠 𝐬𝐤𝐢𝐥𝐥𝐬

If three skills can handle the same task, routing becomes messy fast.

𝟑. 𝐓𝐮𝐫𝐧 𝐨𝐧𝐥𝐲 𝐬𝐭𝐚𝐛𝐥𝐞 𝐰𝐨𝐫𝐤𝐟𝐥𝐨𝐰𝐬 𝐢𝐧𝐭𝐨 𝐬𝐤𝐢𝐥𝐥𝐬

Not every repeated prompt deserves to become a skill. The best candidates are repeatable, high-value, and have a clear output standard.

𝟒. 𝐒𝐜𝐨𝐩𝐞 𝐩𝐞𝐫𝐦𝐢𝐬𝐬𝐢𝐨𝐧𝐬 𝐜𝐚𝐫𝐞𝐟𝐮𝐥𝐥𝐲

A skill that can read files, call tools, or run scripts needs much tighter boundaries than a simple writing workflow.

𝟓. 𝐑𝐞𝐯𝐢𝐞𝐰 𝐬𝐤𝐢𝐥𝐥𝐬 𝐥𝐢𝐤𝐞 𝐩𝐫𝐨𝐝𝐮𝐜𝐭 𝐟𝐞𝐚𝐭𝐮𝐫𝐞𝐬

Skills can become outdated. Someone has to maintain them, improve them, and remove the ones that no longer make sense.

𝐌𝐲 𝐭𝐚𝐤𝐞:

The issue is not having “too many skills.”

The issue is having too many vague, overlapping, over-permissioned, or unmaintained skills.

The more skills an agent has, the more important it becomes to treat them like a workflow system.