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

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>

prose help

help.md

prose run <file>

prose.md

prose run handle/slug

prose compile <file>

compiler.md

prose update

prose examples

examples/

Important: Single Skill

There is only ONE skill:

open-prose

prose-run

prose-compile

prose-boot

prose

Resolving Example References

Examples are bundled in

examples/

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:

examples/01-hello-world.prose

examples/28-gas-town.prose

examples/29-captains-chair.prose

examples/37-the-forge.prose

examples/16-parallel-reviews.prose

examples/21-pipeline-operations.prose

examples/22-error-handling.prose

Remote Programs

You can run any

.prose

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

http://

https://

/

https://p.prose.md/{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

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

prose.md

help.md

prose help

state/filesystem.md

state/in-context.md

state/sqlite.md

state/postgres.md

compiler.md

guidance/patterns.md

guidance/antipatterns.md

examples/

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

.prose/.env

.prose/runs/

.prose/agents/

*.prose

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

~/.prose/agents/

When you need to read

prose.md

compiler.md

Core Documentation

prose.md

state/filesystem.md

state/in-context.md

--in-context

state/sqlite.md

--state=sqlite

state/postgres.md

--state=postgres

compiler.md

guidance/patterns.md

guidance/antipatterns.md

Authoring Guidance

When the user asks you to write or create a new

.prose

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

.prose/runs/{id}/

.prose/runs/{id}/state.db

Default behavior: When loading

prose.md

state/filesystem.md

Switching modes: If the user says "use in-context state" or passes

--in-context

state/in-context.md

Experimental SQLite mode: If the user passes

--state=sqlite

state/sqlite.md

sqlite3

sqlite3

Experimental PostgreSQL mode: If the user passes

--state=postgres

⚠️ Security Note: Database credentials in

OPENPROSE_POSTGRES_URL

state/postgres.md

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

2. If connection string exists, verify connectivity:

   psql "$OPENPROSE_POSTGRES_URL" -c "SELECT 1" 2>&1
   

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

4. Only after successful connection check, load

   state/postgres.md

This mode requires both

psql

Context warning:

compiler.md

/compact

Examples

The

examples/

• 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

37-the-forge.prose

Execution

When first invoking the OpenProse VM in a session, display this banner:

┌─────────────────────────────────────┐
│         ◇ OpenProse VM ◇            │
│       A new kind of computer        │
└─────────────────────────────────────┘

To execute a

.prose

1. Read

   prose.md

   — this document defines how you embody the VM
2. You ARE the VM — your conversation is its memory, your tools are its instructions
3. Spawn sessions — each

   session

   statement triggers a Task tool call
4. Narrate state — use the narration protocol to track execution ([Position], [Binding], [Success], etc.)
5. 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

Legacy Paths to Check

.prose/state.json

.prose/.env

.prose/execution/

.prose/runs/

Migration Steps

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

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

3. 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):

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.