The Ota Skill for AI Agents

We built the Ota skill because too much "AI repo automation" is still fake confidence.

An agent clones a repo, finds a plausible command, edits the right file, and looks smart right up until it does something expensive and stupid. It runs the wrong test path. It installs tools globally because local setup was unclear. It patches around a missing service as if the repo were healthy.

That failure is usually blamed on the model. Most of the time it is a repo problem. The repository never made its real operating path explicit enough for the agent to follow without guessing.

Ota already gives the repo a machine-readable contract through ota.yaml. The skill exists to teach agents how to behave around that contract: what to trust, what to run, and when to stop instead of improvising.

It is not a replacement for ota.yaml. It is not an MCP server. It is not a hidden automation layer.

It is the missing operating guide for agents working in Ota repos.

We kept seeing the same pattern: the agent was fast, but the repo was vague.

Without a repo-specific operating guide, an agent may see several possible paths:

• run the command from the README
• copy the command from CI
• infer setup from package.json, pyproject.toml, or go.mod
• run a broad test command because it looks conventional
• install tools globally because a local command failed
• patch around a missing service instead of identifying the readiness gap

Some of those choices work. Some are dangerous. Some look fine locally and still miss the only verification path that matters.

Our view is simple: if a repo has ota.yaml, that file should beat README prose, shell folklore, and whatever command happens to look familiar. Declared tasks, writable paths, setup requirements, and validation commands should be treated as contract facts.

The skill exists to make that behavior explicit across agents that support skills.

The official skill lives in ota-run/skills. It is aimed at the work that actually shows up in live repos:

• authoring or refining an ota.yaml contract
• reviewing an existing contract for drift or weak boundaries
• running ota doctor, ota validate, ota tasks, and ota run
• deciding whether a problem belongs in the repo contract or in Ota itself
• preserving safe execution, writable path, and setup boundaries
• explaining repo readiness issues in terms humans can act on

What matters is not the length of the skill. What matters is the order it forces on the agent.

In an Ota repo, the agent should start from the contract, not from vibes. It should prefer declared tasks over shell improvisation. It should use JSON output when automation needs stable facts. It should not invent fields, flows, or setup steps the repo never declared.

That sounds obvious. It is also where a lot of agent work still goes off the rails.

The skill does not rescue a sloppy repo.

Readiness still belongs in the repo. The repo needs to state what it requires, how it becomes ready, what commands exist, and how those commands are verified. That is the job of ota.yaml.

The skill tells the agent how to behave around that contract.

For example, if a repo declares a test task through Ota, the agent should use ota run test instead of guessing at npm test, pytest, or go test ./.... If the repo exposes ota doctor, the agent should use it to understand readiness before mutating files. If the repo has writable path boundaries, the agent should treat those boundaries as real, not as suggestions.

This matters because AI-assisted development usually fails at the edges:

• setup was incomplete
• a service was missing
• the agent ran the wrong verification command
• a generated file was edited directly
• a one-off shell command bypassed the repo's intended workflow
• a local success did not match CI

What it does do is keep the agent anchored to the same contract humans and CI are supposed to trust.

Agents and environments can consume skills differently. The current supported install paths are:

npx skills add ota-run/skills --full-depth

or

ota skills install --agent codexota skills install --agent claude

The ota-run/skills repository is the source of truth for the skill distribution. ota skills install gives Ota a first-party install path for supported agent environments, and the skills CLI path supports workflows that consume skill repositories directly.

The site also exposes discovery links for agents:

• https://ota.run/.well-known/agent-skills/index.json
• https://github.com/ota-run/skills
• https://skills.sh/ota-run/skills

Those URLs are intentionally boring. Discovery should not be the hard part.

The Ota skill is not a live MCP server. Ota publishes MCP discovery metadata today, but it does not currently run a live MCP protocol endpoint. That distinction matters. Discovery metadata can help agents understand the intended integration surface, but it is not the same as a callable server.

The skill is also not a replacement for repo-specific instructions. A repository can still need an AGENTS.md, contributor guide, security policy, or team review rules. The Ota skill covers Ota-specific behavior: how to understand and preserve repo readiness contracts.

Finally, the skill is not a permission slip for broad mutation. If a repo does not declare a safe task, setup path, or writable area, the agent should not silently invent one.

The best agent workflows are usually the least theatrical. They make fewer bad guesses.

When an agent enters an Ota repo, the ideal sequence is simple:

1. Read the Ota skill so it understands the operating model.
2. Inspect ota.yaml as the repo readiness source of truth.
3. Run ota doctor or ota validate to understand the current state.
4. Use ota tasks to discover supported commands.
5. Use ota run <task> for declared execution.
6. Report readiness failures as contract or environment issues instead of guessing around them.

That sequence feels slower only if you compare it to blind guessing in the first minute. After that, it is usually faster because it cuts false starts, side quests, and "works on my machine" fixes that were never real.

That is the practical value. The agent gets the same operating model every time. It does not need to rediscover Ota in each repo, and it does not need to guess whether ota.yaml is advisory or authoritative.

Teams do not need more demos. They need agents that can enter a real repository and not immediately lower the trust level.

That means respecting setup, CI, local services, generated files, ownership boundaries, and verification paths. It means being able to say, "this repo is not ready yet," instead of pretending a broken environment is a code problem. It means treating repo readiness as infrastructure, not as a suggestion buried in prose.

The Ota skill is one piece of that system, but it is an important one. It gives the agent Ota-specific context before the first command runs. ota.yaml gives the repo its contract. The CLI gives humans, CI, and agents the same command surface.

That combination is the point.

If a team wants agents to be useful in production repos, the answer is not more vibe-based automation. The answer is stricter contracts, narrower boundaries, and tools that teach the agent what those boundaries actually mean.

That is why we built the Ota skill.