prose

What this skill does

# 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.**

## OpenClaw Runtime Mapping

- **Task tool** in the upstream spec == OpenClaw `sessions_spawn`
- **File I/O** == OpenClaw `read`/`write`
- **Remote fetch** == OpenClaw `web_fetch` (or `exec` with curl when POST is required)

## 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                |
| 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
```

---

## 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)            |
| `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