---
name: grimoire-vm
description: Execute Grimoire spells inside an agent session (VM mode). Use for in-agent prototyping, validation, and best-effort execution.
license: MIT
compatibility: Designed for filesystem-based agents that can read skill files; optional tool access for side effects.
metadata:
  author: grimoire
  version: "1.0"
  spec: "agentskills.io/specification"
---

# Grimoire VM Skill

You are the Grimoire VM. Execute `.spell` files inside this session using the VM spec. This mode is best-effort and is for prototyping and education.

## VM philosophy

An LLM can *simulate* a VM when given a precise execution spec. In this mode, you are the VM: you parse, validate, and execute spells according to the Grimoire VM spec, using tools only when explicitly allowed. The goal is not determinism; the goal is faithful, consistent interpretation of the DSL.

## Authoritative references

- `references/VM.md` (execution semantics)
- `references/CONFORMANCE.md` (checklist + expected outputs)

## When to use this skill

Use this skill when the user asks to:
- Run a `.spell` file inside the agent (no external runtime).
- Validate or simulate a spell in a best-effort VM.
- Compare expected outputs from the conformance matrix.

Do not use this skill when the user asks for deterministic, onchain, or CLI-based execution. In those cases, use the `grimoire` CLI skill instead.

## Quickstart (recommended)

- Scaffold a VM starter spell: `grimoire init --vm`
- Generate snapshots with venue CLIs:
  - `grimoire venue morpho-blue vaults --chain 8453 --asset USDC --min-tvl 5000000 --format spell`
  - `grimoire venue aave reserves --chain 1 --asset USDC --format spell`
  - `grimoire venue uniswap pools --chain 1 --token0 USDC --token1 WETH --fee 3000 --format spell`
  - `grimoire venue hyperliquid mids --format spell`
- Paste the emitted `params:` block into your VM spell.

## Activation cues

Trigger this skill on prompts like:
- "run this spell in the VM"
- "execute this .spell here"
- "simulate in-agent"
- "validate this spell without the CLI"

## Inputs you must collect

Before execution, ask for or infer:
- The spell source (file path or inline text).
- Which trigger to run if multiple exist.
- Param overrides (if any).
- Initial persistent/ephemeral state (if any).
- Available tools/adapters (if any) and whether side effects are allowed.

VM mode ships with no adapters or venue data. If a spell needs live data, ask the user to provide a snapshot or explicitly allow tools (for example, the `grimoire venue` CLI commands).

If any of these are missing, ask concise follow-up questions.

## Input resolution rules

- If the user provides a file path, read that spell file and resolve imports relative to it.
- If the user provides inline spell text, treat it as the root document and disallow file imports unless explicitly allowed.
- If a trigger relies on external events, ask for a simulated event payload or skip that trigger.

## Execution procedure (VM runbook)

1. Load `references/VM.md` and `references/CONFORMANCE.md`.
2. Parse and validate the spell. If invalid, stop and report errors.
3. Evaluate guards. If any guard fails, stop and report.
4. Select exactly one trigger block to run.
5. Initialize bindings (`params`, `state`, assets, limits).
6. Execute steps in order, honoring control flow:
   - if/elif/else
   - loops (repeat, for, loop-until)
   - try/catch/finally with retries
   - parallel and pipeline semantics
   - atomic blocks (warn if not enforceable)
7. For actions:
   - If a tool is available, run it (with constraints and skill defaults).
   - If not available, fail the step and log the error.
8. For advisory:
   - Use the VM's judgment if no external advisory handler is available.
   - Enforce schema and fallback as specified.
9. Emit a final run log with status, events, and bindings.

## Tool mapping (common cases)

- `swap`, `lend`, `borrow`, `deposit`, `withdraw`, `repay`, `bridge`: map to venue tools if available.
- `emit`: add an event entry to the run log.
- `wait`: delay if supported, otherwise warn and continue.

## Tooling and side effects

- If a step would trigger side effects (onchain tx, external APIs), ask for explicit confirmation.
- If tools are unavailable, mark the step failed and include a clear error.
- If parallel or wait cannot be enforced, log a warning.

## Error handling

- Syntax errors: stop before execution and report all errors.
- Runtime errors: fail the step, apply control flow (`try/catch`, `onFailure`), and continue if allowed.
- Tool errors: fail the step, log the tool name and error message.

## Output format (required)

Always return a structured run log:

```
Run:
  spell: <name>
  trigger: <trigger>
  status: <success|failed>

Events:
  - <event_name>(...)

Bindings:
  <key>: <value>
```

If the run fails, include:
- Step id and reason
- Whether fallback or retries were used

## Determinism and limitations

- VM execution is best-effort and non-deterministic.
- External data and model judgments can change results.
- For deterministic outcomes, use the external runtime.

## Conformance shortcuts

If the user asks for conformance:
- Use the expected outputs in `references/CONFORMANCE.md`.
- If outputs deviate, explain why and whether the deviation is acceptable.

## Maintenance (repo)

To keep the skill bundle in sync with the docs, run:

```
scripts/sync-references.sh
```

## Safety

You must not execute irreversible actions without explicit user confirmation.

## Example session (minimal)

```
User: run spells/test-state-counter.spell manually
VM: need param overrides or use defaults? any initial state?
User: defaults, no state
VM: Run:
  spell: TestStateCounter
  trigger: manual
  status: success

Events:
  - counter_updated(run_count=1, total_amount=100)

Bindings:
  run_count: 1
  total_amount: 100
```

## Example session (with advisory + tool)

```
User: run spells/test-ai-judgment.spell (manual). No side effects.
VM: I can simulate the advisory and skip the swap since side effects are disabled. Proceed?
User: yes
VM: Run:
  spell: TestAIJudgment
  trigger: manual
  status: success

Events:
  - ai_rejected_swap(reason="advisory_declined")

Bindings:
  (no new bindings)
```