ralph-hats

Create, validate, and improve Ralph hat collection YAML workflows.

3.1k|292|Updated Sep 7, 2025
One-click install
npx skills add https://github.com/mikeyobrien/ralph-orchestrator --skill ralph-hats
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: ralph-hats
Source: https://github.com/mikeyobrien/ralph-orchestrator/tree/main/skills/ralph-hats
Command: npx skills add https://github.com/mikeyobrien/ralph-orchestrator --skill ralph-hats

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

Designing multi-agent orchestration workflows in Ralph requires correctly wiring hat triggers, published events, and routing rules in YAML, where mistakes like reserved triggers or ambiguous routing break the run. This Skill guides the full lifecycle of authoring, inspecting, validating, and refining .ralph/hats/*.yml collections.

Core Features & Use Cases

  • Hat Collection Authoring: Create new workflow files under .ralph/hats/ with correct schema, semantic delegated events, and per-hat instructions.
  • Topology Inspection & Validation: Explain event flow with ralph hats graph, inspect single hats with ralph hats show, and catch routing errors with ralph hats validate.
  • Workflow Refactoring: Analyze an existing hats file, summarize risks, and propose minimal structural improvements.
  • Use Case: You want a planner-builder-reviewer pipeline for a coding task. The Skill writes the YAML with work.start as the starting event, validates routing, and renders a mermaid graph of the event flow.

Quick Start

Ask the assistant to create a Ralph hat collection in .ralph/hats/ for a plan-build-review workflow and validate it with ralph hats validate.

Frequently Asked Questions about ralph-hats

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I create a Ralph hat collection workflow?

Create a YAML file under `.ralph/hats/` defining an `event_loop` with a starting event and a `hats` map where each hat declares triggers, publishes, and instructions. Then validate it with `ralph hats validate -c ralph.yml -H .ralph/hats/<name>.yml`.

How do I validate and visualize Ralph hat routing?

Run `ralph hats validate` to catch reserved triggers, ambiguous routing, and orphan events. Use `ralph hats graph --format mermaid` or `--format ascii` to visualize the event topology, and `ralph hats show <hat>` to inspect one hat.

Why can't I use task.start as a hat trigger in Ralph?

Ralph reserves `task.start` and `task.resume` for coordinator coordination, so assigning them as hat triggers is rejected. Use a semantic delegated event like `work.start` or `review.start` and set it as `event_loop.starting_event`.

What fields can a Ralph hats YAML file contain?

Hats files support only the top-level keys `name`, `description`, `events`, `event_loop`, and `hats`. Runtime settings like `max_iterations` or `required_events` belong in the core `-c` config, not the hats overlay.

When should I use a review loop instead of a pipeline pattern?

Use a linear pipeline when work flows one way from planning to completion. Use a review loop with a closer hat that publishes either a follow-up event or the completion promise when the workflow needs iteration and rejection cycles.