Agent harness guide

A harness is the coding tool that runs the agent: Claude Code, Codex, GitHub Copilot, Cursor, OpenCode, or Pi. Each one looks for instructions and skills in its own folders. This page lists what Cratis puts in those folders, and how to install the native plugin when you only need one tool.

Cratis AI reaches a harness in one of two ways:

• Managed repository setup. cratis ai install resolves the repository’s profiles and languages, installs the shared corpus in .cratis/ai, and wires every selected harness to it. See Start using Cratis AI.
• Native plugin setup. You install one harness’s plugin or package without the Cratis CLI. You get no shared repository copy, no multi-harness wiring, and no protection for local edits on update.

Use the managed path when a team wants the same guidance across tools. Use a native plugin when one developer wants Cratis skills in one tool.

Managed harness support

cratis ai install \
  --harnesses claude,codex,copilot,cursor,opencode,pi \
  --profiles cratis/application/csharp \
  --languages csharp,typescript

The accepted harness values come from the corpus’s .cratis/ai/manifest.json. The CLI creates adapters only for the harnesses you select:

Harness	Managed project integration
Claude Code	CLAUDE.md, plus .claude rules, agents, commands, prompts, skills, and hook settings
OpenAI Codex	AGENTS.md and .agents/skills
GitHub Copilot	.github/copilot-instructions.md, plus .github instructions, agents, prompts, and skills
Cursor	.cursor rules, agents, commands, and skills
OpenCode	AGENTS.md, plus .opencode agents, commands, and skills
Pi	AGENTS.md, plus .pi extensions (rules loading, path guidance, Screenplay MCP, subagents, quality hooks), agents, prompts, and skills

Most adapters are symbolic links into .cratis/ai, so no harness gets its own diverging copy. AGENTS.md, CLAUDE.md, and .github/copilot-instructions.md are created only when you do not already have your own file at that path. Run cratis ai status to see local edits to managed files, and cratis ai uninstall to remove the integrations the CLI created.

The Screenplay profile also registers an MCP server

When a selected profile resolves to cratis/screenplay, the CLI also adds a managed screenplay MCP server entry (cratis screenplay mcp) to each harness’s MCP configuration, next to your own entries: .mcp.json (Claude Code), .vscode/mcp.json (Copilot), .cursor/mcp.json, .codex/config.toml and opencode.json. Pi reaches the same server through its managed cratis-mcp extension. To turn it off, set mcpServers.screenplay.enabled to false in .cratis/ai.json.

Your harness folders remain yours

The installer refuses to overwrite a file it did not install. You can add your own files next to the Cratis links in any harness folder. A folder that is itself a link, such as .claude/skills, points into .cratis/ai: anything you put there becomes part of the shared tree that every harness reads. --force only replaces or removes files already recorded as Cratis-managed.

Native plugins

The Claude Code, Codex, GitHub Copilot, and Cursor plugins come from the marketplace manifests in Cratis/AI. They carry the skills only, read from the repository’s current default branch, so there is no version to pin. Rules, prompts, agents, and hooks are not included; use the managed install for those.

Claude Code plugin

/plugin marketplace add Cratis/AI
/plugin install cratis@cratis

Remove it with /plugin uninstall cratis@cratis.

OpenAI Codex plugin

codex plugin marketplace add Cratis/AI
codex plugin add cratis@cratis

Remove it with codex plugin remove cratis@cratis.

GitHub Copilot plugin

These commands are for the GitHub Copilot CLI:

copilot plugin marketplace add Cratis/AI
copilot plugin install cratis@cratis

Cursor plugin

Add Cratis/AI in Cursor’s plugin settings. Cursor reads the committed .cursor-plugin/marketplace.json and installs the Cratis skills.

Pi package

@cratis/pi is published to npm and versioned per release, which makes it the one native channel you can pin.

# Project-scoped (written to .pi/settings.json)
pi install -l npm:@cratis/pi

# User-wide
pi install npm:@cratis/pi

# Pinned to an exact version
pi install -l npm:@cratis/pi@<version>

Pi treats a versioned npm source as pinned: pi update does not move it. Find the published versions with npm view @cratis/pi versions.

The package reads .cratis/ai.json when present and exposes the skills for the selected profiles and languages. Without that file, it exposes every packaged skill. Unlike the marketplace plugins, it also contributes rules, prompts, agents, a subagent tool, and Cratis quality hooks.

It does not create .cratis/ai, configure other harnesses, or protect local edits. When the repository already has a managed install (.cratis/ai.manifest.json exists), the package steps aside so the same rules and hooks are not registered twice.

OpenCode without the CLI

There is no Cratis OpenCode plugin or marketplace entry. OpenCode reads AGENTS.md and .opencode/agents, .opencode/commands, and .opencode/skills from the project, so to get Cratis content into OpenCode, use the managed install with --harnesses opencode. You can add your own content to those folders either way.