Advanced

Format specs for everyone authoring against Ralphy — templates, skills, playbooks, schemas.

Specifications for everyone authoring against Ralphy. If you ship a new template, write a skill, draft a playbook, add a model entry, or read project memory from another tool, this section is your contract. Each page documents one format: the field-by-field schema, the lint that enforces it, and a full working example you can copy.

The rest of the docs cover how to use Ralphy. This section covers how to extend it.

Pages

Models registry

The MODELS.md format. Per-section conventions, the per-model matrix tables, lifecycle, and how to add a new entry.

Skill format

SKILL.md frontmatter contract, body sections, the 1536-char description cap, and the ralphy vs ralphy-dev namespace split.

Template format

template.yaml Zod schema, the five segment-persona categories, vibe-reference vs vibe-style, slug rules, and version gating.

Playbook format

docs/playbooks/<role>.md structure, sub-doc convention, routing into AGENTS.md, and the agents-md lint.

Memory schemas

The three JSONL logs under .ralphy/workspaces/<ws>/projects/<id>/logs/. Append-only contract, field-by-field schema, and read patterns.

Asset manifest

asset-manifest.json slot pointer table, slot-id convention, and how the auto-versioning archive interacts with manifest pointers.

How the specs interact

The Ralphy stack has one routing surface (AGENTS.md) and four format contracts that hang off it. Read them as a chain:

1. A request comes in. AGENTS.md routes it to a playbook (docs/playbooks/<role>.md). See Playbook format.
2. The playbook may invoke a skill. Skills live under .agents/skills/<name>/SKILL.md and are slash-invocable. See Skill format.
3. The skill or playbook picks a template. Templates live in the hosted content library (and your .ralphy/workspaces/<ws>/templates/) and declare a template.yaml. See Template format.
4. The template names model IDs. All available models are in MODELS.md. See Models registry.
5. Every generation writes to project memory. Append-only logs land in .ralphy/workspaces/<ws>/projects/<id>/logs/; per-slot pointers land in asset-manifest.json. See Memory schemas and Asset manifest.

If you change any one format, the others depend on it. The CI lints in scripts/lint-*.ts are the contract between layers — they’re the first thing to read when adding a field.

Working on the specs themselves

The source of truth for each spec lives in the repo:

Spec	Source files
Models registry	MODELS.md
Skill format	docs/skills-format.md, scripts/lint-skills.ts
Template format	cli/lib/schemas/template.ts, scripts/lint-templates.ts
Playbook format	docs/playbooks/README.md, scripts/lint-agents-md.ts
Memory schemas	cli/lib/gen-log.ts
Asset manifest	cli/commands/generate.ts (see Manifest type + readManifest / writeManifest)

When a doc page and the source disagree, the source wins. Open an issue or PR.

Related

• Concepts: templates — what a template is, before this page tells you the wire format.
• Concepts: playbooks & skills — the routing model, narrated.
• Templates gallery — every shipped template, browsable.
• Skills gallery — every built-in skill with trigger phrases.