Skills

A skill is a folder containing a SKILL.md file with structured instructions that an agent can load at runtime. Skills live in ~/.aws/cli-agent-orchestrator/skills/ and are managed via the CLI: cao skills add, cao skills remove, cao skills list.

When an agent needs a skill, it calls the load_skill(name) MCP tool. For Kiro CLI, skills are delivered natively via skill:// resources in the agent JSON. Kiro CLI and OpenCode CLI discover skills natively; other providers load them on demand through the MCP server.

✎

What's in a Skill

A folder with a SKILL.md file containing step-by-step instructions, constraints, and examples. The agent receives this content verbatim when it loads the skill.

◈

How Agents Discover Them

Agents call load_skill(name) at runtime. The MCP server resolves the name to the skill folder, reads SKILL.md, and returns its content directly into the agent's context.

▶

Built-in Skills

CAO ships 11 built-in skills, including supervisor and worker protocols, memory usage, workflow authoring, session management, and agent routing. These cover the most common multi-agent patterns out of the box.

+

cao skills add ./my-custom-skill

Copies the skill folder into the skills directory, making it available to all agents immediately.

−

cao skills remove my-custom-skill

Removes the skill from the skills directory. Running agents that already loaded it are unaffected.

≡

cao skills list

Shows all installed skills with their names and descriptions.

Installing Agents

The cao install command takes a profile name, local path, or URL and sets it up for your provider automatically. No manual JSON editing or config wrangling required.

1

Install the profile

cao install code_supervisor — Resolves a built-in profile and writes a context file to agent-context/. Also accepts local paths (./my-agent.md) or URLs from an allowlisted host such as raw.githubusercontent.com.

2

Provider-specific setup happens automatically

For Kiro CLI, CAO writes the agent JSON with skill:// resources. For Claude Code and Codex, it writes a context file (no provider-specific config needed). You never touch provider configs directly.

3

Set secrets with cao env

cao env set ANTHROPIC_API_KEY sk-... — Stores the variable in ~/.aws/cli-agent-orchestrator/.env. Profiles reference them with ${VAR} syntax.

4

Verify the installation

cao profile list — Confirms the profile is registered and lists the name, source, and description. Use cao profile show <name> for the provider, role, and tool access.

terminal

# Install from built-in registry
cao install code_supervisor

# Install from a local file
cao install ./my-agent.md

# Install from URL with env var
cao install https://raw.githubusercontent.com/org/repo/main/agent.md \
  --env TEAM=platform

# Manage environment variables
cao env set ANTHROPIC_API_KEY sk-...
cao env list
cao env unset ANTHROPIC_API_KEY

What each command does

Downloads and registers the built-in code_supervisor profile

Installs a custom profile from a local markdown file

Fetches a remote profile and embeds the TEAM env var into it

Stores, lists, and removes environment variables used by profiles

⚡

Skills Compose with Profiles