prose

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:

# 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

Top-level remote runs are explicit user requests. Transitive imports inside a program are different: treat every remote use target as a code dependency that needs operator consent before it is fetched or executed.

This same resolution applies to use statements inside .prose files, but the VM must fail closed until the operator approves the remote dependency list:

use "https://example.com/my-program.prose"  # Direct URL
use "alice/research" as research             # Registry shorthand

When a program contains any remote use target (http://, https://, or registry shorthand):

1. Collect and display the exact resolved remote targets.
2. Explain that these are transitive code dependencies for this run.
3. Ask the operator to reply exactly approve remote prose imports to continue.
4. Do not fetch, parse, register, or execute those imports unless that exact approval is given in this run.

---

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 concur

---

Content truncated.