Readme of agentjido/kata

The Jido Work System gives your AI agent two skills:

$jido carries one goal to a checked result. It plans the smallest set of steps, works inside the authority that you give, and checks the result.
$tutor teaches you to direct and check agent work. It uses your real task for practice and gives feedback on what you write.

You set the goal, the limits, and the authority. You decide whether the result is useful.

Install

You need Node.js and npm. Open the workspace where you use your agent, then run:

npx skills add agentjido/skills

Select jido and tutor. Start a new agent session so that the host loads them.

This README uses $jido and $tutor. If your host uses a different skill syntax, such as /jido, use that syntax. See the installation guide for host options and the trust boundary.

Start here: your first real task

Use this path if you are new to agent work or new to Jido. It takes one real task from a clear request to a checked result.

Start Tutor. Send $tutor with no other text. Tutor welcomes you and asks which real task you have now. This reply also shows that the install works.
Bring one real task. Pick a small task that you need this week. Tutor helps you state the result that you need and a check that shows when it is done. Tutor gives feedback, and you revise.
Get a Jido request. Ask Tutor to turn your work into a $jido request. Tutor writes the request, but it does not run it.
Run it with Jido. Send the request. Jido states its plan and authority limit in one sentence, does the work, and returns the result with evidence.
Check the result. Send $tutor review this result against my done check. Tutor helps you accept the result or write a specific repair request.

An example start. The exact words change with the host and model:

You:   $tutor
Tutor: Welcome. Which real task do you have now? We can start with a
       first win on that task, or I can show the topics.
You:   I need to compare three vendors for my team lead.
Tutor: What should exist when the work is done, and how will your team
       lead check it?

The Jido request that comes from this lesson can look like this:

$jido compare vendors A, B, and C on price, support hours, and contract length, with one source for each cell. Read only the vendor sites and my budget note. Do not contact a vendor.

Jido starts with one plan sentence, for example:

Jido: produce the comparison table, then check each source. No external contact.

Fast path: go straight to Jido

If you already direct agents, give Jido a goal and a limit:

$jido find why the nightly report job failed, fix it locally, and show the passing run. Do not commit or push.

Tell Jido what you need, not how to do it. Jido selects the steps.

Which entry to use

You want	Use	Example
An answer or one small action	A direct request	What does this error message mean?
A checked result from work with several steps or an unclear part	`$jido`	`$jido turn these notes into a decision brief and check its claims`
To learn how to direct, check, or improve agent work	`$tutor`	`$tutor help me check this agent's report`

Jido and Tutor do not start each other. Jido can recommend a $tutor request for a learning gap. Tutor can write a $jido request for you to send.

Give authority in the request

A request grants only the actions that it names. State the limit with the goal:

Limit	Example request
Inspect and report	`$jido explain why the export test fails. Do not change files.`
Change local files	`$jido fix the export test locally. Do not commit.`
Named external actions	`$jido fix the export test, commit it, and open a pull request. Do not merge.`

Each action needs its own authority. Inspection does not permit a write. A local change does not permit a commit. A commit does not permit a push. A push does not permit a merge, tag, or release.

Jido asks a question only when the answer can materially change the result, scope, cost, risk, authority, owner, or an irreversible effect.

How Jido works

Jido uses only the steps that your goal needs, in this order:

Step	What it does
Investigate	Establish facts, causes, and current state.
Plan	Set direction, scope, decisions, and sequence.
Delegate	Give bounded work to separate workers and integrate the return.
Produce	Make one candidate result.
Check	Check the candidate against its acceptance conditions with evidence.
Deliver	Commit, push, open a pull request, merge, tag, or release, only with that authority.

Jido starts at the first step that your request does not already resolve. Its plan sentence uses these verbs, so you can see which steps it selected. A separate request to improve a reusable work method uses an improve step.

For a material or risky check, Jido uses a separate worker when the host supports one. When it cannot, it labels the verdict self-checked.

These steps are internal methods, called Katas, in skills/jido/references/. You do not need their names to use Jido.

How Tutor works

Tutor teaches effective AI work through the Jido Work System. It can coach you on a task in any field, but it teaches the work method, not the field. For example, it can help you direct an agent on a biology task, but it does not teach biology.

You can:

ask a direct question about agent work;
explore the topics and choose one;
get coaching on a real task;
take one short lesson on a real task; or
get a review of work that you or an agent produced.

The topics are: define useful work, direct agents, use Jido, verify work, improve work, and agentic engineering for software work.

Tutor is read-only. It does not edit files, run work, or store a learner profile. At the end of a practice exchange, it can give you a short progress note. You keep the note and can bring it back next time.

Local routines

A project can define repeatable local work in docs/routines/. Jido can list, show, make, validate, or run these routines:

$jido make a dependency health routine
$jido run the dependency health routine
$jido run all routines

A routine produces a bounded work request. It cannot grant authority. Task systems, schedulers, and notification services are outside the routine loop.

Specialist skills

Jido can use a separate team or domain skill only when the host already exposes it. Jido does not scan the file system or install missing skills. Elixir and Jido SDK specialist methods are not part of this general package.

Make Jido a default

Use Jido without $jido for substantial work by adding a standing preference to your host. For Codex, add this line to ~/.codex/AGENTS.md:

Prefer $jido for substantial or ambiguous work that benefits from routing, coordination, or verification; skip it for simple questions, direct commands, and small self-contained tasks.

This is a preference, not a requirement for every request. A direct $jido request remains available.

Upgrading from 0.5

Version 0.6 replaces the former public kata-* commands with two public skills: Jido and Tutor. The detailed work methods remain internal to Jido. There are no aliases or compatibility wrappers. The v0.5.0 release remains the last multi-skill package.

Maintainers

Dojo is opt-in evaluation tooling for one exact method candidate. Jido uses it only when a request names Dojo. See Contributing before you change a skill.

Project links

The Jido Work System is authored by Jidoka Labs and licensed contributors. It is licensed under Apache-2.0. Adapted material keeps its required license notices and attribution.