Agent skill

The COMA skill teaches a coding agent how to work in a project whose containers run on a machine through COMA. It is a SKILL.md file in the open Agent Skills format, with three reference files the coding agent reads only when it needs them. Coding agents load it when a task mentions COMA, the project has a coma.yaml, or Docker behaves as if the engine is somewhere else.

The skill is instructions only: it has no scripts and makes no network calls. It does not install COMA; see Installation.

What it teachesCopy Anchor Link

• Before running containers, check docker context show and coma workspace status --json, and bring the workspace up when it is not.
• Add --json to every coma command, and branch on error.code and the exit code, never on the message.
• Never set DOCKER_HOST, DOCKER_CONTEXT or DOCKER_CONFIG, or start a local engine, to make a failing command pass. Run coma doctor --json and report what it says.
• Ask you before trusting a host key, bootstrapping a machine, confirming a mirror sync, or anything else that needs --host-key, --yes, --replace or --remote.
• For tools that ignore Docker contexts, run eval "$(coma endpoint env)" in the same command as the tool.
• After a task, read local-fallback in coma doctor --json and say so if anything ran on your laptop.

It also carries every error code with what to do about it, the coma.yaml rules, and the fixes from Troubleshooting.

Install for any coding agentCopy Anchor Link

npx skills add https://coma.sh

skills is an open-source installer, published on npm, that knows where dozens of coding agents keep their skills. Given https://coma.sh, it reads the site's discovery index, which lists the skill's archive and its SHA-256 digest, and asks which coding agents to install it for. Add -g to install it for all your projects instead of the current one, or -a claude-code (or codex, cursor, opencode) to choose without the question.

Install by handCopy Anchor Link

The skill is one archive with SKILL.md at its root. Unpack it into the directory your coding agent reads skills from:

mkdir -p ~/.claude/skills/coma
curl -fsSL https://coma.sh/skills/coma.tar.gz | tar -xzf - -C ~/.claude/skills/coma

Then start a new session, so the coding agent finds the skill.

Cursor and OpenCode also read ~/.claude/skills, so a copy there covers Claude Code, Cursor and OpenCode at once.

To give everyone on a project the skill, unpack it into the repository's .agents/skills/coma and .claude/skills/coma and commit both.

UpdateCopy Anchor Link

Run the same install command again. The skill's frontmatter records the COMA version its commands were checked against, in metadata.coma-version; the skill is updated with these docs, and every coma command and flag in it is checked against that version's CLI.

Read it firstCopy Anchor Link

The files are plain Markdown:

• SKILL.md: the rules and the everyday workflow.
• references/errors.md: every error code, its exit code and the action to take.
• references/coma-yaml.md: writing and fixing a coma.yaml.
• references/troubleshooting.md: common problems and their fixes.

For how coding agents run through COMA, and the pitfalls found while testing them, see Coding agents.