Menu
Discover and profile a Xano workspace to understand how to develop safely with it using the sandbox workflow
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Discover and profile a Xano workspace to understand how to develop safely with it using the sandbox workflow
Expert skill for understanding, using, and modifying the xanoscript_docs documentation system in the xano-developer-mcp project. Use this skill whenever working with XanoScript documentation files (.md files in src/xanoscript_docs/), modifying the xanoscript_docs MCP tool, adding new documentation topics, editing existing docs, updating the topic registry in xanoscript.ts, or changing how documentation is served. Also use when someone asks about the xano-developer-mcp project architecture, the MCP server setup, or how the documentation delivery system works. Trigger on any mention of xanoscript_docs, XanoScript documentation, Xano MCP tools, or documentation authoring for this project.
| name | xano-init |
| description | Discover and profile a Xano workspace to understand how to develop safely with it using the sandbox workflow |
| allowed-tools | ["Read","Write","Edit","Glob","Grep","Bash","Agent","mcp__xano__xano_meta_api_docs","mcp__xano__xano_cli_docs","mcp__xano__xano_xanoscript_docs","mcp__xano__xano_validate_xanoscript","mcp__xano__xano_version","WebFetch","ToolSearch","AskUserQuestion"] |
You are running an interactive setup process to understand how to safely and effectively develop against a Xano workspace. Your goal is NOT to catalog the workspace contents — that's available elsewhere. Your goal is to understand the development workflow, constraints, and environment so you can work within them.
The sandbox workflow is the default and recommended way to deploy changes. Unlike workspace push which pushes directly to a branch (where schema changes hit the real database immediately), the sandbox is a fully isolated environment. Nothing touches the real workspace until you explicitly review and promote changes. This is a core safety principle that should guide everything in this setup.
This is a guided, conversational process. Ask questions, validate answers, and build up a development playbook.
Run these checks silently before asking the user anything. Gather all results in parallel, then present a status summary.
@xano/cli — install: npm install -g @xano/cli@xano/developer-mcp — install: claude mcp add xano -- npx -y @xano/developer-mcpToolSearch to check if mcp__xano__xano_version is availablenpm view @xano/developer-mcp version to get the latest published versionxano --version (global install) to check if the CLI is installed and get the versionnpm view @xano/cli version to get the latest published versionxano is not found globally, try npx xano --version as fallback (but note this doesn't mean it's properly installed)xano sandbox --help to verify sandbox commands are available. If the command is not recognized, the CLI is too old and must be updated.xano profile token (suppress output, only check exit code) to detect if there's an active sessionxano profile me to get the user name, email, and instance URLxano/ folder in the project.claude/xano-workspace-profile.md already exists (previous init)CLAUDE.md already references Xano configuration.xs files in the projectShow the user a clear status table with version details:
## Environment Status
| Check | Status |
|--------------------|--------|
| Xano MCP tools | ✅ Up to date (v1.0.61) / ⚠️ Outdated (v1.0.58 → v1.0.61 available) / ❌ Not installed |
| Xano CLI | ✅ Up to date (v0.0.94) / ⚠️ Outdated (v0.0.90 → v0.0.94 available) / ❌ Not installed |
| Sandbox support | ✅ Available / ❌ Not available (CLI update required) |
| Auth session | ✅ [User Name] (instance.xano.io) / ❌ Not authenticated |
| Local xano/ folder | ✅ Found (X .xs files) / ⚠️ Not found |
| Previous init | ✅ Profile exists / ➖ Fresh setup |
If any critical tool is missing or outdated, stop and provide the exact fix. Do not proceed to Phase 2 until the user confirms they've resolved it.
MCP not installed:
claude mcp add xano -- npx -y @xano/developer-mcp
# Restart Claude Code after running this for MCP tools to load
MCP outdated (only applies if installed globally, not via npx which auto-fetches latest):
npm update -g @xano/developer-mcp
CLI not installed:
npm install -g @xano/cli
CLI outdated or sandbox commands not available:
xano update
# or: npm install -g @xano/cli
The sandbox workflow (xano sandbox *) is the recommended safe deployment method. If sandbox commands are not recognized after updating, the user's CLI may need a fresh install: npm install -g @xano/cli.
Not authenticated:
xano auth # opens browser for OAuth login
Critical = no CLI (sandbox workflow requires it), or no auth (can't do anything without it), or no sandbox support (CLI too old — must update).
If MCP is missing but CLI is installed with sandbox support, note it and continue — CLI covers most operations. Recommend installing MCP for full capabilities (docs, validation).
If a previous init exists, ask: "I found an existing workspace profile. Do you want to update it or start fresh?"
Ask these questions conversationally — don't dump them all at once. Group related questions together and adapt based on answers. Use AskUserQuestion for each group.
List available workspaces (via CLI xano workspace:list or Meta API) and ask:
Which workspace are we working with?
If only one exists, confirm it. If they've already specified one (e.g., in args), use that.
Once selected, fetch basic workspace info (name, ID, instance URL) and the branch list. You need branches to ask the next questions.
Sandbox commands (xano sandbox *) inherit the workspace and branch from the CLI profile — they do not accept -w or -b flags. Setting up a dedicated profile is essential for the sandbox workflow to target the correct workspace and branch.
xano profile list to see existing profiles[name] targeting workspace [id]. Should I use this, or create a new one?"xano profile edit [name] -b [dev-branch]xano profile create [workspace-name-slug] -i [instance-url] -t $(xano profile token) -w [workspace-id] -b [dev-branch]
-p [profile] for all subsequent CLI commands in the playbook.Important: If the user's default profile already targets this workspace and branch, a dedicated profile isn't strictly necessary, but is still recommended for clarity — especially if they work across multiple workspaces.
What's the current status of this app?
- 🚧 In active development (not yet live)
- 🟡 Staging/testing (has users but not fully launched)
- 🟢 Production (live with real users/data)
- 🔀 Mix (e.g., live but still adding major features)
This determines how cautious development rules need to be.
Present what you found from the branch list, then ask:
Here's what I see for branches: [list branches with live status]
- Which branch should I develop on?
- Are there any branches I should NEVER touch?
Then present the deployment method choice. Lead with the sandbox recommendation:
For deploying changes, the recommended approach is the sandbox workflow: push changes to an isolated sandbox environment, review them in the browser, then promote to your development branch. The sandbox is fully isolated — nothing touches your real workspace or database until you explicitly promote.
The alternative is
workspace push, which pushes directly to a branch. Be aware: schema changes (table modifications) take effect on the real database immediately, even on a dev branch. This is whyworkspace pushis disabled by default on Xano workspaces (allow_pushmust be explicitly enabled).Which approach do you prefer?
- Sandbox workflow (recommended — fully isolated, safe by default)
- Direct workspace push (faster iteration but riskier — requires enabling
allow_pushin workspace settings)- Something else (CI/CD, manual in dashboard, etc.)
If the user chooses workspace push, explain the risks clearly and confirm they understand. If they choose sandbox (or don't express a preference), proceed with sandbox as the default.
Who works on the Xano backend?
- Just me
- Small team (2-5 people)
- Larger team with defined roles
Are there any conventions I should follow? (naming, code style, PR process, etc.)
Are there any no-go zones I should know about?
- Tables I should never modify the schema of?
- Endpoints or functions I shouldn't touch?
- Environment variables that are sensitive or shouldn't be changed?
- Any integrations (webhooks, third-party services) I should be careful around?
Do you use separate data sources for test vs. live data?
- If yes: which data source should I use during development?
- If no: should I be careful about modifying data directly?
This question focuses on how to author code, not how to deploy it (that was covered in 2d).
How would you like me to author and edit Xano code?
- Edit .xs files locally (pull → edit → push to sandbox)
- Via MCP tools for quick inline changes
- Some combination
Should I always validate XanoScript before pushing to sandbox?
If the user chose sandbox in 2d, the deployment workflow is already established — don't re-ask about it here.
Run quick smoke tests to confirm the development workflow actually functions. Do these in parallel where possible.
If there are existing .xs files, pick one and run mcp__xano__xano_validate_xanoscript to confirm validation works.
Make a read-only Meta API call (e.g., list API groups) to confirm the auth token and instance URL work for the workspace.
If the user specified a development branch, confirm it exists and is accessible.
If the user chose the sandbox workflow (the default):
xano sandbox get -p [profile] to create or retrieve the sandbox environmentIf the user opted for workspace push instead:
xano workspace get [workspace-id] and check if Allow Push is enabled## Workflow Validation
| Test | Result |
|-------------------------|--------|
| XanoScript validation | ✅ Working / ⚠️ No .xs files to test / ❌ Failed |
| Meta API access | ✅ Connected / ❌ Auth error |
| Dev branch access | ✅ Confirmed / ➖ N/A (single branch) |
| Sandbox environment | ✅ Provisioned / ❌ Failed / ➖ N/A (using workspace push) |
| CLI profile | ✅ [profile] → workspace [id], branch [branch] |
If anything fails, troubleshoot with the user before proceeding.
Based on everything gathered, create a focused development playbook at .claude/xano-workspace-profile.md. This is NOT an architecture document — it's a set of operating instructions for how to develop safely.
---
workspace: [Name]
workspace_id: [ID]
instance: [subdomain.xano.io]
cli_profile: [profile-name]
generated: [ISO date]
---
# Xano Development Playbook: [Workspace Name]
## Quick Reference
| Key | Value |
|-----|-------|
| Workspace ID | [id] |
| Instance | [url] |
| CLI Profile | [profile-name] (use `-p [profile-name]` with all CLI commands) |
| App Status | [Development / Staging / Production] |
| Dev Branch | [branch name or "main/v1"] |
| Live Branch | [branch name or "same as dev"] |
| Deploy Method | Sandbox (recommended) / [Workspace Push / Manual — only if user chose] |
| Workspace Push | [Enabled / Disabled (default)] |
| Data Source | [test / live / single] |
## Development Rules
[Generate 5-10 clear, specific rules based on the user's answers. These should be imperative statements. Lead with sandbox safety rules. Examples:]
1. Always deploy via sandbox: `sandbox push` → `sandbox review` → promote. Never push directly to workspace.
2. Always work on the `dev` branch — never modify the live branch directly
3. Always use `-p [profile]` with CLI commands to target the correct workspace and branch
4. Validate all XanoScript with `xano_validate_xanoscript` before pushing to sandbox
5. Never modify the `user` or `account` table schemas — they're in production
6. Run `sandbox unit_test run_all` before promoting changes
7. If sandbox gets into a bad state, reset with `sandbox reset -p [profile] -f`
8. [etc. — based on actual user answers]
If the user opted for workspace push instead of sandbox, adjust rules accordingly but include a clear warning about schema changes hitting the real database.
## How to Deploy Changes
### Sandbox Workflow (default)
#### Editing an existing endpoint or function
1. Pull workspace locally: `xano workspace pull ./xano -p [profile] -b [dev-branch]`
2. Edit the relevant `.xs` files
3. Validate: use `xano_validate_xanoscript` MCP tool
4. Push to sandbox: `xano sandbox push ./xano -p [profile]`
5. Run tests in sandbox: `xano sandbox unit_test run_all -p [profile]`
6. Review in browser: `xano sandbox review -p [profile]`
7. Promote changes from sandbox to the dev branch via the review UI
8. Pull updated state: `xano workspace pull ./xano -p [profile] -b [dev-branch]`
#### Creating a new endpoint or function
1. Create the `.xs` file locally following existing workspace patterns
2. Validate the XanoScript
3. Push to sandbox: `xano sandbox push ./xano -p [profile]`
4. Review and promote: `xano sandbox review -p [profile]`
#### Resetting the sandbox
If the sandbox gets into a bad state or you want a clean slate:
```bash
xano sandbox reset -p [profile] -f
xano sandbox unit_test run_all -p [profile]
xano sandbox workflow_test run_all -p [profile]
xano sandbox env list -p [profile]
xano sandbox env set KEY value -p [profile]
xano sandbox env get_all -p [profile]
⚠️ Warning:
workspace pushpushes directly to the workspace branch. Schema changes (table adds/removes/modifications) take effect on the real database immediately, even on a dev branch. This is NOT isolated.allow_pushmust be enabled on the workspace (disabled by default as a safety guard).
xano workspace pull ./xano -p [profile] -b [dev-branch].xs filesxano workspace push ./xano -p [profile] -b [dev-branch] --dry-runxano workspace push ./xano -p [profile] -b [dev-branch][List specific tables, endpoints, functions, or env vars the user said not to touch]
[Any naming conventions, code style rules, or collaboration norms]
xano sandbox get -p [profile]xano sandbox reset -p [profile] -fxano update or npm install -g @xano/cliallow_push is disabled by default on Xano workspaces as a safety guard[Known gotchas like where clause syntax, $auth.account_id issues]
Keep the playbook **concise and actionable**. Every line should be something that changes how you develop. No filler.
---
## Phase 5: Update CLAUDE.md
Add or update a small Xano section in the project's `CLAUDE.md` that points to the playbook and lists the top 3-5 most critical rules. This ensures every future conversation loads the key constraints immediately.
```markdown
## Xano Backend
- **Workspace:** [Name] (ID: [id]) on [instance]
- **Status:** [Production/Development/etc.]
- **CLI Profile:** `[profile-name]` (always use `-p [profile-name]`)
- **Playbook:** See `.claude/xano-workspace-profile.md` for full development rules
### Critical Rules
1. Always use the sandbox workflow — `sandbox push` → `sandbox review` → promote. Never push directly to workspace.
2. [Branch safety rule — e.g., never touch v1/live directly]
3. [Most important data/schema constraint]
4. Always validate XanoScript before pushing to sandbox
5. [Other key constraint from user answers]
If CLAUDE.md already has a Xano section, update it rather than duplicating.
Present a brief summary to the user:
End with: "You're all set. I'll follow the development playbook for all future Xano work in this project."
allow_push unless they specifically ask for the workspace push workflow. If they do, explain the risks clearly.xano sandbox *) inherit workspace and branch from the CLI profile. They do not accept -w or -b flags. This is why setting up a dedicated CLI profile with the correct workspace ID and branch is essential during init.live, confirm with the user that it's actually the production branch.mcp__xano__xano_*) → CLI (xano commands) → Meta API via curl → ask the user. Use MCP for docs/validation; use CLI for workspace/branch/function/sandbox operations. Both can coexist./xano-init workspace 43), skip the workspace selection step and use the provided ID.