Use agents.md for global context and skills.md for workflows you only need on demand.
agents.md is global context.
If something is not needed for every chat, it should not be there. Otherwise it is just context bloat.
skills.md is for workflows you only need sometimes.
Use agents.md for things that should shape nearly every interaction:
- default coding style
- response preferences
- repo-wide guardrails
- rules you want applied all the time
Use skills.md for things that are situational:
- task-specific workflows
- detailed runbooks
- domain-specific instructions
- procedures you only need on demand
For example, if I have a trading bot with a strict workflow:
- start the bot
- test the bot
- stop the bot
That does not belong in agents.md. I do not need it loaded when I am writing a blog post or fixing CSS.
It belongs in a skill like bot-testing/skill.md.
Then it only loads when I ask for it:
start and test the bot
Here is the simple version:
brush your teeth
That is everyday guidance. It belongs in agents.md.
Now compare that with:
make coffee
- grind the beans
- put a filter in the coffee maker
- add hot water
That should be a make-coffee skill. You only load it when you need it.
- everyday defaults go in
agents.md - optional workflows go in
skills.md
Keep agents.md lean. Load the detailed stuff on demand.