AGENTS.md contains your preferences for how you want your agent to behave.
Think of it as the prompt your agent reads every time it starts.
Mine tells the agent to always read the project's README and CONTRIBUTING files, so it has the context of the repo I'm working on.
It also says how I want it to talk to me: direct, not chatty.
Skills on the other hand are repeatable flows you can reuse over and over again.
Anything you did over and over before agents is a great fit.
Architecture is a great candidate for a skill. My compose-architecture skill describes how my app's screens should be built: one sealed class for the screen's state, and one-shot events for side effects like navigation or a snackbar.
The agent gets it right on the first try. The best part is that it cuts down QA, because the screens can't end up in states that make no sense, like showing a success checkmark and an error message at the same time.
The architecture makes those states impossible, and the skill makes sure the agent follows it.
tldr: preferences go in AGENTS.md. Workflows go in skills.
Happy coding,
– Alex
