标签：#reporeadiness

Overview AGENTS.md is useful. It gives AI coding agents a place to find repo-specific guidance: how to behave what conventions matter what areas need extra caution what kinds of changes should trigger review That is a meaningful improvement over sending an agent into a repo with no instructions at all. But AGENTS.md is not enough. It can tell an agent to be careful. It cannot, by itself, make execution safe, verification trustworthy, or review inspectable. For that, a repository needs more than instructions. It needs: declared safe commands a canonical verification path receipts that show what actually ran That is the difference between agent guidance and execution governance. Instructions Help. They Do Not Govern Execution. An instruction file is still prose. That means it can express intent, but it does not automatically create operational truth. For example, AGENTS.md can say: run the right checks before handoff avoid destructive commands do not edit generated files ask before touching infrastructure Those are good rules. But notice what they leave unresolved: which checks are the right ones which commands are actually safe which paths are protected structurally versus only suggested what should count as evidence that verification happened how to tell whether a failure came from code, setup, or drift That is where many agent workflows still break down. The agent may follow the spirit of the instructions and still take the wrong execution path. Safe Commands Need To Be Explicit One of the biggest gaps in agent-oriented repos is that they often declare guidance without declaring a safe command surface. The repo may tell the agent: Run tests before you finish. But that still leaves a dangerous amount of interpretation. Which task is safe? Is it: npm test pnpm test make check docker compose run test a narrower unit-test path the CI workflow itself And if several exist, which one is canonical for a routine code change? The repo should not force the agent to infer that

Overview 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. Why an Ota skill exists 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. What the skill teaches an agent The official skill lives in ota-run/skills . It is aime