Skills and Updates

How do you give an assistant the right guidance? Start with controllerai-start. Then load the skill for the task in hand, together with the references it points to. The eleven skills cover agent building, workflow construction, and verification. A skill guides the assistant’s work. It does not authorize an action, and it does not expand the account’s permissions.

This documentation targets CLI 0.2.24 and skill set 2026.09.15.4. Those labels do not establish compatibility with one released skill set. Check the installed versions yourself. The CLI executable, the skill files, the host plugin, and the hosted server each report their version separately.

Choose a skill for the next task

In the running example, Support helper answers policy questions from support-policy.md. Load the agent guidance for that work. Add the workflow guidance when the helper needs a Support desk workflow to record an escalation.

Skill	Read it when you need to…	Example step
controllerai-start	Choose the deliverable and next skill.	Decide whether Support helper needs an agent, a workflow, or both.
controllerai-agents	Write instructions, add files and tools, test, or publish an agent.	Give Support helper its policy file.
controllerai-integration-actions	Attach one existing app operation directly to an agent.	Add a discovered support-channel notification action.
controllerai-workflows	Create, inspect, validate, restore, or publish a workflow.	Build Support desk.
controllerai-node-config	Discover and configure a node’s component, properties, and connection.	Configure the escalation step.
controllerai-expressions	Bind inputs, calculate values, or debug a resolved value.	Pass the ticket ID into a node.
controllerai-flow-control	Branch, loop, call a subflow, or handle an error.	Route a ticket with missing information.
controllerai-data	Define schemas and read, write, or import records.	Store ticket T-104.
controllerai-ai-nodes	Configure Ask AI or a workflow action that talks to an agent.	Summarize the ticket before escalation.
controllerai-triggers	Capture, map, test, or enable a schedule or event source.	Start processing when a ticket arrives.
controllerai-runs	Test a flow or inspect inputs, outputs, skips, and warnings.	Check the saved ticket and execution result.

Read one skill’s instructions before you act. Then open the referenced file that answers the question in front of you. Agent release work points to references/instructions-and-versioning.md. Mapping CLI commands to remote tools points to controllerai-start/references/mcp-tool-map.md.

Use the guidance for your operating path

The canonical sources produce separate CLI, MCP, and hosted-builder copies. A CLI copy includes terminal procedures. An MCP copy uses typed tools and inline inputs. A hosted copy carries the in-product builder’s restrictions. All three come from the same authored skill tree, with content selected for each operating path.

Choose the copy that belongs to the assistant doing the work. A locally installed skill does not create an MCP connection. Remote guides do not install files on your machine. For account access and the builder’s handoffs, read Assistant security.

Repair the installation doctor identifies

In the Controller AI app, open Connect for setup. A plugin update belongs to the host that owns the plugin. A CLI-managed skill copy uses the local maintenance commands below. None of those commands select or change a workflow.

With a terminal assistant, read back the installation and the setup actions it plans:

cai agent setup --status --json
cai skills status --json
cai doctor --json

If doctor identifies an outdated Claude Code plugin, run:

claude plugin update controllerai

For other hosts, follow the host’s setup guide. Setup status reports a plan without applying it. Read its detected hosts and next steps before you change an installation. For CLI-managed copies, choose between these two commands:

cai skills install --json
cai skills update --json

install uses the verified set bundled with the installed CLI. update fetches the hosted skills feed and verifies its file sizes and SHA-256 digests before installing it. Both default to --target auto.

Automatic selection detects existing Codex, Claude, Cursor, and Copilot home directories. If none exists, it uses ~/.agents/skills. An explicit --target selects one destination. --target all selects every personal destination.

Target	Installation directory	Use it for
codex	$CODEX_HOME/skills, otherwise ~/.codex/skills	A CLI-managed Codex copy.
claude	~/.claude/skills	A CLI-managed Claude copy.
cursor	~/.cursor/skills	A CLI-managed Cursor copy.
copilot	~/.copilot/skills	A CLI-managed Copilot copy.
agents	~/.agents/skills	The shared personal location.
project	<project>/.agents/skills	One project; choose its root with --project-dir.

To update one project’s copy and then read its status, run both commands from that project directory:

cai skills update --target project --project-dir . --json
cai skills status --target project --project-dir . --json

A managed copy can be replaced even when it is modified or incomplete. Install and update overwrite it without --force, so move local edits out first. Installation removes its temporary backup unless cleanup fails. If a backup is left behind, read the cleanup warnings. --force permits replacing an unmanaged folder, and a managed copy does not need it.

Check versions and retained copies

skills status reports paths, versions, digests, and a status for each selected skill. Its default target is all, and it compares against the bundled manifest of the installed CLI. An intact copy that is newer than the bundle also reports current, so a newer working label can appear in the result. To compare against the hosted feed, and to see separate server and plugin reports, use doctor.

Before you repair a copy, read the reason beside missing, unmanaged, incomplete, modified, stale, or invalid. Those statuses distinguish absent files, unmanaged folders, changed content, and version or marker problems.

If the hosted feed fails with a network or HTTP error, update keeps the complete, intact managed sets that are current or newer than the bundle. Where it cannot keep one, it installs the bundled copy, and it reports updated and retained rows separately. An integrity failure or an incompatible CLI version fails instead of taking that fallback.

Updating skills does not replace the CLI executable. cai upgrade updates skills and prints the installation command for the executable; see Use the CLI. The in-product builder uses its bundled set. If it meets a runtime problem, it must report that instead of updating itself.

When diagnosing an update, keep each version attached to the component that reported it:

Component	What the report compares	What to do next
CLI executable	Installed package version against the hosted feed, with the MCP CLI stamp as a fallback.	Follow the executable update command.
Local skills	Installed versions and integrity against the bundle and available hosted feed.	Update the affected target, then inspect it again.
MCP server and catalog	Versions reported by the remote health response.	Keep these separate from your local installation.
Detected Claude plugin	Installed and latest plugin versions when the host reports both.	Follow the host’s plugin update path.

A reported server version is an observation, not a comparison that proves it is current. An unavailable feed cannot establish freshness. Keep the reported source and version together in a troubleshooting handoff, so the next assistant can tell which component still needs attention.

Fetch guides without local files

For an MCP assistant, call guide_list with {} to see guide names, versions, and digests. Then call guide_get with the exact name you selected:

{"name":"controllerai-agents"}

The response includes instructions, skillSetVersion, sha256, and the referenced Markdown files with their own content and digests. Both tools read the server’s bundled guidance. Neither modifies account resources. As you build Support helper, use the MCP tool reference for exact operation contracts.