mcpField
R
ralph-hats

ralph-hats

github.com/mikeyobrienAgent workflows3.2k57 installsUpdated 2w ago
Repository

About ralph-hats

ralph-hats is a skill for creating, inspecting, validating, and refining user-authored hat collections for Ralph workflows. It focuses on routing and event flow, with CLI commands for validation and topology visualization.

Key features

  1. 01Create and inspect hat collections
  2. 02Validate trigger routing and event flow
  3. 03Check completion behavior
  4. 04Refine roles and routing
  5. 05Validate with ralph hats validate
  6. 06Visualize topology with ralph hats graph

Use cases

  1. 01Building a new Ralph hat workflow
  2. 02Reviewing an existing collection's topology
  3. 03Finding routing or completion risks
  4. 04Improving workflow orchestration

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/mikeyobrien/ralph-orchestrator --skill ralph-hats

After installing, type/ralph-hatsin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

agents/
openai.yaml
references/
commands.md
examples.md
schema.md

Details

From the project 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

Comments

Markdown supported