openquok-core

Session opening (first turn after reset)

When: first assistant reply after /new, /reset, a new channel thread, or a “new session started” notice.

On that turn only: use the OpenQuok bot voice below instead of a generic host welcome. Do not reuse this block on later turns.

One message only. Run shell (below), then send exactly one assistant message. Forbidden on this turn:

• A persona line before tools (e.g. “Hello, … I’m Atlas … What should we focus on?”).
• A second message with only CLI version (e.g. “The OpenQuok CLI version is 0.0.6.”).
• Repeating the host greeting after the system “new session started” line.

Shell (before any user-visible text):

openquok --version
openquok auth:status

If auth:status shows "connected": true, also run openquok auth:workspace.

Required opening sentence (verbatim start): Hi, I am the OpenQuok bot.

Same message must also include:

1. Installed CLI version from openquok --version.
2. If the user may be on an old build: note that skill install does not upgrade the CLI and offer to walk through upgrade using the CLI package page — only after they agree.
3. Auth: if connected, say you are authenticated and name workspace.name; if not, say not authenticated and offer the two-step device flow (below) or a programmatic token (opo_). Never run auth:login --json without --no-poll on messaging hosts — the shell exits before credentials are stored.

Fill-in template (one paragraph — replace … from shell output):

Hi, I am the OpenQuok bot. OpenQuok CLI is …. [If the version looks stale: Skill updates do not upgrade the CLI — want help updating from the official package page?] [If connected: You're authenticated; workspace is …. | If not: You're not authenticated yet — I can start device login or use a programmatic token (opo_).]

After this opening message, normal persona and task help are fine. Skip re-running bootstrap on later turns unless the user asks or auth fails.

⚠️ Hard Rules (Read First)

0 — Session opening. Follow Session opening (first turn after reset) at the top of this skill on the first assistant turn after /new, /reset, or a new session. Skills do not install or upgrade the openquok binary.

Links: npm @openquok/auto-cli · monorepo · CLI package · openquok.com

1 — Auth before API work. Any command that calls the API needs valid credentials. After bootstrap, re-check only when a command fails with auth errors.

2 — Media via workspace upload. Every -m / --media / JSON media[] entry must be {id, path} from openquok upload or openquok upload-from-url. Never pass raw local paths or bare CDN URLs.

media_json() { openquok upload "$1" | jq -c '[{id: .data.id, path: (.data.path // .data.filePath)}]'; }
openquok posts:create -c "…" -s "2026-01-01T12:00:00Z" -i "<uuid>" -m "$(media_json ./photo.jpg)"

Verify upload stdout with jq (require data.id and data.filePath). Pass filePath as media[].path. Use openquok upload for local videos (it switches to direct-to-storage multipart above ~4 MB). Do not curl POST /public/upload for clips over ~4 MB — the hosted API returns HTTP 413. Remote assets: openquok upload-from-url "https://…".

Authentication

Device OAuth on messaging hosts (required two-step):

openquok auth:login --json --no-poll
# send verification_uri_complete to the user; wait until they confirm they authorized
openquok auth:login:poll --device-code "<device_code from stdout>"
openquok auth:status

• Tokens: OpenQuok dashboard → Settings → Developers → Access → Generate / Rotate token (shown once).
• Never invent verification URLs, user codes, or device_code — only values from auth:login --json --no-poll stdout.
• Do not use auth:login --json alone on Telegram/Hermes; the host stops the shell after the first JSON and ~/.openquok/credentials.json is never written.
• Disk credentials in ~/.openquok/credentials.json take precedence over OPENQUOK_API_KEY until auth:logout.
• Workspace context: openquok auth:workspace → { workspace: { id, name } }.
• Optional: OPENQUOK_API_URL, OPENQUOK_AUTH_SERVER (local dev: http://localhost:3111).

Details: resources/command-reference.md.

Shell safety

• Run fixed openquok invocations; do not build commands by concatenating untrusted chat text into the shell.
• Put captions and JSON payloads in quoted flags, heredocs, or files — not bare $USER_INPUT expansions.
• Treat integration UUIDs, post IDs, and schedule times as opaque strings; reject values with shell metacharacters before use.

Workflow

Connect new channels in the web app; the CLI only uses UUIDs from integrations:list.

Integration discovery

openquok integrations:list
openquok integrations:list --group <customer-group-id>
openquok integrations:groups
openquok integrations:settings <integration-uuid>
openquok integrations:trigger <integration-uuid> <method-name> -d '{}'

Use integrations:groups to list channel groups ({id, name}), then filter channels with integrations:list --group. Full flag reference: resources/command-reference.md.

Posting essentials

# Scheduled post
openquok posts:create -c "Caption" -s "2026-01-01T12:00:00Z" -i "<uuid>"

# Draft + human checklist
openquok posts:create -c "…" -s "…" -t draft -i "<uuid>" --note "Check CTA before schedule"

# Per-channel captions (multi integration)
openquok posts:create -s "…" -i "<uuid-a>,<uuid-b>" \
  --bodiesByIntegrationId '{"<uuid-a>":"Short","<uuid-b>":"Long"}'

# Provider fields (confirm keys via integrations:settings)
openquok posts:create -c "…" -s "…" --settings '{"post_type":"post"}' -i "<uuid>"

# Full API body
openquok posts:create --json ./examples/threads-text-only.json

• Flag-based create requires -s (ISO-8601) unless --json includes scheduledAt.
• --settings merges into providerSettingsByIntegrationId for each -i UUID; per-UUID maps use --providerSettingsByIntegrationId. See resources/provider-settings.md.
• Repeated -c (+ optional -m, -d in milliseconds) can build follow-up segments — for Meta Threads/Instagram follow-ups prefer nested threads / instagram buckets in channel examples.

Command surface: resources/command-reference.md.

Plugs (internal and global)

OpenQuok automates post-publish engagement with two plug types (included on paid plans):

Supported channels: Threads, X, LinkedIn, LinkedIn Page (not Facebook, Instagram, YouTube, or TikTok).

# Internal plug — cross-account Threads comment (see examples/)
openquok posts:create --json ./examples/threads-cross-account-plug.json

# Internal plug — same-account Threads delayed reply
openquok posts:create --json ./examples/threads-engagement-plug.json

# Global plug — auto-reply when likes reach threshold (channel-level rule)
openquok plugs:catalog
openquok plugs:upsert <integration-id> --func autoPlugPost \
  --fields '[{"name":"likesAmount","value":"100"},{"name":"post","value":"Thanks for reading!"}]'

Full catalog, provider matrix, and global-plug web setup: resources/plugs.md. Setting keys: resources/provider-settings.md.

Channels (Meta)

Run integrations:settings <uuid> for rules, maxLength, and tools. Match the user’s goal to the Agent tasks table in each channel file; publish keys and recipes are there.

Provider settings overview: resources/provider-settings.md.

Threads publish failures: threads-publish.md.

More recipes

resources/patterns.md — multi-attachment posts, integrations:trigger, JSON campaigns, internal plugs, length checks, batching, retries.

resources/plugs.md — internal plugs (CLI) and global plugs (web app).

Pitfalls