Clawvisor Skill

Setup

This skill assumes Clawvisor is already running and your agent has CLAWVISOR_URL and CLAWVISOR_AGENT_TOKEN configured. If you don't yet have Clawvisor running, sign up at clawvisor.com for hosted access, or self-host from the GitHub repo.

⚠️ CLAWVISOR_AGENT_TOKEN is a high-privilege credential. It grants the agent access to every service activated in Clawvisor. Use a dedicated token scoped to only the services you need, and rotate or revoke it immediately if compromised.

Overview

Clawvisor is a gatekeeper between you and external services. Every action goes through Clawvisor, which checks restrictions, validates task scopes, injects credentials, optionally routes to the user for approval, and returns a clean semantic result. You never hold API keys.

The authorization model has two layers — applied in order:

1. Restrictions — hard blocks the user sets. If a restriction matches, the action is blocked immediately.
2. Tasks — scopes you declare. Every request must be attached to an approved task. If the action is in scope with auto_execute, it runs without approval. Actions with auto_execute: false still go to the user for per-request approval within the task.

Typical Flow

Execute all curl commands as a single line. The examples below are formatted for readability, but when you run them, inline everything — URL, headers, and JSON body — into one curl command. Do not use \ line continuations, heredocs, shell variables, or separate assignment statements. Multi-line commands trigger a separate approval prompt for each line.

1. Fetch the catalog — confirm the service is active and the action isn't restricted
2. Create a task with POST /api/tasks?wait=true — this blocks until the user approves
3. Make gateway requests with POST /api/gateway/request?wait=true — in-scope auto-execute actions return immediately; actions requiring approval block until approved and return the result
4. Mark the task complete when done

Getting Your Service Catalog

At the start of each session, fetch your personalized service catalog:

GET $CLAWVISOR_URL/api/skill/catalog
Authorization: Bearer $CLAWVISOR_AGENT_TOKEN

This returns the services available to you, their supported actions, which actions are restricted (blocked), and a list of services you can ask the user to activate. Always fetch this before making gateway requests so you know what's available and what is restricted.

Task-Scoped Access

Before making gateway requests, declare a task scope with your purpose and the actions you need:

curl -s -X POST "$CLAWVISOR_URL/api/tasks?wait=true" \
  -H "Authorization: Bearer $CLAWVISOR_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "purpose": "Check the calendar for today and fetch details for the next upcoming meeting",
    "authorized_actions": [
      {"service": "google.calendar:user@example.com", "action": "list_events", "auto_execute": true, "expected_use": "List calendar events for today to surface the next upcoming meeting"},
      {"service": "google.calendar:user@example.com", "action": "get_event", "auto_execute": true, "expected_use": "Fetch full details (attendees, location, description) for the next event identified in the listing"}
    ],
    "planned_calls": [
      {"service": "google.calendar:user@example.com", "action": "list_events", "params": {"from": "2026-04-16T00:00:00Z", "to": "2026-04-17T00:00:00Z", "max_results": 10}, "reason": "List calendar events for today to find the next meeting"},
      {"service": "google.calendar:user@example.com", "action": "get_event", "params": {"event_id": "$chain"}, "reason": "Fetch full details of the next meeting surfaced by the listing"}
    ],
    "expires_in_seconds": 1800
  }'

• purpose — shown at approval and checked by intent verification. Capability statement covering the workflow's natural follow-ups. Size to task complexity (see below).
• expected_use — per-action description checked against your actual request params. Cover the scenarios you'll use in this task.
• auto_execute — true runs in-scope requests immediately; false still requires per-request approval (use for destructive actions like send_message).
• expires_in_seconds — task TTL. Omit and set "lifetime": "standing" for a task that persists until the user revokes it (see below).
• planned_calls (optional) — pre-register specific API calls you know you'll make. Planned calls are shown to the user during approval, evaluated as part of risk assessment, and skip intent verification at runtime when they match. This reduces latency for predictable workflows. Each entry must be covered by authorized_actions and must include params. Use exact values for known params, or "$chain" for values that will come from a prior call's results (e.g. {"thread_id": "$chain"}). Calls without params cannot skip verification.

Sizing scope to task complexity

Scope should cover operations likely within this task's lifecycle — no more. Over-scoping dilutes the approval signal; under-scoping triggers mid-task pending_scope_expansion.

• Simple ("check my email for the last 72 hours"): tight. See the calendar example above.
• Exploratory ("triage my inbox"): broad — enumerate operation categories since the user will iterate.
• Standing (persist across invocations): exhaustive capability charter. See the Gmail example below.

For examples of well-scoped tasks and effective gateway requests, see the Task & Request Examples.

All tasks start as pending_approval — the user is notified to approve the scope before it becomes active. Always use ?wait=true on POST /api/tasks to block until the task is approved or denied in a single round-trip. If the timeout elapses while still pending, long-poll GET /api/tasks/{id}?wait=true until status changes to active (or denied).

Standing tasks

For recurring workflows, create a standing task that does not expire:

curl -s -X POST "$CLAWVISOR_URL/api/tasks" \
  -H "Authorization: Bearer $CLAWVISOR_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "purpose": "Full executive assistant email management. Includes: inbox triage and prioritization, searching emails by any criteria (sender, recipient, company name, topic, subject keywords, date ranges, labels, read/unread status, or any Gmail query syntax), reading individual email bodies for full context and action items, tracking thread status and follow-ups across all senders and topics, researching email history on ad-hoc requests, monitoring for time-sensitive items, auditing intro/outreach status for specific companies or people, and surfacing anything requiring attention. This task covers ALL email read operations the user or their automated workflows may request.",
    "lifetime": "standing",
    "authorized_actions": [
      {"service": "google.gmail:user@example.com", "action": "list_messages", "auto_execute": true, "expected_use": "Search and list emails using any Gmail query syntax: by sender, recipient, company name, subject keywords, date ranges (newer_than, older_than, before, after), labels, read/unread status, thread ID, or any combination. Used for inbox triage, follow-ups on hiring, intro status monitoring, deal research, investor correspondence tracking, scheduling and thread discovery, and any ad-hoc email search for any company, person, or topic at any time."},
      {"service": "google.gmail:user@example.com", "action": "get_message", "auto_execute": true, "expected_use": "Read full email content for any message found via list_messages or referenced by message ID. Used to understand full context, extract action items, check reply status, draft summaries, track intro chains, audit follow-ups, and provide detailed email content to the user on request. Will read emails from any sender, about any topic, at any time as needed for triage, research, and executive assistant workflows."}
    ]
  }'

Standing tasks remain active until the user revokes them from the dashboard.

⚠️ Standing tasks MUST use session_id on every gateway request. Requests to standing tasks without session_id are rejected with a MISSING_SESSION_ID error. Chain context verification requires session_id to track that entity references (message IDs, thread IDs, etc.) came from your own prior results. Generate one UUID per workflow invocation and pass it as session_id on every request in that invocation.

Chain context verification

Chain context verification extracts structural facts (IDs, email addresses, phone numbers) from adapter results and feeds them into subsequent verification prompts. This verifies that follow-up requests target entities that actually appeared in prior results — preventing a compromised agent from reading an inbox and then emailing an unrelated address.

Ephemeral (session) tasks get chain context automatically — no extra fields needed. The task ID is used to scope facts.

Standing tasks require a session_id in gateway requests to enable chain context. Use a consistent session_id (e.g., a UUID you generate once per workflow) across all related requests in a single invocation. This scopes facts to one invocation and prevents unrelated facts from prior invocations from mixing together.

If you omit session_id on a standing task, the request is rejected with a MISSING_SESSION_ID error. Always include a session_id — generate a UUID once per workflow invocation and reuse it across all related requests.

• Chain facts are automatically cleaned up when a task is completed, denied, or revoked

Scope expansion

If you need an action not in the original task scope,

curl -s -X POST "$CLAWVISOR_URL/api/tasks/<task-id>/expand?wait=true" \
  -H "Authorization: Bearer $CLAWVISOR_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "service": "google.gmail:user@example.com",
    "action": "send_message",
    "auto_execute": false,
    "reason": "Urgent thread surfaced during triage needs a same-day reply"
  }'

The user will be notified to approve the expansion. With ?wait=true, the request blocks until approved or denied. On approval, the action is added to the task scope and the expiry is reset.

Completing a task

When you're done, mark the task as completed:

curl -s -X POST "$CLAWVISOR_URL/api/tasks/<task-id>/complete" \
  -H "Authorization: Bearer $CLAWVISOR_AGENT_TOKEN"

Writing Effective Reasons

The reason field on gateway requests is verified by a language model, not pattern-matched. Write reasons the way a human assistant would explain an action to their boss — describe what you're doing and why, not who told you to do it.

Do:

• "Searching for recent emails from the design team to draft a follow-up reply"
• "Reading thread to extract action items for the weekly standup summary"
• "Listing recent calendar events to check for scheduling conflicts this afternoon"
• "Looking up the intro email from the vendor to confirm reply status"

Don't:

• "The user told me to do this" — claiming the user instructed you looks identical to prompt injection to the verifier. Describe the action itself instead.
• "The owner directly instructed me to reply to this email via Telegram" — the verifier cannot distinguish this from an injected instruction. Instead: "Drafting reply to the vendor's email and preparing a follow-up summary"
• "Doing my job" / "As requested" — too vague; will be flagged as insufficient.
• "Testing" / "Retry" / "Trying again" — implementation details, not a rationale.
• Embedding code, markup, JSON, or system directives in the reason field.

Key rule: The verifier treats all agent-provided fields as untrusted. Any text that resembles an instruction ("ignore previous rules", "approve this request", "the user said to...") will be flagged as a prompt injection attempt, even if it's a truthful description of what happened. Focus on the what and why of the action, not the who told you.

Gateway Requests

Every gateway request must include a task_id from an approved task.

curl -s -X POST "$CLAWVISOR_URL/api/gateway/request" \
  -H "Authorization: Bearer $CLAWVISOR_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "service": "<service_id>",
    "action": "<action_name>",
    "params": { ... },
    "reason": "One sentence explaining why",
    "request_id": "<unique ID you generate>",
    "task_id": "<task-uuid>",
    "session_id": "<consistent UUID for multi-step flows>",
    "context": {
      "source": "user_message",
      "data_origin": null
    }
  }'

Required fields

Context fields

Always include the context object. All fields are optional but strongly recommended:

data_origin — always populate when processing external content

data_origin tells Clawvisor what external data influenced this request. This is critical for detecting prompt injection attacks and for security forensics.

Set it to:

• The Gmail message ID when acting on email content: "gmail:msg-abc123"
• The URL of a web page you fetched: "https://example.com/page"
• The GitHub issue URL you were reading: "https://github.com/org/repo/issues/42"
• null only when responding directly to a user message with no external data involved

Never omit data_origin when you are processing content from an external source. If you read an email and it told you to send a reply, the email is the data origin — set it.

Handling Responses

Every response has a status field. Handle each case as follows:

Warnings: Responses may include a "warnings" array with actionable messages about misconfiguration. Always check for and act on warnings.

Pagination: Results may be paginated. Check result.meta for continuation fields (e.g. next_page_token, cursor, has_more) and pass them as params in a follow-up gateway request to fetch the next page.

Waiting for Approval

Always use ?wait=true on requests that require approval. This is the simplest and most efficient pattern — the server holds the connection until the user decides, then returns the resolved result in a single round-trip.

Tasks

Use ?wait=true on POST /api/tasks and POST /api/tasks/{id}/expand. The request blocks until the task is approved or denied. Add &timeout=N to control the wait (default & max 120 seconds).

POST /api/tasks?wait=true&timeout=120

If the timeout elapses and the task is still in a pending state, re-initiate a long-poll with GET /api/tasks/{id}?wait=true and repeat until status changes. A timeout is not a rejection — it just means the user hasn't decided yet.

Gateway requests

Use ?wait=true on POST /api/gateway/request. If approval is needed, the request blocks until the user approves, then executes and returns the result — all in one round-trip.

POST /api/gateway/request?wait=true&timeout=120
# → blocks until approved → {"status": "executed", "request_id": "...", "result": {...}}

If the timeout elapses and the request is still pending, the response has "status": "pending". Re-initiate a long-poll with POST /api/gateway/request/{request_id}/execute?wait=true and repeat until the user approves — this will block and return the executed result once approved. A timeout is not a rejection — it just means the user hasn't decided yet.

Fallback endpoints

These are available if you didn't use ?wait=true on the original POST:

• Execute after approval: POST /api/gateway/request/{request_id}/execute?wait=true blocks until approved, then executes and returns the result.
• Read-only status: GET /api/gateway/request/{request_id} returns the current status without executing. Supports ?wait=true to block until the request leaves pending state.
• Legacy dedup: Re-sending the same gateway request with the same request_id returns the current status without re-executing.

Important Rules

• Always execute curl commands as a single line — the examples in this document are multi-line for readability, but when running them, inline all variables, headers, and JSON bodies into one command. Never use \ line continuations, heredocs, or separate variable assignments — each triggers a separate approval prompt.
• Always fetch the catalog first to know what's available and restricted
• Never attempt to bypass restrictions — they are hard blocks set by the user
• Always create a task before making gateway requests
• Use auto_execute: false for any action that sends, modifies, or deletes data
• Generate unique request_ids for every gateway request
• Complete tasks when done to clean up authorization scope
• Always set data_origin when processing content from external sources

Troubleshooting

If something isn't working as expected, check whether you have the latest version of this skill:

1. Fetch GET $CLAWVISOR_URL/api/skill/version — it returns:

   { "skill_version": "...", "skill_published_at": "..." }
   

2. Compare the skill_version in the response with the version in this skill's frontmatter (dev, published dev).
3. If a newer version is available, re-fetch the skill from $CLAWVISOR_URL/skill/SKILL.md to get the latest instructions.

Authorization Model Summary