Standards
Why uze adopts AGENTS.md, Agent Skills, MCP and Agent Plugins instead of inventing a format
The easy mistake for a tool like uze is becoming one more format: moving the duplication into its own directory instead of removing it. So uze consumes the open standards that exist and models only what they leave out.
What uze adopts
| For | The standard |
|---|---|
| Project instructions | AGENTS.md |
| Skills | Agent Skills (SKILL.md) |
| Tools and resources | MCP |
| Bundling them | Agent Plugins 1.0 |
Each is stored exactly as written and never converted. Where an agent does not
read a standard natively, uze bridges it through that agent's own format, as it
does for Claude Code and AGENTS.md.
A standard is not the same as zero setup. MCP is one protocol, but Claude Code and OpenCode read servers from JSON while Codex reads TOML; skills live in a different directory per agent. That gap is what uze fills.
What uze adds
The standards above describe the parts of an agent's environment. None of them describes the environment itself: which parts a project uses, where they come from, and how to obtain the same ones again. For that gap, uze proposes three files. Each is small, readable without uze, and answers a single question. They are offered as candidates for a shared convention, not as a private format.
agents.yaml: what a project declares
A project states its intent in one file at its root: the marketplaces it draws from, the plugins it takes from each, and how agent work in the repository is handled. A person writes it and tools read it. Unknown keys are rejected rather than ignored, since a misspelled key in a file a person wrote should not be read as a decision.
agents.lock: what the declaration resolved to
The lock records what resolving the declaration produced, and nothing more:
the commit each marketplace was read at, and a SHA-256 digest of the bytes each
plugin delivered. It carries no intent, so it can always be regenerated and
never needs repair. The division is the one language package managers draw
between a manifest and a lockfile, applied to the tools an agent works with.
Together the pair makes an environment reproducible: git clone && uze install
yields the same plugins, at the same bytes, on any machine.
marketplace.json: what a source offers
A marketplace is a Git repository with an index at its root, naming each plugin
and the directory it lives in. The index keeps the name and the fields (name,
owner, plugins) that agent marketplaces already use, so an existing
marketplace needs no second index to be read.
The complete schemas are in agents.yaml & agents.lock and Plugin format. They are written for adoption: a tool other than uze reading these files is the outcome they aim at.