Skills
What OKE ships to teach AI agents the system — the repo-level AGENTS.md contract and the installable skills under .agents/skills/.
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 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, because knowing the system is not the same as being trusted by it.
Learn more
- MCP — the runtime surface these contracts pair with
- The Architecture — the eight elements in human terms
- llms.txt —
/llms.txt,/llms.json,/llms/agents, per-page markdown