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"):

• Read examples/ to list available files

• Match by partial name, keyword, or number

• 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:

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:

• Apply resolution rules above

• Fetch the .prose content

• Load the VM and execute as normal

This 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

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

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 compiling—they're for authoring only.

State Modes

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.

Examples

The examples/ directory contains 37 example programs:

• 01-08: Basics (hello world, research, code review, debugging)

• 09-12: Agents and skills

• 13-15: Variables and composition

• 16-19: Parallel execution

• 20-21: Loops and pipelines

• 22-23: Error handling

• 24-27: Advanced (choice, conditionals, blocks, interpolation)

• 28: Gas Town (multi-agent orchestration)

• 29-31: Captain's chair pattern (persistent orchestrator)

• 33-36: Production workflows (PR auto-fix, content pipeline, feature factory, bug hunter)

• 37: The Forge (build a browser from scratch)

Start with 01-hello-world.prose or try 37-the-forge.prose to watch AI build a web browser.

Execution

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:

• Read prose.md — this document defines how you embody the VM

• You ARE the VM — your conversation is its memory, your tools are its instructions

• Spawn sessions — each session statement triggers a Task tool call

• Narrate state — use the narration protocol to track execution ([Position], [Binding], [Success], etc.)

• Evaluate intelligently — ... markers require your judgment

Help & FAQs

For syntax reference, FAQs, and getting started guidance, load help.md .

Migration (prose update )

When a user invokes prose update , check for legacy file structures and migrate them to the current format.

Legacy Paths to Check

Legacy Path Current Path Notes

.prose/state.json

.prose/.env

Convert JSON to key=value format

.prose/execution/

.prose/runs/

Rename directory

Migration Steps

Check for .prose/state.json

• If exists, read the JSON content

• Convert to .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

• Write to .prose/.env

• Delete .prose/state.json

Check for .prose/execution/

• If exists, rename to .prose/runs/

• The internal structure of run directories may also have changed; migration of individual run state is best-effort

Create .prose/agents/ if missing

• This is a new directory for project-scoped persistent agents

Migration Output

🔄 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.

Skill File References (for maintainers)

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.