Resource Kinds
All xcaf resource kinds supported by the xcaffold compiler.
xcaffold compiles .xcaf manifest files into provider-native output directories. Each file declares exactly one resource using a kind: field that tells the compiler how to parse and render it.
Kinds fall into two categories:
Provider Kinds
These kinds compile directly into files inside the provider output directories (.claude/, .cursor/, .gemini/, .github/, .agents/). Each provider renders the resource in its native format.
| Kind | Compiles to | Description |
|---|---|---|
agent | agents/<id>.md per provider | Named AI persona with a system prompt, tools, and optional skill/rule bindings |
skill | skills/<id>/SKILL.md per provider | Reusable procedure invoked by agents on-demand |
rule | rules/<id>.md per provider | Constraint always active or scoped to specific file paths |
mcp | Provider-specific JSON config | Model Context Protocol server declaration |
workflow | workflows/<id>/WORKFLOW.md per provider | Multi-step scripted procedure |
context | CLAUDE.md, GEMINI.md, etc. | Workspace-level ambient context |
Xcaffold Kinds
These kinds govern the compiler itself — they configure compilation targets, enforce policies, and structure the project manifest. They produce no output files.
| Kind | Description |
|---|---|
project | Root manifest — declares targets and project metadata; resources discovered from xcaf/ directories |
policy | Compile-time constraint evaluated during apply and validate |
blueprint | Named resource subset for conditional compilation |
global | Shared resource definitions inherited across projects |
Resource File Format (One Kind Per File)
xcaffold enforces a single-kind-per-file layout. Each .xcaf file declares exactly one kind: field. Resources under xcaf/ are discovered automatically, parsed recursively, and merged prior to compilation. Unknown fields will cause an immediate parse error.
xcaffold leverages two distinct file formats depending on whether a structural resource requires a multi-line textual instruction block.
Body-Bearing Kinds (Frontmatter Format)
agent, skill, rule, and context embed their instruction body organically as Markdown appended after a standard YAML frontmatter block.
---
kind: agent
version: "1.0"
name: developer
model: claude-sonnet-4-6
---
You are a senior backend developer. Focus heavily on code-quality.The --- delimiters demarcate the boundaries of the frontmatter config. All characters after the closing --- comprise the instruction body (equivalent to the UI prompting box).
Data-Only Kinds (Pure YAML)
workflow, hooks, mcp, settings, policy, global, memory, and blueprint have no concept of open-ended instruction bodies. They use pure YAML format without --- delimiters.
project is also pure YAML. No --- delimiters are required or recommended.
kind: project
version: "1.0"
name: my-api
targets:
- claude