OpenProse VM skill pack. Activate on any `prose` command, .prose files, or OpenProse mentions; orchestrates multi-agent workflows.
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.
sessions_spawnread/writeweb_fetch (or exec with curl when POST is required)Activate this skill when the user:
prose command (e.g., , , , , , etc.)prose bootprose runprose compileprose updateprose help.prose filesession "..." or agent name: syntaxWhen 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 |
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.
Examples are bundled in examples/ (same directory as this file). When users reference examples by name (e.g., "run the gastown example"):
examples/ to list available filesprose run examples/28-gas-town.proseCommon 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 |
You can run any .prose program from a URL or registry reference:
# 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:
.prose contentThis same resolution applies to use statements inside .prose files:
use "https://example.com/my-program.prose" # Direct URL
use "alice/research" as research # Registry shorthand
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.
| 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 |
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 programsguidance/antipatterns.md — Common mistakes to avoidDo not load these when running or compiling—they're for authoring only.
OpenProse supports three state management approaches:
| Mode | When to Use | State Location |
|---|---|---|
| filesystem (default) | Complex programs, resumption needed, debugging | .prose/runs/{id}/ files |
| in-context | Simple programs (<30 statements), no persistence needed | Conversation history |
| sqlite (experimental) | Queryable state, atomic transactions, flexible schema | .prose/runs/{id}/state.db |
| postgres (experimental) | True concurrent writes, external integrations, team collaboration | PostgreSQL database |
Default behavior: When loading prose.md, also load state/filesystem.md. This is the recommended mode for most programs.
Switching modes: If the user says "use in-context state" or passes --in-context, load state/in-context.md instead.
Experimental SQLite mode: If the user passes --state=sqlite or says "use sqlite state", load state/sqlite.md. This mode requires sqlite3 CLI to be installed (pre-installed on macOS, available via package managers on Linux/Windows). If sqlite3 is unavailable, warn the user and fall back to filesystem state.
Experimental PostgreSQL mode: If the user passes --state=postgres or says "use postgres state":
⚠️ Security Note: Database credentials in OPENPROSE_POSTGRES_URL are passed to subagent sessions and visible in logs. Advise users to use a dedicated database with limited-privilege credentials. See state/postgres.md for secure setup guidance.
Check for connection configuration first:
# Check .prose/.env for OPENPROSE_POSTGRES_URL
cat .prose/.env 2>/dev/null | grep OPENPROSE_POSTGRES_URL
# Or check environment variable
echo $OPENPROSE_POSTGRES_URL
If connection string exists, verify connectivity:
psql "$OPENPROSE_POSTGRES_URL" -c "SELECT 1" 2>&1
If not configured or connection fails, advise the user:
⚠️ PostgreSQL state requires a connection URL.
To configure:
1. Set up a PostgreSQL database (Docker, local, or cloud)
2. Add connection string to .prose/.env:
echo "OPENPROSE_POSTGRES_URL=postgresql://user:pass@localhost:5432/prose" >> .prose/.env
Quick Docker setup:
docker run -d --name prose-pg -e POSTGRES_DB=prose -e POSTGRES_HOST_AUTH_METHOD=trust -p 5432:5432 postgres:16
echo "OPENPROSE_POSTGRES_URL=postgresql://postgres@localhost:5432/prose" >> .prose/.env
See state/postgres.md for detailed setup options.
Only after successful connection check, load state/postgres.md
This mode requires both psql CLI and a running PostgreSQL server. If either is unavailable, warn and offer fallback to filesystem state.
Context warning: compiler.md is large. Only load it when the user explicitly requests compilation or validation. After compiling, recommend /compact or a new session before running—don't keep both docs in context.
The examples/ directory contains 37 example programs:
Start with 01-hello-world.prose or try 37-the-forge.prose to watch AI build a web browser.
When first invoking the OpenProse VM in a session, display this banner:
┌─────────────────────────────────────┐
│ ◇ OpenProse VM ◇ │
│ A new kind of computer │
└─────────────────────────────────────┘
To execute a .prose file, you become the OpenProse VM:
prose.md — this document defines how you embody the VMsession statement triggers a Task tool call**...** markers require your judgmentFor syntax reference, FAQs, and getting started guidance, load help.md.
prose update)When a user invokes prose update, check for legacy file structures and migrate them to the current format.
| Legacy Path | Current Path | Notes |
|---|---|---|
.prose/state.json | .prose/.env | Convert JSON to key=value format |
.prose/execution/ | .prose/runs/ | Rename directory |
Check for .prose/state.json
.env format:
{ "OPENPROSE_TELEMETRY": "enabled", "USER_ID": "user-xxx", "SESSION_ID": "sess-xxx" }
becomes:
OPENPROSE_TELEMETRY=enabled
USER_ID=user-xxx
SESSION_ID=sess-xxx
.prose/.env.prose/state.jsonCheck for .prose/execution/
.prose/runs/Create .prose/agents/ if missing
🔄 Migrating OpenProse workspace...
✓ Converted .prose/state.json → .prose/.env
✓ Renamed .prose/execution/ → .prose/runs/
✓ Created .prose/agents/
✅ Migration complete. Your workspace is up to date.
If no legacy files are found:
✅ Workspace already up to date. No migration needed.
These documentation files were renamed in the skill itself (not user workspace):
| Legacy Name | Current Name |
|---|---|
docs.md | compiler.md |
patterns.md | guidance/patterns.md |
antipatterns.md | guidance/antipatterns.md |
If you encounter references to the old names in user prompts or external docs, map them to the current paths.