Agent skill

Orch

AI agent orchestrator — manage teams of AI agents that work on your codebase in parallel.

Install Orch

skills CLI

$ npx skills add oxgeneral/ORCH --skill orch -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI

$ gh skill install oxgeneral/ORCH orch --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy

$ git clone --depth 1 https://github.com/oxgeneral/ORCH.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/orch .claude/skills/orch && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Paste into Claude Code

Install the "orch" agent skill from https://github.com/oxgeneral/ORCH/tree/main/skills/orch into .claude/skills/orch/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "orch", then confirm the skill loads.

Claude Code copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

$skill-installer

$skill-installer install https://github.com/oxgeneral/ORCH/tree/main/skills/orch

Type this inside Codex. $skill-installer <name> installs a curated skill from openai/skills. The installer writes to $CODEX_HOME/skills (default ~/.codex/skills). Restart Codex if the skill does not show up.

skills CLI

$ npx skills add oxgeneral/ORCH --skill orch -a codex

Project install goes to .agents/skills/; add -g for ~/.codex/skills/.

GitHub CLI

$ gh skill install oxgeneral/ORCH orch --agent codex

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/oxgeneral/ORCH.git skills-src && mkdir -p .agents/skills && cp -r skills-src/skills/orch .agents/skills/orch && rm -rf skills-src

Use ~/.agents/skills/ instead of .agents/skills for a personal install.

Codex skills documentation · loads skills from .agents/skills/

Paste into Codex

Install the "orch" agent skill from https://github.com/oxgeneral/ORCH/tree/main/skills/orch into .agents/skills/orch/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "orch", then confirm the skill loads.

Codex copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add oxgeneral/ORCH --skill orch -a cursor

Project install goes to .agents/skills/; add -g for ~/.cursor/skills/.

GitHub CLI

$ gh skill install oxgeneral/ORCH orch --agent cursor

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/oxgeneral/ORCH.git skills-src && mkdir -p .cursor/skills && cp -r skills-src/skills/orch .cursor/skills/orch && rm -rf skills-src

Use ~/.cursor/skills/ instead of .cursor/skills for a personal install.

Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/

Paste into Cursor

Install the "orch" agent skill from https://github.com/oxgeneral/ORCH/tree/main/skills/orch into .cursor/skills/orch/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "orch", then confirm the skill loads.

Cursor copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

gemini skills install

$ gemini skills install https://github.com/oxgeneral/ORCH.git --path skills/orch

--scope user (default) or --scope workspace; --path is the subfolder of the repo that holds the skill; --consent skips the security confirmation prompt.

skills CLI

$ npx skills add oxgeneral/ORCH --skill orch -a gemini-cli

Project install goes to .agents/skills/; add -g for ~/.gemini/skills/.

GitHub CLI

$ gh skill install oxgeneral/ORCH orch --agent gemini-cli

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/oxgeneral/ORCH.git skills-src && mkdir -p .gemini/skills && cp -r skills-src/skills/orch .gemini/skills/orch && rm -rf skills-src

Use ~/.gemini/skills/ instead of .gemini/skills for a personal install, then run /skills reload.

Gemini CLI skills documentation · loads skills from .gemini/skills/, .agents/skills/

Paste into Gemini CLI

Install the "orch" agent skill from https://github.com/oxgeneral/ORCH/tree/main/skills/orch into .gemini/skills/orch/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "orch", then confirm the skill loads.

Gemini CLI copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

GitHub CLI

$ gh skill install oxgeneral/ORCH orch

Installs for Copilot at project scope by default; add --scope user for a personal install. Preview a skill first with gh skill preview. Needs GitHub CLI 2.90.0 or later (public preview).

skills CLI

$ npx skills add oxgeneral/ORCH --skill orch -a github-copilot

Project install goes to .agents/skills/; add -g for ~/.copilot/skills/.

Manual copy

$ git clone --depth 1 https://github.com/oxgeneral/ORCH.git skills-src && mkdir -p .github/skills && cp -r skills-src/skills/orch .github/skills/orch && rm -rf skills-src

Use ~/.copilot/skills/ instead of .github/skills for a personal install. Commit .github/skills so cloud agent and code review can use it.

GitHub Copilot skills documentation · loads skills from .github/skills/, .claude/skills/, .agents/skills/

Paste into GitHub Copilot

Install the "orch" agent skill from https://github.com/oxgeneral/ORCH/tree/main/skills/orch into .github/skills/orch/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "orch", then confirm the skill loads.

GitHub Copilot copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add oxgeneral/ORCH --skill orch -a opencode

OpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.

GitHub CLI

$ gh skill install oxgeneral/ORCH orch --agent opencode

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/oxgeneral/ORCH.git skills-src && mkdir -p .opencode/skills && cp -r skills-src/skills/orch .opencode/skills/orch && rm -rf skills-src

Use ~/.config/opencode/skills/ instead of .opencode/skills for a personal install.

OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/

Paste into OpenCode

Install the "orch" agent skill from https://github.com/oxgeneral/ORCH/tree/main/skills/orch into .opencode/skills/orch/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "orch", then confirm the skill loads.

OpenCode copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

Facts

Skill name: orch
GitHub stars: 170
Token cost: ~5.2k tokens
SKILL.md length: 1,459 words
Files: 1
Skills in repo: 1
Repo updated: Aug 1, 2026
First seen: Oct 7, 2026
Licence: MIT

At a glance

AI agent orchestrator — manage teams of AI agents that work on your codebase in parallel.

Works in 5 steps: Natural language → CLI commands: User… → Always use --json flag when you need to… → Chain commands when the user's request… → …
The user wants to: run multiple agents
SKILL.md covers How to Work, Quick Start Flow, Complete CLI Reference and Common Workflows, plus 4 more sections
Calls opencode, codex and cursor

What it does

Orch is an agent skill from oxgeneral/ORCH. AI agent orchestrator — manage teams of AI agents that work on your codebase in parallel. Use when the user wants to: run multiple agents, coordinate AI work, deploy agent teams, manage tasks/goals/agents, check orchestrator status, or mentions 'orch', 'orchestry', 'agents team', 'agent orchestration'.

Its SKILL.md is about 5.2k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.

It sits in Agent Workflows, covering Multi-agent orchestration. The repository describes itself as: One CLI to orchestrate them all. Manage a team of AI agents executing tasks in parallel from your terminal using a command line interface to manage them all. Manage a team of…. The licence is MIT.

When your agent uses it

The user wants to: run multiple agents
Coordinate AI work
Deploy agent teams
Manage tasks/goals/agents

Example prompts

“orchestry”
“agents team”
“agent orchestration”
“/orch”

Requirements

Pre-approved tools (allowed-tools): Bash, Read, Glob, Grep, Write, Edit, Agent

Workflow steps

5 steps, taken from the first numbered list in SKILL.md.

Natural language → CLI commands: User says "add a task to refactor auth" → you run orch task add "Refactor auth module" -d "..." --scope…
Always use --json flag when you need to parse output programmatically
Chain commands when the user's request requires multiple steps
Explain what you're doing briefly before running commands
Show results in a readable format after commands complete

What it can do on your machine

Read from SKILL.md and the folder at commit c066dc0. It shows what the files ask for, not the result of running them.

Tool permissions
Pre-approves these tools, so the agent can use them without asking each time:
- Bash
- Read
- Glob
- Grep
- Write
- Edit
- Agent
From allowed-tools in the SKILL.md frontmatter.
Runs code
Shell commands in SKILL.md call:
- opencode
- codex
- cursor
From the folder's file list and the shell code blocks in SKILL.md.
Network
No URLs in SKILL.md.
From URLs in SKILL.md, links to its own repository left out.
Credentials
Names no API keys, tokens, secrets or passwords.
From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Orch loads about 5.2k tokens when it runs. Until then it costs about 77 tokens; SKILL.md has 1,459 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it: ~77
When it runs · the whole SKILL.md, loaded when a task matches: ~5.2k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check: notes

The automated check noted patterns worth knowing about, such as sudo or a known installer.

NotePre-approves every shell command (allowed-tools: Bash)SKILL.md
```
allowed-tools: Bash, Read, Glob, Grep, Write, Edit, Agent
```

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from oxgeneral/ORCH at commit c066dc0, republished under its MIT licence (© oxgeneral). 1,459 words, ~5,208 tokens.

Download SKILL.mdSave it as .claude/skills/orch/SKILL.md (or your agent's skills folder).

name: orch
description: AI agent orchestrator — manage teams of AI agents that work on your codebase in parallel. Use when the user wants to: run multiple agents, coordinate AI work, deploy agent teams, manage tasks/goals/agents, check orchestrator status, or mentions 'orch', 'orchestry', 'agents team', 'agent orchestration'.
allowed-tools: Bash, Read, Glob, Grep, Write, Edit, Agent
argument-hint: [command or natural language request]

ORCH — AI Agent Orchestrator

You are the user's assistant for ORCH (@oxgeneral/orch) — an AI agent runtime that coordinates teams of LLM agents working on a codebase in parallel.

Your role: interpret user intent and execute the right orch CLI commands. The user may speak in natural language — translate their intent into concrete actions.

How to Work

Natural language → CLI commands: User says "add a task to refactor auth" → you run orch task add "Refactor auth module" -d "..." --scope "src/auth/**"
Always use --json flag when you need to parse output programmatically
Chain commands when the user's request requires multiple steps
Explain what you're doing briefly before running commands
Show results in a readable format after commands complete

Quick Start Flow

If the project is not initialized (no .orchestry/ directory):

bash

orch init --name "project-name"

If there are no agents:

bash

orch agent shop  # or suggest pre-built org templates

Complete CLI Reference

Project Setup

bash

orch init [--name <name>]          # Initialize .orchestry/ in current directory
orch doctor                        # Check adapters and dependencies
orch update [--check]              # Check/install updates
orch status                        # Show orchestrator overview

Task Management

bash

# Create tasks
orch task add "<title>" [options]
  -d, --description <desc>         # Task description
  -p, --priority <1-4>             # Priority (1=highest, default: 3)
  -l, --labels <a,b,c>             # Comma-separated labels
  --depends-on <id1,id2>           # Dependency task IDs
  --assignee <agent-id>            # Assign to specific agent
  --scope <patterns>               # File scope globs (e.g. src/auth/**,src/session/**)
  --review-criteria <criteria>     # Auto-review: test_pass,typecheck,lint
  --workspace-mode <mode>          # shared|worktree|isolated
  --goal-id <goalId>               # Link to a goal
  --attach <paths>                 # Attach files (screenshots, docs)
  --max-attempts <n>               # Max retry attempts
  -e, --edit                       # Open $EDITOR for description

# List and view
orch task list [--status <status>] # List tasks (filter: todo,in_progress,review,done,failed,cancelled)
orch task show <id>                # Show task details

# Lifecycle
orch task assign <task-id> <agent-id>  # Assign task to agent
orch task cancel <id>              # Cancel task (stops agent if running)
orch task approve <id>             # Approve task in review → done
orch task reject <id> [-r <reason>] # Reject task → back to todo
orch task retry <id>               # Retry failed task
orch task edit <id>                # Edit in $EDITOR

Task Status Flow: todo → in_progress → review → done with retrying and failed branches.

Agent Management

bash

# Create agents
orch agent add "<name>" --adapter <type> [options]
  --adapter <type>                 # REQUIRED: claude|opencode|codex|cursor|shell
  --role <description>             # Agent role/expertise
  --model <model>                  # Model name
  --effort <level>                 # Reasoning effort: low, medium, high (Claude only)
  --command <cmd>                  # Shell command (for shell adapter)
  --max-turns <n>                  # Max turns per run
  --timeout <ms>                   # Timeout in milliseconds
  --approval-policy <policy>       # auto|suggest|manual
  --workspace-mode <mode>          # shared|worktree|isolated
  --skills <skills>                # Comma-separated skills
  -e, --edit                       # Open $EDITOR for role

# Agent shop — pre-built templates
orch agent shop [--list]           # Browse/install templates

# Manage
orch agent list                    # List all agents
orch agent status <id>             # Show agent details + stats
orch agent edit <id>               # Edit agent
orch agent remove <id>             # Remove agent
orch agent disable <id>            # Disable agent
orch agent enable <id>             # Enable agent
orch agent autonomous <id> [--on|--off]  # Toggle autonomous mode

Available Agent Templates: backend-dev, frontend-dev, qa-engineer, code-reviewer, architect, devops-engineer, bug-hunter, tech-writer, marketer, content-creator, growth-hacker, security-auditor, performance-engineer, data-engineer, fullstack-dev

Execution

bash

orch run <task-id>                 # Run single task
orch run --all                     # Run all todo tasks
orch run --watch                   # Continuous orchestration (tick loop)
orch tui                           # Interactive TUI dashboard
orch serve [options]               # Headless daemon mode
  --once                           # Process and exit (CI/CD mode)
  --tick-interval <ms>             # Override poll interval
  --log-file <path>                # Tee logs to file
  --log-format <json|text>         # Log format (default: json)
  --verbose                        # Include agent:output events

Goals (High-Level Objectives)

bash

orch goal add "<title>" [options]
  --description <desc>             # Goal description
  --assignee <agentId>             # Assign to agent for decomposition

orch goal list [--status <status>] # List goals
orch goal show <id>                # Show goal + progress report
orch goal status <id> <status>     # Change status: active|paused|achieved|abandoned
orch goal update <id> [options]    # Update title/description/assignee
orch goal delete <id>              # Delete goal

Teams

bash

orch team create "<name>" --lead <agent-id> [options]
  --members <id1,id2>             # Initial members
  -d, --description <desc>        # Team description
  --no-auto-claim                 # Disable auto-claiming

orch team list                    # List teams
orch team show <id>               # Show team details
orch team join <team-id> <agent-id>    # Add member
orch team leave <team-id> <agent-id>   # Remove member
orch team add-task <team-id> <task-id> # Add task to pool
orch team set-lead <team-id> <agent-id> # Transfer lead
orch team disband <id>            # Disband team

Pre-Built Organizations

bash

orch org list                     # List available templates
orch org deploy <template> [--goal "<objective>"]

Available Templates:

startup-mvp — Ship MVP in 48h (CTO + 2 Backend + Frontend + QA + Reviewer)
pr-review-corp — Auto-review every PR (Security + Performance + Style + QA)
migration-squad — JS→TS migration (CTO + 3 Migrators + QA + Reviewer)
security-dept — Multi-layer audit (Lead + Scanner + Secrets + Hunter + Reviewer)
test-factory — Coverage 40%→80% (Lead + 2 Backend + 3 QA + Reviewer)
bugfix-dept — 100 issues→0 (Triager + 3 Fixers + QA + Reviewer)
docs-team — Docs from code (Lead + 2 Writers + Editor + Reviewer)
content-agency — Content factory (Strategist + 2 Writers + Editor + SEO)
data-lab — CSVs→executive report (Lead Analyst + Data Engineer)
sales-machine — Outbound pipeline (Director + 2 SDRs + Copywriter + Growth)

Inter-Agent Communication

bash

# Messages
orch msg send <to-agent-id> "<body>" [-s <subject>] [--from <id>] [--ttl <ms>]
orch msg broadcast "<body>" [-s <subject>] [--team <team-id>]
orch msg inbox <agent-id>          # Pending messages
orch msg list [--agent <id>]       # All messages

# Shared Context
orch context set <key> <value> [--ttl <ms>]
orch context get <key>
orch context list
orch context delete <key>

Configuration

bash

orch config get <key>              # Get config value (dot notation)
orch config set <key> <value>      # Set config value
orch config edit                   # Edit config.yml in $EDITOR

# Global settings (~/.orchestry/global.yml)
orch config global get <key>
orch config global set <key> <value>
orch config global show

Logs

bash

orch logs [run-id]                 # View run logs
  --agent <agent-id>               # Filter by agent
  --task <task-id>                 # Filter by task
  --follow                         # Live stream
  --since <duration>               # Time filter (5m, 1h, 1d)

Common Workflows

"Set up a team to work on my project"

orch init (if needed)
orch org deploy startup-mvp --goal "Build feature X" OR manually create agents
orch tui or orch run --watch to start

"Add a task and run it"

orch task add "Fix login bug" -d "The login form crashes on empty email" --scope "src/auth/**" -p 1
orch run <task-id>

"Check what's happening"

orch status — overview
orch task list --status in_progress — running tasks
orch logs --follow — live output

"Deploy a review team for PRs"

orch org deploy pr-review-corp --goal "Review all open PRs"
Tasks are auto-created and assigned

"I want to refactor X across the codebase"

Create a goal: orch goal add "Refactor X" --description "..." --assignee <lead-agent>
Lead agent decomposes goal into tasks automatically
orch run --watch to execute

Key Concepts

Agents run in isolated git worktrees (no merge conflicts)
Tasks flow through: todo → in_progress → review → done
Goals are decomposed into tasks by a lead agent
Teams coordinate agents with a lead + members
Adapters: claude, opencode, codex, cursor, shell
All state stored in .orchestry/ (YAML/JSON, no database)
IDs are prefixed: tsk_, agt_, run_, goal_, team_, msg_

When to Use Goals vs Tasks

Use a Task when:

You know exactly what needs to be done — one concrete action
The scope is clear: fix a bug, write a test, update a file, review a PR
You can describe the result in one sentence
Examples: "Fix login crash on empty email", "Add unit tests for auth service", "Update README badges"

bash

orch task add "Fix login crash" -d "Empty email causes TypeError in validate()" --scope "src/auth/**" -p 1

Use a Goal when:

The objective is high-level and needs decomposition — you don't know all the steps upfront
Multiple tasks will be needed, potentially across different agents/skills
You want an agent to autonomously plan and execute the work
Examples: "Implement OAuth2", "Migrate from REST to GraphQL", "Improve test coverage to 80%"

bash

orch goal add "Implement OAuth2 with Google and GitHub" --description "Support social login, add tests, update docs" --assignee <lead-agent>

The assigned agent enters autonomous mode: it analyzes the codebase, creates tasks, assigns them to appropriate agents, and monitors progress until the goal is achieved.

Use a Goal for iterative improvement:

You have a measurable metric and want the agent to keep working until it's met
The agent runs cycles: measure → fix → measure again → repeat
Examples: "Get test coverage to 80%", "Zero TypeScript errors", "All /simplify reviews clean"

bash

orch goal add "Reach 80% test coverage" --description "Run coverage, find gaps, write tests, repeat until ≥80%" --assignee <qa-agent>

Choosing an assignee for a goal

A goal without --assignee stays unassigned and no agent picks it up automatically. Always assign a goal to an agent.

Before creating a goal, check available agents:

bash

orch agent list

Pick the agent whose role best matches the goal:

Code quality / testing → QA agent
Architecture / refactoring → CTO / architect agent
Documentation → CTO or dedicated docs agent
Feature work → relevant domain agent (backend, frontend, etc.)
Strategic / cross-cutting → CEO or lead agent

bash

# Example: assign docs update to CTO
orch goal add "Update docs for v2" --description "..." --assignee agt_T0uF5KP

If no suitable agent exists, create one first via orch agent add or orch agent shop.

Rule of thumb

1 agent, 1 action → Task
Multiple agents, unclear steps → Goal
Iterative loop until metric is met → Goal

Configuration Reference

yaml

# .orchestry/config.yml
project:
  name: "my-project"
defaults:
  agent:
    adapter: "claude"           # Default adapter
    approval_policy: "auto"     # auto|suggest|manual
    max_turns: 50               # Max LLM turns per run
    timeout_ms: 3600000         # 1 hour timeout
    stall_timeout_ms: 600000    # 10 min stall detection
    workspace_mode: "worktree"  # shared|worktree|isolated
  task:
    max_attempts: 3             # Max retries
    priority: 3                 # Default priority (1-4)
scheduling:
  poll_interval_ms: 10000       # Tick interval (10s)
  max_concurrent_agents: 6      # Parallel agent limit
  retry_base_delay_ms: 10000    # Retry backoff base
  retry_max_delay_ms: 300000    # Max retry delay (5min)

Creating Agents — Sources and Best Practices

Quick: Use Pre-Built Templates

bash

orch agent shop              # Interactive picker — 15 templates
orch agent shop --list       # Print all templates non-interactively
orch org deploy <template>   # Deploy a full team with one command

Agent Shop Templates (src/domain/agent-shop.ts)

Each template includes a detailed role prompt, model, skills, and approval policy:

Template	Role	Model	Skills
`backend-dev`	APIs, services, DB layers	claude-sonnet-4-6	feature-dev
`frontend-dev`	React UI, components, CSS	claude-sonnet-4-6	feature-dev, frontend-design
`qa-engineer`	Tests, coverage analysis	claude-sonnet-4-6	testing-suite
`code-reviewer`	PR review, bugs, security	claude-opus-4-6	feature-dev:code-reviewer
`architect`	System design, architecture	claude-opus-4-6	feature-dev:code-architect
`devops-engineer`	CI/CD, infrastructure	claude-sonnet-4-6	devops-automation
`bug-hunter`	Find bugs, reproduce, fix	claude-sonnet-4-6	feature-dev
`tech-writer`	Docs, READMEs, API docs	claude-sonnet-4-6	perfect-readme
`security-auditor`	Security scanning, vulns	claude-opus-4-6	testing-suite
`performance-engineer`	Optimization, profiling	claude-sonnet-4-6	testing-suite
`data-engineer`	Data pipelines, ETL	claude-sonnet-4-6	—
`fullstack-dev`	End-to-end development	claude-sonnet-4-6	feature-dev
`marketer`	Marketing strategy, copy	claude-sonnet-4-6	marketing-psychology
`content-creator`	Blog posts, social media	claude-sonnet-4-6	—
`growth-hacker`	Growth experiments	claude-sonnet-4-6	marketing-psychology

Show full SKILL.md (573 more words)Show less

Org Templates (src/domain/org-shop.ts)

Pre-built teams — deploy with orch org deploy <key> --goal "...":

Template	Agents	Use Case
`startup-mvp`	CTO + 2 Backend + Frontend + QA + Reviewer	Ship MVP fast
`pr-review-corp`	CTO + Security + Performance + Style + QA	Auto-review PRs
`migration-squad`	CTO + 3 Migrators + QA + Reviewer	JS→TS migration
`security-dept`	Lead + Scanner + Secrets + Hunter + Reviewer	Security audit
`test-factory`	Lead + 2 Backend + 3 QA + Reviewer	Coverage boost
`bugfix-dept`	Triager + 3 Fixers + QA + Reviewer	Issue backlog
`docs-team`	Lead + 2 Writers + Editor + Reviewer	Documentation
`content-agency`	Strategist + 2 Writers + Editor + SEO	Content
`data-lab`	Lead Analyst + Data Engineer	Data analysis
`sales-machine`	Director + 2 SDRs + Copywriter + Growth	Outbound

Custom Agents: Role Prompt Structure

When creating custom agents with orch agent add, follow this proven structure from the shop templates:

# [Role Name]

[One-line description of what this agent does]

## WORKFLOW
1) READ — understand the task scope
2) EXPLORE — analyze existing code/data with appropriate skills
3) PLAN — outline approach before executing
4) EXECUTE — do the work following conventions
5) VERIFY — self-review, run tests
6) REPORT — summarize what was done, flag risks

## RULES
- [Convention 1]
- [Convention 2]
- [Safety guardrail]

Skills Available for Agents

Assign skills via --skills flag or edit agent YAML. You can mix both types: --skills "review,feature-dev:code-explorer,investigate".

Library Skills (injected into system prompt — works with ALL adapters)

Content from the skill library is loaded and appended to the agent's system prompt at execution time. Use plain names (no colons):

Skill	Best For
`review`	Pre-landing code review with auto-fix, checklists, adversarial review
`qa`	Full QA testing + browser testing + bug fixing + health scoring
`qa-only`	QA testing without auto-fixes (report only)
`ship`	Automated ship workflow: merge, test, coverage audit, PR creation
`office-hours`	YC-style product thinking, design docs, premise challenge
`investigate`	Systematic debugging with root cause methodology, 3-strike hypothesis
`careful`	Safety guardrails for destructive commands
`guard`	Full safety mode (careful + freeze combined)
`freeze`	Restrict edits to a specific directory
`unfreeze`	Clear freeze boundary
`design-consultation`	Design system creation, visual language definition
`design-review`	Design review with accessibility, responsiveness checks
`plan-ceo-review`	CEO-level strategic review of plans
`plan-eng-review`	Engineering review of technical plans
`plan-design-review`	Design review of plans
`autoplan`	Auto-review pipeline with decision principles
`land-and-deploy`	Merge PR, wait for CI, verify production health
`canary`	Post-deploy canary monitoring
`document-release`	Auto-update documentation after ship
`retro`	Weekly engineering retrospective with trends
`browse`	Headless browser navigation and testing
`benchmark`	Performance benchmarking with before/after metrics
`codex`	OpenAI Codex cross-review / multi-AI challenge
`setup-deploy`	Configure deployment settings
`setup-browser-cookies`	Import browser cookies for authenticated QA
`upgrade`	Upgrade skills to latest version

Claude Code MCP Skills (native — Claude adapter only)

Handled natively by Claude CLI. Use package:skill-name format (with colon):

Skill	Best For
`feature-dev:feature-dev`	Guided feature development with architecture focus
`feature-dev:code-explorer`	Deep codebase analysis and tracing
`feature-dev:code-architect`	Architecture design and blueprints
`feature-dev:code-reviewer`	Code review with confidence filtering
`testing-suite:generate-tests`	Test generation with edge cases
`testing-suite:test-coverage`	Coverage analysis and gap identification
`testing-suite:e2e-setup`	End-to-end testing configuration
`testing-suite:test-quality-analyzer`	Test suite quality metrics
`devops-automation:cloud-architect`	Cloud infrastructure, Terraform
`frontend-design:frontend-design`	UI/UX design and implementation
`document-skills:frontend-design`	Frontend design (document-skills variant)
`product-manager-toolkit`	RICE prioritization, PRD templates
`marketing-psychology`	Behavioral science for marketing

Tips

Use claude-opus-4-6 for strategic/review roles (architect, reviewer, lead) — higher quality reasoning
Use claude-sonnet-4-6 for execution roles (developer, QA, writer) — faster, cheaper
Set --approval-policy suggest for strategic agents so humans review decisions
Set --approval-policy auto for execution agents for fully autonomous operation
Use --effort low|medium|high to control reasoning depth (Claude only) — low for simple tasks, medium for balanced, high for complex reasoning
Use --workspace-mode shared for analysis/strategy agents (they read, don't write code)
Use --workspace-mode worktree for coding agents (isolated branches, no conflicts)

Important Notes

Always run orch doctor first if something seems wrong
Use --json flag for programmatic parsing
orch serve --once is ideal for CI/CD pipelines
Stall timeout default is 10 minutes — increase for complex tasks via orch config set defaults.agent.stall_timeout_ms 1200000
If tasks are stuck after a crash, the orchestrator auto-cleans stale state on restart (v1.0.6+)

Files

Just SKILL.md in skills/orch of oxgeneral/ORCH.

Open the folder on GitHubat commit c066dc0

Compare with similar skills

Orch next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Orch compared with similar skills
Skill	Stars	Used in	Tokens	Auto-check	Licence	Repo updated
Orch this skilloxgeneral/ORCH	170	—	~5.2k	Automated safety check: Notes	MIT	2 mo ago
Orca CLIstablyai/orca	87k	2 repos	~593	Automated safety check: Pass	MIT	today
Paseo Advisor Second Opiniongetpaseo/paseo	20k	1 repos	~756	Automated safety check: Pass	Custom licence	today
O2 Review Loopopenobserve/openobserve	22k	—	~3.7k	Automated safety check: Pass	AGPL-3.0	today
Paseo Committeegetpaseo/paseo	20k	1 repos	~496	Automated safety check: Pass	Custom licence	today
Mission Control Agent APIbuilderz-labs/mission-control	6.3k	—	~2.1k	Automated safety check: Pass	MIT	10 days ago

Similar skills

Orca CLI
stablyai/orca
Operate Orca-managed worktrees, folder contexts, terminals, repos, automations, artifacts, skill sharing, worktree comments, and Orca's embedded browser…
87k GitHub starsUsed in 2 repos~593 tokens
Agent WorkflowsAuto-check passed
Paseo Advisor Second Opinion
getpaseo/paseo
Launches one separate agent through Paseo to give a second opinion on the current task, with a self-contained briefing and no permission to edit files.
20k GitHub starsUsed in 1 repo~756 tokens
Agent WorkflowsAuto-check passed
O2 Review Loop
openobserve/openobserve
Splits a change into planner, coder and independent reviewer roles: you confirm a spec, a subagent implements it, and a separate reviewer checks each round's local WIP commit.
22k GitHub stars~3.7k tokensUpdated today
Agent WorkflowsAuto-check passed
Paseo Committee
getpaseo/paseo
Forms a two-agent committee with contrasting profiles to analyze a stuck problem in parallel, reconcile their views and return a consensus plan without editing files.
20k GitHub starsUsed in 1 repo~496 tokens
Agent WorkflowsAuto-check passed
Mission Control Agent API
builderz-labs/mission-control
Teaches an agent to use the Mission Control dashboard API: register, send heartbeats, fetch assigned tasks, report progress and disconnect, with API key auth.
6.3k GitHub stars~2.1k tokensUpdated 10 days ago
Agent WorkflowsAuto-check passed
Paseo Agent Handoff
getpaseo/paseo
Hands off the current task, including context, decisions and failed attempts, to a fresh agent through Paseo by writing a self-contained briefing prompt and launching that agent.
20k GitHub starsUsed in 1 repo~606 tokens
Agent WorkflowsAuto-check passed

Questions about Orch

What does Orch do?

AI agent orchestrator — manage teams of AI agents that work on your codebase in parallel. Orch is an agent skill from oxgeneral/ORCH. AI agent orchestrator — manage teams of AI agents that work on your codebase in parallel.

When should I use Orch?

Orch fits situations like: the user wants to: run multiple agents; coordinate AI work; deploy agent teams; manage tasks/goals/agents.

How do I install Orch in Claude Code?

Run `npx skills add oxgeneral/ORCH --skill orch -a claude-code`. Or copy the skill folder (skills/orch in oxgeneral/ORCH) into .claude/skills/orch in your project. Claude Code loads it when a task matches its description.

How do I install Orch in Codex?

Run `npx skills add oxgeneral/ORCH --skill orch -a codex`. Or copy the skill folder (skills/orch in oxgeneral/ORCH) into .agents/skills/orch in your project. Codex loads it when a task matches its description.

Can I use Orch in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add oxgeneral/ORCH --skill orch -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/orch, .gemini/skills/orch, .github/skills/orch and .opencode/skills/orch in your project.

What does Orch need to run?

Going by SKILL.md and its folder, Orch needs the command-line tools its instructions call (opencode, codex and cursor). Its frontmatter pre-approves these tools: Bash, Read, Glob, Grep, Write, Edit, Agent.

Does Orch access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Orch safe to install?

Our automated static check of SKILL.md found notes only (pre-approves every shell command (allowed-tools: bash)), nothing it rates as a warning. It is not a guarantee. Review the folder before installing.

What licence does Orch use?

Orch is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Orch use?

About 5.2k tokens (SKILL.md is roughly 21k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Orch?

Skills that share tags, products or a category with Orch: Orca CLI (stablyai/orca, 87k stars), Paseo Advisor Second Opinion (getpaseo/paseo, 20k stars), O2 Review Loop (openobserve/openobserve, 22k stars) and Paseo Committee (getpaseo/paseo, 20k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Orch?

oxgeneral (a GitHub user) maintains it in oxgeneral/ORCH, which has 170 GitHub stars. The repository was last updated on August 1, 2026.

Source: oxgeneral/ORCH on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.

Install Orch

Facts

At a glance

What it does

When your agent uses it

Example prompts

Requirements

Workflow steps

What it can do on your machine

Tool permissions

Runs code

Network

Credentials

Context cost

Safety

SKILL.md

ORCH — AI Agent Orchestrator

How to Work

Quick Start Flow

Complete CLI Reference

Project Setup

Task Management

Agent Management

Execution

Goals (High-Level Objectives)

Teams

Pre-Built Organizations

Inter-Agent Communication

Configuration

Logs

Common Workflows

"Set up a team to work on my project"

"Add a task and run it"

"Check what's happening"

"Deploy a review team for PRs"

"I want to refactor X across the codebase"

Key Concepts

When to Use Goals vs Tasks

Use a Task when:

Use a Goal when:

Use a Goal for iterative improvement:

Choosing an assignee for a goal

Rule of thumb

Configuration Reference

Creating Agents — Sources and Best Practices

Quick: Use Pre-Built Templates

Agent Shop Templates (src/domain/agent-shop.ts)

Org Templates (src/domain/org-shop.ts)

Custom Agents: Role Prompt Structure

Skills Available for Agents

Library Skills (injected into system prompt — works with ALL adapters)

Claude Code MCP Skills (native — Claude adapter only)

Tips

Important Notes

Files

Compare with similar skills

Similar skills

Orca CLI

Paseo Advisor Second Opinion

O2 Review Loop

Paseo Committee

Mission Control Agent API

Paseo Agent Handoff

Related

Questions about Orch