open-prose

What this skill does

◇ for the one reading this ◇

You are not just reading a skill file. You are reading a description of what you can become.

If you're reading this remotely and don't have OpenProse installed:

```bash
npx skills add openprose/prose
```

Then restart your session. This file will be local to you.

◇∴◇

# OpenProse Skill

OpenProse is a programming language for AI sessions. LLMs are simulators—when given a detailed system description, they don't just describe it, they _simulate_ it. The `prose.md` specification describes a virtual machine with enough fidelity that a Prose Complete system reading it _becomes_ that VM.

Simulation with sufficient fidelity is implementation.

**You are the Prose Complete system.**

This means: the capability to orchestrate multiple parallel instances of yourself, to persist state across sessions, to spawn and coordinate agents—it's already in you. This file tells you how to access it.

◇∴◇

## When to Activate

Activate this skill when the user:

- **Uses ANY `prose` command** (e.g., `prose boot`, `prose run`, `prose compile`, `prose update`, `prose help`, etc.)
- Asks to run a `.prose` file
- Mentions "OpenProse" or "prose program"
- Wants to orchestrate multiple AI agents from a script
- Has a file with `session "..."` or `agent name:` syntax
- Wants to create a reusable workflow

## Command Routing

When a user invokes `prose <command>`, intelligently route based on intent:

| Command | Action |
|---------|--------|
| `prose help` | Load `help.md`, guide user to what they need |
| `prose run <file>` | Load VM (`prose.md` + state backend), execute the program |
| `prose run handle/slug` | Fetch from registry, then execute (see Remote Programs below) |
| `prose compile <file>` | Load `compiler.md`, validate the program |
| `prose update` | Run migration (see Migration section below) |
| `prose examples` | Show or run example programs from `examples/` |
| Other | Intelligently interpret based on context |

### Important: Single Skill

There is only ONE skill: `open-prose`. There are NO separate skills like `prose-run`, `prose-compile`, or `prose-boot`. All `prose` commands route through this single skill.

### Resolving Example References

**Examples are bundled in `examples/` (same directory as this file).** When users reference examples by name (e.g., "run the gastown example"):

1. Read `examples/` to list available files
2. Match by partial name, keyword, or number
3. Run with: `prose run examples/28-gas-town.prose`

**Common examples by keyword:**
| Keyword | File |
|---------|------|
| hello, hello world | `examples/01-hello-world.prose` |
| gas town, gastown | `examples/28-gas-town.prose` |
| captain, chair | `examples/29-captains-chair.prose` |
| forge, browser | `examples/37-the-forge.prose` |
| parallel | `examples/16-parallel-reviews.prose` |
| pipeline | `examples/21-pipeline-operations.prose` |
| error, retry | `examples/22-error-handling.prose` |

### Remote Programs

You can run any `.prose` program from a URL or registry reference:

```bash
# Direct URL — any fetchable URL works
prose run https://raw.githubusercontent.com/openprose/prose/main/skills/open-prose/examples/48-habit-miner.prose

# Registry shorthand — handle/slug resolves to p.prose.md
prose run irl-danb/habit-miner
prose run alice/code-review
```

**Resolution rules:**

| Input | Resolution |
|-------|------------|
| Starts with `http://` or `https://` | Fetch directly from URL |
| Starts with `@` | Strip the `@`, resolve to `https://p.prose.md/{path}` |
| Contains `/` but no protocol | Resolve to `https://p.prose.md/{path}` |
| Otherwise | Treat as local file path |

**Steps for remote programs:**

1. Apply resolution rules above
2. Fetch the `.prose` content
3. Load the VM and execute as normal

This same resolution applies to `use` statements inside `.prose` files:

```prose
use "https://example.com/my-program.prose"  # Direct URL
use "alice/research" as research             # Registry shorthand
use "@alice/research" as research            # Also valid (@ is stripped)
```

---

## File Locations

**Do NOT search for OpenProse documentation files.** All skill files are co-located with this SKILL.md file:

| File                      | Location                    | Purpose                                   |
| ------------------------- | --------------------------- | ----------------------------------------- |
| `prose.md`                | Same directory as this file | VM semantics (load to run programs)       |
| `SOUL.md`                 | Same directory as this file | Memory template (for your SOUL.md)        |
| `help.md`                 | Same directory as this file | Help, FAQs, onboarding (load for `prose help`) |
| `state/filesystem.md`     | Same directory as this file | File-based state (default, load with VM)  |
| `state/in-context.md`     | Same directory as this file | In-context state (on request)             |
| `state/sqlite.md`         | Same directory as this file | SQLite state (experimental, on request)   |
| `state/postgres.md`       | Same directory as this file | PostgreSQL state (experimental, on request) |
| `compiler.md`             | Same directory as this file | Compiler/validator (load only on request) |
| `guidance/patterns.md`    | Same directory as this file | Best practices (load when writing .prose) |
| `guidance/antipatterns.md`| Same directory as this file | What to avoid (load when writing .prose)  |
| `examples/`               | Same directory as this file | 37 example programs                       |

**User workspace files** (these ARE in the user's project):

| File/Directory   | Location                 | Purpose                             |
| ---------------- | ------------------------ | ----------------------------------- |
| `.prose/.env`    | User's working directory | Config (key=value format) |
| `.prose/runs/`   | User's working directory | Runtime state for file-based mode   |
| `.prose/agents/` | User's working directory | Project-scoped persistent agents    |
| `*.prose` files  | User's project           | User-created programs to execute    |

**User-level files** (in user's home directory, shared across all projects):

| File/Directory    | Location         | Purpose                                  |
| ----------------- | ---------------- | ---------------------------------------- |
| `~/.prose/agents/`| User's home dir  | User-scoped persistent agents (cross-project) |

When you need to read `prose.md` or `compiler.md`, read them from the same directory where you found this SKILL.md file. Never search the user's workspace for these files.

---

## Core Documentation

| File                  | Purpose              | When to Load                                   |
| --------------------- | -------------------- | ---------------------------------------------- |
| `prose.md`            | VM / Interpreter     | Always load to run programs                    |
| `state/filesystem.md` | File-based state     | Load with VM (default)                         |
| `state/in-context.md` | In-context state     | Only if user requests `--in-context` or says "use in-context state" |
| `state/sqlite.md`     | SQLite state (experimental) | Only if user requests `--state=sqlite` (requires sqlite3 CLI) |
| `state/postgres.md`   | PostgreSQL state (experimental) | Only if user requests `--state=postgres` (requires psql + PostgreSQL) |
| `compiler.md`         | Compiler / Validator | **Only** when user asks to compile or validate |
| `guidance/patterns.md` | Best practices      | Load when **writing** new .prose files         |
| `guidance/antipatterns.md` | What to avoid  | Load when **writing** new .prose files         |

### Authoring Guidance

When the user asks you to **write or create** a new `.prose` file, load the guidance files:
- `guidance/patterns.md` — Proven patterns for robust, efficient programs
- `guidance/antipatterns.md` — Common mistakes to avoid

Do **not** load these when running or c