Start using Cratis AI

You want your coding agent to write Cratis code the way the framework expects: commands with Handle() on the record, model-bound projections, ConceptAs<T> instead of raw primitives. Cratis AI is the shared guidance that teaches it that. This page gets it into a repository and shows how to tell it worked.

The guidance comes in four kinds. Rules are standing instructions; some load for every file, others only for matching paths such as **/*.cs. Skills are focused task workflows the agent loads when a task matches. Prompts are slash commands such as new-vertical-slice, and agents are subagent definitions.

Pick a channel

You want	Use	What you get
One consistent setup for a repository, its team, and several coding tools	`cratis ai install` (this page)	Rules, skills, prompts, agents, and hooks, filtered by profile and committed to the repository
Cratis skills in one tool on your own machine	The tool’s native plugin	Skills only
Cratis guidance in Pi, pinned to a package version	`@cratis/pi`	Skills, rules, prompts, agents, and quality hooks

Cratis AI distribution explains how the three channels are versioned and why the CLI path is the only one that manages a shared repository copy.

Complete repository setup

Prerequisites: the Cratis CLI, and git with network access to GitHub. The CLI clones the current main branch of Cratis/AI on each install and update, unless you point it at a local checkout with --source.

From the repository root, preview what would be written:
Terminal window
```
cratis ai install --dry-run
```
In a terminal, the CLI asks you to pick harnesses (your coding tools), profiles, and languages. The choices come from the corpus’s own .cratis/ai/manifest.json, so they always match what is published.
Run the same command without --dry-run. In a script, CI, or an agent’s terminal there is no prompt, so pass the selection explicitly:
Terminal window
```
cratis ai install \
  --harnesses claude,codex,copilot,cursor,opencode,pi \
  --profiles cratis/application/csharp,cratis/documentation \
  --languages csharp,typescript
```
Choose Cratis AI profiles explains which profile fits your repository. Name your languages: rules scoped to C# or TypeScript files are installed only for the languages you list.
Check the result:
Terminal window
```
cratis ai status
```
It prints the selected profiles, harnesses, and languages, the corpus revision installed, and whether any managed file was changed locally.
Commit .cratis/ai.json, .cratis/ai.manifest.json, the .cratis/ai/ tree, and the harness adapters (AGENTS.md, CLAUDE.md, .claude/, .pi/ and so on). Everyone on the team and every CI run then reads the same guidance.

To confirm the agent actually sees it, start your coding tool from the repository root and ask it to list the Cratis skills or prompts it can use. The names start with cratis-, for example cratis-arc-command and cratis-chronicle-projection.

What the installer writes

The CLI copies the selected corpus into .cratis/ai/, records each installed file and its hash in .cratis/ai.manifest.json, and creates native adapters for each selected harness. Most adapters are symbolic links into .cratis/ai/, so every tool reads the same copy. The agent harness guide lists what each harness receives.

Pi is configured directly from the managed copy. The managed cratis-rules extension puts the universal rules from .cratis/ai/rules into the system prompt, and cratis-path-guidance attaches path-scoped rules and skill hints the first time a matching file is touched. You do not need the @cratis/pi package as well.

Put guidance that belongs to this repository alone in .cratis/ai/rules/project.md. When it covers several concerns, keep that file a short index and give each concern its own file:

.cratis/ai/rules/
├── project.md
└── project/
    ├── build-and-test.md
    ├── architecture.md
    ├── security.md
    └── deployment.md

project.md tells harnesses that read one context file to read every concern. Native rule adapters and Pi’s rules extension discover the concern files directly. The CLI creates AGENTS.md and CLAUDE.md as links to project.md when those paths are free.

If AGENTS.md or CLAUDE.md already exists as your own file, the CLI leaves it alone. Your existing file then does not mention the managed rules; add a line that tells the agent to read .cratis/ai/rules/project.md.

Moving from a legacy project file

The installer detects .cratis/PROJECT.md, .ai/PROJECT.md, and .agents/PROJECT.md. It copies their headings into project.md and one concern file per heading, without deleting the original. Review the split, remove the legacy file and anything that points to it, and run cratis ai update again so the shared adapters are created.

Maintain the installation

cratis ai status              # read-only; exits non-zero if a managed file was edited
cratis ai update --dry-run    # what an update would change
cratis ai update              # take the current corpus for the recorded selection
cratis ai uninstall           # remove unchanged Cratis-managed content and adapters

update re-reads .cratis/ai.json and takes whatever the corpus main branch holds now. There is no version pin on this channel. To change the selection, run install again with new options.

update and uninstall act only on files the manifest records as Cratis-managed. When one of those files was edited locally, both stop before changing anything and list the paths. Restore the file, or pass --force once you have decided the local edit can be replaced or removed.

Because status exits non-zero on local edits, you can run it in CI to catch drift in managed guidance. Updates and rollback covers previewing, pinning with --source, and going back.

Choose the integration that fits your repository

Managed by Cratis

Use cratis ai install when several people or several coding tools work in the repository, or when you want the guidance reviewed and committed like code. It is the only channel that installs rules for every harness, filters by profile, and protects local edits on update and uninstall.

Native plugin or marketplace

Use a native plugin when one developer wants Cratis skills in one tool without touching the repository. The Claude Code, Codex, GitHub Copilot, and Cursor marketplace plugins deliver the skills only, from the current Cratis/AI default branch. @cratis/pi also contributes rules, prompts, agents, a subagent tool, and quality hooks, and it is versioned on npm. Neither creates .cratis/ai, configures other harnesses, or protects local edits. The agent harness guide has the commands.

Contribute and verify skills

Skills are authored and reviewed in Cratis/AI. A skill can carry a verification.json with an example input and assertions that the skill contains the guidance that input needs. These checks are static: they do not run the input through a model, compile the skill’s examples, or judge its writing. Judging how an agent behaves with a skill still takes a real task and a review of the output.