Skip to main content
An AI agent can only use a tool it knows about. Workser Code ships the instructions that teach yours. Inside Workser Desktop this happens during onboarding — you don’t have to do anything. This page is for running the CLI on its own, or for understanding what your agent has actually been told.

​
Two formats, same content

Skill

For agents with native Skill support (Claude Code). Loaded on demand, so it costs nothing until it’s relevant.

AGENTS.md

The portable form, for every other agent — Codex, OpenCode and the rest. Merged into your project’s AGENTS.md.
Workser Code drops the right one per agent. Installing them by hand:
There’s a matching pair for the SDK (workser-sdk), which teaches the agent how the app reads its own data at runtime — a different job from operating the app.

​
Why a Skill instead of MCP tools

The obvious alternative is to expose every Workser capability as an MCP tool. Workser Code deliberately doesn’t make that the primary path. The Workser CLI provides a discoverable command surface with focused help. Skills teach the agent when and how to use it. MCP tools can also be configured for a role; enable the tools that role needs rather than assuming every task needs the full catalog. The practical effect: more of your agent’s context is spent on your actual problem.

​
Progressive disclosure

The Skill is an index, not a manual. It points at one focused guide per topic, each about a screen long, printed by the CLI itself:
Because the guides come from the CLI binary, what your agent reads always matches the version it’s running — there’s no separate documentation to drift out of date.

​
The rules your agent is given

Worth knowing, because they explain behaviour you’ll see:
  1. Always pass --json — so output is one stable, parseable line.
  2. Orient first. Read workser status, plus the board and the decision log, before doing anything beyond a trivial edit. The project outlives the conversation.
  3. A phased plan goes on the board before it gets built — one card per phase, the plan as a doc, a decision record if it settled a real tradeoff. A plan that lives only in a chat reply is gone when the conversation scrolls.
  4. Stay in your lane. owner_only means it’s yours to do in Workser Code. Don’t retry, don’t look for a workaround.
  5. Approvals are normal. awaiting_approval means asking you and retrying — never bypassing.
  6. Keep credentials out of prompts and output. Use environment or connection settings. Secret-revealing commands are sensitive; do not echo their results.
  7. Verify before “done”. Inspect which checks ran, report their results and test the required behavior. An agent’s reading of the diff alone is not verification.
  8. Respect permissions and refusals. Use the appropriate migration, recovery and approval flow. Do not bypass a denied or unsupported operation.

​
The mistake these instructions exist to prevent

The most common failure is using the CLI where the SDK belongs: an app shelling out to workser db query on every request instead of reading its own data through @workser/app. The line is simple, and both skills state it:
  • Happens when a user hits the app → the SDK.
  • Happens to the app — provision, configure, deploy, read logs → the CLI.
  • Keeps running after the request finishes → a workflow.

​
Next

Security & approvals

What your agent is allowed to do, what pauses for you, and what it can never do at all.