---
name: Ralph Hats
slug: ralph-hats
category: AI Engineering
description: Ralph Hats creates, inspects, validates, and improves Ralph hat collections for multi-hat agent workflows. Use it when making or refining .ralph/hats/*.yml files, debugging hat routing, explaining event topology, or tuning a Ralph run.
github: "https://github.com/mikeyobrien/ralph-orchestrator/tree/main/skills/ralph-hats"
language: Rust
stars: 3099
forks: 285
install: "npx degit https://github.com/mikeyobrien/ralph-orchestrator/tree/main/skills/ralph-hats ~/.claude/skills/ralph-hats"
installs_to: ~/.claude/skills/ralph-hats
source_path: skills/ralph-hats/SKILL.md
collection_size: 20
category_size: 2451
collection_url: "https://dirskills.com/collections/mikeyobrien/ralph-orchestrator"
added: 2026-08-17T07:09:06.417Z
last_synced: 2026-08-17T07:09:06.417Z
canonical_url: "https://dirskills.com/skills/ralph-hats"
---

# Ralph Hats

Ralph Hats creates, inspects, validates, and improves Ralph hat collections for multi-hat agent workflows. Use it when making or refining .ralph/hats/*.yml files, debugging hat routing, explaining event topology, or tuning a Ralph run.

**Install:**

```bash
npx degit https://github.com/mikeyobrien/ralph-orchestrator/tree/main/skills/ralph-hats ~/.claude/skills/ralph-hats
```

## README

# Ralph Hats

Use this skill to operate the full Ralph hat lifecycle for user-authored hat
collections.

## Use This Skill For

- Creating a new hat collection in `.ralph/hats/`
- Inspecting an existing hat collection and explaining its topology
- Validating trigger routing, event flow, and completion behavior
- Improving or refactoring hats for clearer roles and safer routing
- Recommending better orchestration patterns for a Ralph workflow

## Core Assumptions

- Core runtime config already lives in `ralph.yml` or another `-c` source.
- User-authored hats are stored separately and passed with `-H`.
- This skill operates public hat collections, not Ralph built-in presets.

## Workflow

1. If a hats file already exists, read it first and explain the current
   topology before proposing changes.
2. If creating a new workflow, write it to `.ralph/hats/<name>.yml`.
3. Keep the hats file focused on hats-only data. Leave runtime limits and other
   core config in the main config file.
4. Validate with `ralph hats validate`.
5. Visualize topology with `ralph hats graph` when the event flow is not
   trivial.
6. Use `ralph hats show <hat>` when you need to inspect one hat's effective
   configuration.
7. When the user wants stronger confidence, run a targeted `ralph run -c ... -H
   ... -p "..."` exercise or provide the exact test command.

## Guardrails

- Only use hats-file top-level keys that Ralph accepts today:
  `name`, `description`, `events`, `event_loop`, `hats`.
- In a hats file, `event_loop` is only for hats overlay keys such as
  `starting_event` and `completion_promise`.
- Never use `task.start` or `task.resume` as hat triggers. Ralph reserves those
  for coordination. Use semantic delegated events like `work.start`,
  `review.start`, or `research.start`.
- Each trigger must route to exactly one hat.
- Keep `description` populated on every hat.
- Prefer `events:` metadata when custom event names would otherwise be opaque.
- Do not write user workflows into `presets/` from this skill.

## Output Expectations

- When editing or creating hats, produce the file changes and the validation
  result.
- When only inspecting, produce a concise topology summary, the main risks, and
  concrete improvement options.

## Read These References When Needed

- For current hats schema and supported fields: `references/schema.md`
- For command recipes and validation workflow: `references/commands.md`
- For pattern and file examples: `references/examples.md`