Quick Start

1. Install

Homebrew (macOS/Linux)

brew install saero-ai/tap/xcaffold

Go install

go install github.com/saero-ai/xcaffold/cmd/xcaffold@latest

Scoop (Windows)

scoop bucket add saero-ai https://github.com/saero-ai/scoop-bucket.git
scoop install xcaffold

2. Initialize a project

mkdir my-project && cd my-project
xcaffold init --target claude

This creates a project.xcaf and a xcaf/ directory with starter resources — an agent, a skill, and a rule.

3. Review the generated files

xcaffold uses a directory-per-resource layout. Each resource is a separate .xcaf file:

xcaf/
  agents/
    xaff/
      agent.xcaf          # Agent definition
  skills/
    xcaffold/
      skill.xcaf          # Skill definition
      references/         # Skill reference files
  rules/
    xcaf-conventions/
      rule.xcaf           # Rule definition
project.xcaf              # Project metadata

Here is what a typical agent manifest looks like:

kind: agent
version: "1.0"
name: developer
description: Full-stack developer with testing discipline.
model: sonnet
tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
disallowed-tools:
  - WebFetch
skills:
  - tdd
rules:
  - typescript
---
You are a senior full-stack developer. Always run tests before
marking a task complete. Follow the project's coding conventions.

And a skill:

kind: skill
version: "1.0"
name: tdd
description: Test-driven development workflow.
allowed-tools:
  - Bash
  - Read
  - Write
  - Edit
---
Follow TDD: write the failing test first, then the minimal code
to pass, then refactor. Never skip the red step.

4. Compile to provider output

xcaffold apply

This compiles your xcaf/ manifests into Claude Code's native format under .claude/ — agents as markdown files, skills as directories, rules as markdown, hooks as JSON. A project.xcaf.state file tracks SHA-256 hashes for drift detection.

To target multiple providers at once:

xcaffold apply --target claude --target cursor --target gemini

5. Check for drift

xcaffold status

If someone manually edits a .claude/ file instead of going through xcaf/, xcaffold detects the drift and exits with code 1. This integrates cleanly into CI — see the Best Practices section for GitHub Actions workflows.

6. Validate without compiling

xcaffold validate

Checks schema correctness, cross-references (do referenced skills and rules exist?), and policy compliance — without writing any files.

Your xcaf/ directory is now the source of truth. Commit it to version control, add provider output directories (.claude/, .cursor/, etc.) to .gitignore, and run xcaffold apply in CI.