--- title: "Teaching Claude Code to use isolated database branches with Agent Skills" description: "Learn how to set up the Xata Agent Skill in minutes. Enable Claude Code to access realistic data using isolated database branches for safer, faster debugging." source: "https://xata.io/blog/teaching-claude-code-to-use-isolated-database-branches-with-agent-skills" --- # Teaching Claude Code to use isolated database branches with Agent Skills Modern LLMs have come a long way in turning prompts into code. They even execute specific developer workflows when asked. Using [Agent Skills](https://claude.com/blog/skills), it is now possible to teach [Claude Code](https://claude.com/product/claude-code) to get realistic data using isolated developer branches. We have bundled together a “Xata Claude Skill” that teaches Claude to use isolated database branches. To use it, simply download the xata CLI and execute: ``` $ curl -fsSL https://xata.io/install.sh | bash Xata CLI was installed successfully. $ xata ai download claude-skill Downloaded: LICENSE.txt Downloaded: SKILL.md Xata Claude Skill downloaded to .claude/skills/xataxata ai download claude-skill ``` ## Demo aka “enough talk, show me the goods” [Watch video](https://www.youtube.com/watch?v=lDcMY_jFOSs) ## Advantages of Agent Skills Similar outcomes can be achieved with [CLAUDE.md](http://Claude.md) file or by using an MCP server. What are the advantages of using [Agent Skills](https://code.claude.com/docs/en/skills) over other alternatives? **The context window advantage** Unlike [`CLAUDE.md`](http://CLAUDE.md), which is always included in the context window, the prompt and script from a skill are lazy loaded into the context window, decided by the agent. This means cheaper bills as less tokens are used in each chat and better quality as the context window remains focused on the task at hand. **The scripting advantage** Agent Skills aren’t limited to lazy prompt loading. Not only can they execute scripts, they can execute scripts as a black box (without reading the file in the context window but just executing it and loading the output in the context window) **Write once, use anywhere** Instead of writing a fixed prompt and managing it across projects, an Agent Skill can be shared across projects and used by all Claude products (`claude` Code, Claude apps, API). **Against MCP** Skills have a simple tool calling mechanism in comparison to MCP servers. For example, you can authenticate a CLI with an API key and just instruct the model to use it via CLI. To do something similar with an MCP server, you have to cross the network boundary or have some protocol to pass information between the model’s context window, the actual CLI or API and the MCP server. Agent Skills can achieve loading data from external tools in the model’s context window in one less level of indirection. **Composability and other benefits** Agent Skills can be combined to form custom complex workflows. Look at the advantages of using Agent Skills here in [Anthropic’s documentation](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview#why-use-skills). ## The API The API we offer to download the Agent Skill is simple, just run the following command in your project after you have gone through the [quickstart guide](https://xata.io/documentation/quickstart) and the project is initialized. ``` $ xata ai download claude-skill ``` While there are other ways to make the skill available to Claude products. We prefer this because: 1. It enables you to version the skill 2. It enables you to change the skill a bit per the requirements of a project 3. It is isolated and the simplest setup for a skill (just one command) ## Under the hood In the beginning of this post, we downloaded the Xata claude skill using: ``` $ xata ai download claude-skill ``` This is the file that got downloaded: ``` --- name: xata description: Xata platform allows instant copy on write branching to provide AI agents an isolated databsae environment. Because this skill needs `xata`, `psql`, `gh` CLIs available, authenticated and ready to use. This skill can only be used in claude code CLI. license: Proprietary. LICENSE.txt has complete terms --- # Xata - Postgres Database Branches ## Overview The user will prompt their query regarding fixing a bug or implementing a feature. Using Xata you can create an isolated database branch with realistic data. Here is the playbook you can follow. ## Notes for the AI agent You are an AI coding assistant and your goal is to help the developer fix bugs and build features. You have several tools available in form of CLIs. 1. You can use the `gh` CLI to read issues and pull requests. If you can't read it (say because of auth issue for example), do not proceeed and notify the user. 2. THIS IS THE MOST IMPORTANT TOOL AVAILABLE TO YOU. You can use the `xata` CLI to create branches. `xata status` should give you the current branch (this is the main production branch, IMPORTANT, never read / write to it). You can create a new branch using `xata branch create --name ''`. You can wait for a branch to be ready to use by running `xata branch wait-ready `. Once you create a branch, it gets checked out automatically, if it doesn't you can use `xata checkout `. The most important property of this branch is that it has realistic data, so to solve a bug, you can read code and try queries to see and validate fixes before making the changes. 3. You can use `psql` to query the database, you can use the `-c` flag to run a query as expression and read the results. IMPORTANT, DO NOT USE `$DATABASE\_URL` with `psql` that's the production branch. Use `xata branch url` to get the URL of the current checked out branch. If the check out step failed (wait-ready didn't succeed) STOP, don't EVER write to the main branch. NEVER read `seed.sql`, that might be outdated, always query a real database branch. Once you have identified the issue using the tools above, fix it. ``` That's right, around 20 lines of prompt telling the LLM how to use various CLIs is all it needs to start following a custom workflow. And because it is plain text, making small adjustments to customize your workflow is also easy. ## Conclusion In this post, we explored how [Agent Skills](https://code.claude.com/docs/en/skills) provide a fantastic way to teach [Claude Code](https://claude.com/product/claude-code) to work with isolated database branches and how it was able to diagnose and resolve a bug much like a developer would. We look forward to having you try the Xata platform. If you'd like early access, you can [get started today](https://xata.io/get-access).