Skip MCP Skill

Skip MCP — Project & Cloud Management

Overview

The Skip MCP server (mcp_skip_*) provides 39 tools to manage Skip Cloud projects end-to-end: discover projects, edit source files, run migrations, write server hooks, declare AI agents, inspect the database, configure email/OAuth/SMTP, manage secrets and env vars, view logs, and publish to production. Six built-in reference guides provide the canonical documentation for migrations, hooks, AI/agents, SDK, emails, and frontend patterns.

Architecture

Skip Cloud = embedded SQLite + PocketBase v0.36 + server hooks (goja JS VM) + hosted AI micro-agents. Every project has a frontend (React/Vite/Tailwind) and a backend (PocketBase). Schema changes go through migrations; runtime behavior goes through hooks. AI calls go through the $ai gateway (hook-only).

Tool Categories (39 tools)

1. Project Discovery & Lifecycle

• skip_org_list — list orgs with MCP access (id, name, slug)
• skip_project_list — list projects in an org (paginated); pass query for full-text search by name/slug/uid/description; pass orgId if multiple orgs
• skip_project_get — single project details (preview/production URLs, publish status, routes)
• skip_project_status — working-tree state: changed files, current version, deployed build info
• skip_project_apply_changes — commit + run QA pipeline (setup → static check → build → test → commit). The single finalize step after file edits.
• skip_project_publish — production build + deploy to public URL

2. File Operations

• skip_file_list — list file paths in project working tree
• skip_file_read — read a single text file's contents
• skip_file_write — create or overwrite a file (upsert). Edits working tree only — run skip_project_apply_changes after.
• skip_file_delete — remove a file from working tree. Run skip_project_apply_changes after.

3. Environment Variables

• skip_env_list — list env var keys (values never returned)
• skip_env_set — create or overwrite env vars (upsert). Changes take effect on next build/deploy.
• skip_env_delete — remove env vars by name

4. Database — Collections & Migrations

• skip_cloud_get_collections — list collections (id, name, type: base/auth/view)
• skip_cloud_get_collection_details — full definition: fields, access rules, indexes
• skip_cloud_list_migrations — migration list (id, version, name, status: applied/pending/failed)
• skip_cloud_rollback_migration — roll back to a target version (destructive)

5. AI Agents

• skip_cloud_list_agents — list hosted agents (slug, name, tier, description)
• skip_cloud_describe_agent — full agent state: system prompt, tools, memory sources, conversation count

6. Secrets

• skip_cloud_list_secrets — list secret keys (never values)
• skip_cloud_set_secret — create or update a secret (uppercase, starts with letter)
• skip_cloud_delete_secret — delete a secret by key

7. Email & SMTP

• skip_cloud_get_email_templates — read 4 templates (verification, passwordReset, confirmEmailChange, otp)
• skip_cloud_update_email_templates — create or update templates (subject + body HTML)
• skip_cloud_get_smtp_config — read SMTP config (custom vs shared relay, sender identity)
• skip_cloud_configure_smtp — update SMTP config (custom server or shared relay)

8. OAuth Providers

• skip_cloud_list_oauth_providers — list all 8 provider slots (google, microsoft, facebook, github, slack, custom1-3)
• skip_cloud_configure_oauth_provider — create/update a provider (clientId, clientSecret, scopes, OIDC endpoints for custom)
• skip_cloud_disable_oauth_provider — deactivate a provider (frees OIDC slot)

9. Backend URL & Logs

• skip_cloud_get_backend_url — PocketBase backend URL (distinct from frontend URL; exposed as VITE_POCKETBASE_URL)
• skip_cloud_list_logs — runtime logs (HTTP, hooks, emails), paginated, filterable by source/level

10. Reference Guides (6 guides)

• skip_cloud_migrations_guide — collections, fields, RLS, indexes, relations, seeding, vectors, agents in migrations
• skip_cloud_hooks_guide — event/route hooks, $app/$http/$filesystem/$vectors/$response, streaming, secrets, npm deps
• skip_cloud_ai_guide — $ai.chat, $ai.embed, $ai.agent(slug), streaming, frontend parsing, identity rules
• skip_cloud_agents_guide — $ai.agents.define/delete/putMemories/deleteMemories/putTools/deleteTools
• skip_cloud_sdk_guide — PocketBase JS SDK, auth, CRUD, real-time, pb.send, error handling
• skip_cloud_emails_guide — templates, placeholders, HTML policy, SMTP delivery, frontend triggers

Core Workflows

Edit & Deploy a Project

1. skip_project_list → find project ID
2. skip_file_read / skip_file_list → inspect current code
3. skip_file_write / skip_file_delete → make changes
4. skip_project_status → review pending changes
5. skip_project_apply_changes → commit + QA pipeline
6. skip_project_publish → deploy to production (optional)

Create a Migration

1. skip_cloud_list_migrations → find next free 4-digit ordinal
2. skip_cloud_get_collections / skip_cloud_get_collection_details → inspect existing schema
3. Write migration file via skip_file_write to pocketbase/migrations/NNNN_name.js
4. skip_project_apply_changes → applies migration automatically
5. Check skip_cloud_list_migrations for status (applied/failed)

Write a Hook

1. skip_cloud_get_collections → understand schema the hook will touch
2. Write hook file via skip_file_write to pocketbase/hooks/hook_name.js
3. skip_project_apply_changes → deploys hook
4. skip_cloud_list_logs → debug if needed

Declare an AI Agent

1. Write a migration with $ai.agents.define(app, {...}) — see references/agents-reference.md
2. skip_project_apply_changes → applies migration
3. skip_cloud_list_agents / skip_cloud_describe_agent → verify
4. Call from a hook via $ai.agent(slug).chat(...) — see references/ai-reference.md

Configure Email/OAuth/SMTP

1. Read current state (get templates / get SMTP config / list OAuth providers)
2. Read the relevant guide first (skip_cloud_emails_guide)
3. Apply changes (update templates / configure SMTP / configure OAuth provider)

Critical Rules

1. Always read the relevant guide before writing migrations/hooks/agent code. Guides are the canonical reference.
2. Migrations ≠ hooks. Migrations change schema (goja, no $http/$ai). Hooks change runtime behavior ($app, $http, $ai, $filesystem all available).
3. $ai. is hook-only.* Never call $ai.chat or $ai.agent inside a migration — raises SkipAiNotInMigrationError.
4. One route/hook per file. Hooks execute in a separate VM pool — top-level declarations are NOT accessible inside callbacks. All logic must be inline.
5. Routes use /backend/v1/ prefix. Never register under /api/ (reserved by PocketBase).
6. base collections MUST have created + updated autodate fields. Without them, sort/filter/SDK queries fail with HTTP 400.
7. VITE_POCKETBASE_URL is managed by Skip. Set it once via skip_env_set if missing; cannot be overwritten once it exists.
8. Secrets never hard-coded. Use $secrets.get('KEY') in hooks/migrations. Manage via skip_cloud_set_secret.
9. apply_changes is the finalize step. File writes/deletes only edit the working tree. Always run skip_project_apply_changes to commit and build.
10. Migration ordinals never reused. Check skip_cloud_list_migrations for the next free number. Schema migrations before seed migrations.

Additional Resources

Reference Files

• references/migrations-reference.md — Full migration reference: field types, RLS rules, indexes, relations, seeding, vectors, agents in migrations, checklist
• references/hooks-reference.md — Full hooks reference: event types, custom routes, $app/$http/$filesystem/$vectors/$response, streaming, secrets, npm deps, checklist
• references/ai-reference.md — Full $ai gateway reference: $ai.chat, $ai.embed, $ai.agent, streaming, frontend parsing, identity rules, error types
• references/agents-reference.md — Full agents reference: $ai.agents.define, field rules, tool execution modes, memory sources, incremental edits
• references/sdk-reference.md — Full frontend SDK reference: PocketBase client, CRUD, auth, real-time, pb.send, error handling
• references/tool-catalog.md — Complete catalog of all 39 MCP tools with parameter schemas

Guides (read on-demand via MCP tools)

The six guides are available as MCP tools that return full documentation text. Read them before complex operations:

• skip_cloud_migrations_guide — before writing any migration
• skip_cloud_hooks_guide — before writing any hook
• skip_cloud_ai_guide — before any $ai.chat / $ai.embed / $ai.agent usage
• skip_cloud_agents_guide — before declaring or editing an agent
• skip_cloud_sdk_guide — before writing frontend data-access code
• skip_cloud_emails_guide — before editing templates or SMTP config

Guides support partial reading: head (first N lines), tail (last N lines), start/end (line range), regexSearch (matching lines with context). Pass at most one mode.