PocketBase

Build backends with PocketBase collections, auth, and realtime.

Security Scan

The skill is an instruction-only PocketBase SDK/reference guide that coherently requires the pocketbase binary and contains no unexplained credential or install requests.

Purpose & Capability

Name/description (PocketBase backend usage) matches the declared requirement: the pocketbase binary. No unrelated binaries, env vars, or config paths are requested.

Instruction Scope

SKILL.md is a focused SDK/how-to reference for collections, auth, realtime, uploads, hooks, and admin usage. It does not instruct reading unrelated files, exfiltrating environment variables, or sending data to unexpected endpoints.

Install Mechanism

No install spec is provided (instruction-only), which is low-risk. Nothing is downloaded or extracted by the skill itself.

Credentials

The skill requests no environment variables or credentials. It documents admin tokens and auth flows (expected for this topic) but does not request them in metadata.

Persistence & Privilege

always is false and there is no install step or configuration-write behavior. The agent may invoke the skill autonomously (platform default), but that is normal and not combined with other red flags.

Assessment

This is a documentation-style skill that expects a 'pocketbase' binary on PATH. Before installing, verify you trust the pocketbase binary on your system (official PocketBase release) because the agent could invoke that binary and it may start services or modify local state. The skill itself doesn't request credentials, but any workflows that use admin tokens or user credentials (described in the guide) must be handled securely — don't paste secrets into prompts or give long-lived admin tokens to an agent unless you intend it to perform admin operations. If you don't have or want a local pocketbase binary, the skill will be inert.

SDK Basics

• Import from pocketbase not pocketbase/dist — the dist path is internal and breaks on updates
• Always check pb.authStore.isValid before using pb.authStore.model — expired tokens return stale data without error
• After login, token is auto-attached to requests — no need to manually set Authorization headers

Fetching Records

• Use expand parameter to load relations: pb.collection('posts').getList(1, 20, { expand: 'author,comments' })
• Expanded records appear in record.expand.fieldName — not directly on the record object
• Filter syntax is SQL-like but uses single quotes: filter: "status = 'active' && created >= '2024-01-01'"
• Combine conditions with && and ||, not AND/OR — SQL keywords don't work

Authentication

• Users collection is users (lowercase) — _users or Users returns empty results
• authWithPassword(email, password) returns the full user record plus token
• OAuth flow: authWithOAuth2({ provider: 'google' }) opens popup automatically in browser
• Logout requires both pb.authStore.clear() and invalidating server-side if using tokens elsewhere

Realtime

• Subscribe with pb.collection('posts').subscribe('*', callback) — the '*' means all record changes
• Callback receives { action: 'create'|'update'|'delete', record } — check action before processing
• Always unsubscribe on cleanup: pb.collection('posts').unsubscribe() — orphan subscriptions leak memory

File Uploads

• Files require FormData, not JSON: formData.append('document', file) then pass to create()
• Get file URL with pb.files.getURL(record, record.filename) — don't construct URLs manually
• Multiple files to same field: append with same key multiple times

Collection Rules

• Empty rule = blocked for everyone, "" (empty string) rule = open to everyone — counterintuitive
• Use @request.auth.id to reference logged-in user, @request.data for submitted data
• Example restrict to owner: @request.auth.id = user.id in View/Update/Delete rules

Hooks (pb_hooks/)

• JavaScript hooks go in pb_hooks/*.pb.js — the .pb.js extension is required
• Hooks run synchronously and block the request — keep them fast or use routines
• Access app with $app, event data with e — common: e.record, e.httpContext

Admin API

• Admin endpoints need superuser auth, not regular user tokens
• Create admin token: pb.admins.authWithPassword(email, password)
• Admin operations use pb.admins or pb.collections, not pb.collection()