skill
uio
uio is a lightweight, provider-agnostic framework for defining and running AI agents, skills, and prompts.
Set up
Skills are installed by placing their folder where your agent loads skills.
The download comes from github.com/uio-project/uio itself, not from our server, so what you get is exactly what its author published.
Install instructions come from the README
README
synced Oct 23, 2026uio
uio is the agent runtime for CI/CD. Define agents, skills, and prompts as plain markdown files with YAML frontmatter — checked into your repo, executed headlessly in pipelines, and wired to any LLM provider. The origin story covers how and why.
Why uio?
uio occupies a distinct niche: definition-as-code automation. The agents, skills, and prompts you author live in your repo, run headlessly in CI/CD, carry distinct GitHub App identities, and produce auditable cost records.
Interactive assistants (chat UIs, IDE plugins, terminal REPLs) are what you open when you want to build something at a terminal. uio is what runs at 3am when no one is watching.
| Need | Interactive assistant (e.g. Copilot, Cursor) | uio |
|---|---|---|
| Designed for headless CI/CD execution | No | Yes |
| Definitions stored in git | No | Yes — plain markdown files |
| Reproducible across environments | No | Yes — provider-agnostic |
| Scriptable / composable | Limited | Yes — uio agent run, uio skill run |
| Auditable cost records | No | Yes — JSONL ledger, uio cost |
| Multi-agent GitHub identities | No | Yes — planner / coder / reviewer App identities |
| Definition sharing | No | Yes — git-hosted registries |
| Auditable history of changes | No | Yes — git blame, PR diffs |
If your use case is "trigger an agent on push, review its output in a PR" — that is exactly what uio is designed for. See docs/20-positioning.md for the full comparison and rationale.
Concepts
| Concept | What it is |
|---|---|
| Agent | A multi-turn tool-use loop that can execute shell commands and call MCP tools; defined in *.agent.md |
| Skill | A focused, composable subtask — same loop as an agent, but user-directed via uio skill run; defined in *.skill.md |
| Prompt | A single-shot LLM instruction with no tool loop; defined in *.prompt.md |
| Workflow | A sequential pipeline of agent/skill/prompt steps with output chaining; defined in *.workflow.md |
| Tool | An external capability the model invokes mid-loop (MCP tools, run_command) — agent-directed, not user-directed |
See the Glossary for precise definitions of all terms, including the skill vs tool distinction.
Documentation
Full documentation lives in docs/ — covering installation, core concepts, a quickstart, CLI reference, configuration, providers, MCP integration, the chat REPL, cost ledger, registry, writing definitions, etc.
See Use Cases for end-to-end worked examples.
Quickstart
pip install uio-ai
# Scaffold .uio/ and install bundled examples
uio init --examples
# Run one of the bundled examples
uio skill run summarise "Your text here"
uio agent run repo-health
# Inspect the full system prompt before running
uio explain agent repo-health
# Interactive streaming chat
uio chat
# View token spend
uio cost
Definitions live in .uio/:
my-project/
└── .uio/
├── agents/ my-agent.agent.md
├── skills/ my-skill.skill.md
├── prompts/ my-prompt.prompt.md
├── workflows/ my-workflow.workflow.md
└── memory/
See Writing Definitions for the full file format and authoring guide.