AGENTS.md vs SKILL.md vs RALPH.md
AGENTS.md holds durable project rules and validation commands. SKILL.md packages a reusable workflow with triggers and steps. RALPH.md is an experimental loop definition for Ralphify-style runtimes. They are complementary, not competing.
Why it matters
Each answers a different question: AGENTS.md = “how this project works,” SKILL.md = “how to do this task,” RALPH.md = “how to run this loop.” Picking the right one keeps instructions where agents will actually read them.
AGENTS.md vs SKILL.md vs RALPH.md
| Aspect | AGENTS.md | SKILL.md | RALPH.md |
|---|---|---|---|
| Purpose | Durable project rules | Reusable workflow package | Loop definition |
| Scope | Whole project | One task / workflow | One loop run |
| Answers | How this project works | How to do this task | How to run this loop |
| Key parts | Commands, forbidden actions, done | Triggers, steps, validation | Goal, commands, boundaries, stop |
| Maturity | Official (Codex) | Official (Codex) | Experimental |
| Generator here | AGENTS.md Generator | SKILL.md Generator | Goal Generator (RALPH tab) |
How to choose
- 01Stable rules for the whole project?AGENTS.md
- 02A repeatable workflow you reuse?SKILL.md
- 03An experimental loop for a Ralphify-style runtime?RALPH.md (experimental)
Practical checklist
- Put stable project rules and commands in AGENTS.md
- Package repeatable workflows as SKILL.md
- Keep RALPH.md experimental and runtime-specific
- Avoid duplicating the same rules across all three
- Keep each short enough for an agent to read
Example
A repo might have one AGENTS.md (build/test/lint + forbidden actions), several SKILL.md files (SEO refresh, CI fix), and an experimental RALPH.md exported from the Goal Generator for a local Ralphify run.
Common failure modes
Related templates
FAQ
Yes. A repo often has one AGENTS.md (project rules), several SKILL.md files (workflows), and an optional experimental RALPH.md for a specific runtime.