# AGENTS.md vs skills

> Read the latest update from Composables.

Published 11 November 2026 by Alex Styl.

**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