I know I'm late at the party, but not long ago someone gave me the kick I needed to really make work of using and understanding AI.
What are (agent) skills
A short explanation for people who are not aware of skills.
Skills are a standardized format to add extra context to a prompt that is picked up by an agent. Because they are a standard other applications have adopted them too.
A basic skill is nothing more than a directory with a descriptive name and a SKILL.md file with name and description keys in frontmatter.
The convention is that the frontmatter name matches the directory name.
The content of the SKILL.md file is any context you can add to a prompt.
Why I think they are functions
As developers we are taught to create functions that are:
- short
- composable
- have no side effects
- single task
And I think you should look at skills the same way.
At the moment I have general-code-rules, php-rules and composer-rules skills. In each of them I set the rules that are specific for the domain.
I mentioned no side effects, but like any guideline you can ignore it when there is a good reason.
That is why I have Use the PHP version in composer.json to determine the PHP features to use in the php-rules skill.
Skill content
There are already skill sites like Skillsmp and skills.sh, and you can generate skills with AI. While it is good to see what others have done I think skills should be as specific as you need them to be.
You should not treat them as a library that gets you almost to your goal.
While I think it is fine to let an agent manipulate the skill based on decisions you make after asking a question. Don't fall into the trap of letting an agent find skills.
Skills need to be evaluated like any other dependency you use for a project.
Read them in a plain text because a markdown viewer can hide HTML comments that will be read by the LLM.
You can add CLI commands to skills. When the agent gets a command back from the LLM, it wil ask you to execute it. Because CLI command can be damaging double check if it is the action you need.
Conclusion
Skills are a great step forward making AI work with less friction.
Use them to your advantage and be safe.
Update: I found it funny that Claude, Codex and Gemini skill-creator all needed to state that their LLM is very smart.
Top comments (2)
This is a great mental model. Treating skills like functions—short, composable, and single-task—is the best way to solve 'prompt bloat' and context noise.
The comparison to dependency management is spot on. We’ve spent decades learning not to trust unverified npm packages; we shouldn't trust unverified Markdown files either, especially with hidden HTML comments or CLI commands.
I’m curious: when you compose multiple skills (like php-rules + composer-rules), do you ever run into 'logic collisions' where the LLM gets confused by competing instructions?
As I mentioned in the post it is still early days of using the full extend of the ai capacities.
I think if you spot competing instructions the solution is to use a sub-agent to keep the relevant contexts separate. But I haven't tried that myself.