Tools alone don't make a good operator — an agent also needs to know the _vocabulary_: what a Flow is, why `fx` is the only door, which driver ids are legal. OKE ships that knowledge as contracts and skills that agents load automatically, so sessions start aligned instead of drifting and getting corrected. ## The layers | Layer | Path | Loaded when | Teaches | | ------------------ | ---------------------------- | ------------------------------------------------- | ---------------------------------------------------------------------- | | **Agent contract** | `AGENTS.md` (repo root) | Every agent session, automatically | The one law, eight elements, one contract, the fx rule, ports, budgets | | **Element skill** | `.agents/skills/oke/` | Building or changing an okengine app | The element contract in depth — declaration patterns per element | | **Docs skill** | `.agents/skills/oke-docs/` | Writing or editing docs under `site/content/docs` | The documentation information-architecture standard and its gates | | **Ship skill** | `.agents/skills/oke-ship/` | After any implementation, before claiming done | Changelog under `## Unreleased` + docs sync via `oke-docs` | | **Deps skill** | `.agents/skills/oke-deps/` | Updating `package.json` dependencies | Scoped bumps, Bun install, pins (Drizzle RC, fumadocs alias, …) | | **Images skill** | `.agents/skills/oke-images/` | Updating Compose image pins | Registry probe, pin style, catalog + recipes + Keel + docs lockstep | Contributor-only skills in the same tree (not required for app authors): `oke-ci`, `oke-docs-update`, `oke-docs-visuals`, `oke-console-style`. ## AGENTS.md — the root contract Every OKE app's repo carries an `AGENTS.md` that agents (Cursor, Claude Code, and peers) read at session start. It is deliberately short and absolute: every backend behavior is a Flow (`on(Trigger) → Effects`), there are eight elements bound to one contract, all world access goes through `fx`, drivers are named after protocols, and the ports/budgets are fixed. Its closing rule is the one that keeps agents honest: **if the documentation is silent, stop and ask** — never invent the API. ## Skills — installable know-how Skills are `SKILL.md` packages an agent loads when the work matches their description. OKE ships: | Skill | Use it for | Inside | | ------------ | -------------------------------------------- | ------------------------------------------------------------------------- | | `oke` | App work — flows, elements, drivers | The agent contract, element patterns, the fx invariants | | `oke-docs` | Docs work — new pages, rewrites | The page skeleton, verification sources, the density gate | | `oke-ship` | Closing an implementation — changelog + docs | Append under `## Unreleased`; `bun run bump` promotes it into `## vX.Y.Z` | | `oke-deps` | Dependency updates — one package or all | Scope map, `ncu` + Bun, reject downgrades / protect RC and aliases | | `oke-images` | Compose image pins — one image or all | Registry probe, keep pin style, never `:latest`, sync catalog → docs | All live in the repo under `.agents/skills/`, so they travel with the code and stay versioned with what they describe. ## How contracts compose with MCP Contracts teach the _vocabulary_; [MCP](/docs/ai/mcp) grants the _hands_. An agent that knows the eight elements from `AGENTS.md` reads the Manifest through `oke.manifest.get` with the right mental model — and its write attempts still pass through [per-call human confirmation](/docs/ai/mcp), because knowing the system is not the same as being trusted by it. ## Learn more - [MCP](/docs/ai/mcp) — the runtime surface these contracts pair with - [The Architecture](/docs/understand/the-architecture) — the eight elements in human terms - [llms.txt](/docs/ai/llms-txt) — `/llms.txt`, `/llms.json`, `/llms/agents`, per-page markdown ## Next