How to use the Cloud Spanner Basics agent skill

What does the spanner-basics skill make the agent do?

Once installed, the agent follows Spanner guidance when you ask about provisioning instances and databases, designing schemas, writing SQL or client library code, or diagnosing performance problems. The skill covers primary key design that avoids hotspots, when to use interleaved parent-child tables, and how to write gcloud, client library, Terraform and PostgreSQL-dialect code.

For performance work, the skill points the agent to the SPANNER_SYS tables, such as SPANNER_SYS.QUERY_STATS_TOP_HOUR, to find the queries using the most CPU.

• Design primary keys that avoid monotonically increasing values, such as sequential timestamps, as the first part of the key.
• Prefer interleaved tables for strongly related parent-child data that is accessed together.
• Generate gcloud spanner, client library, Terraform and PostgreSQL-dialect examples.
• Look for slow or resource-intensive queries in SPANNER_SYS statistics.

How do you install the spanner-basics skill?

Download the ZIP file from the skill page on this site. You can install it in one of two ways: unzip it into your personal skills folder, or into a project folder, or upload it in the Claude apps.

For a personal install, unzip it into ~/.claude/skills/. For a single project, unzip it into the .claude/skills/ folder inside that project. In the Claude apps, open Settings, go to Capabilities, then Skills, and upload the ZIP there.

• Personal: ~/.claude/skills/
• Project: .claude/skills/ inside your project folder
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP

How do you trigger the skill with natural requests?

You do not need a special command. Describe the task in plain language that mentions Spanner and the kind of help you need. The skill's description covers primary key design, SQL queries, client library code, and performance diagnosis, so requests on those topics are the ones it is meant to handle.

Name the database or instance when you can. The agent cannot always check that resources exist, so specific names help it write correct commands.

• Help me choose a primary key for an Orders table in Cloud Spanner that will not create hotspots.
• Should Invoices be interleaved under Customers in my Spanner schema?
• Find the slowest queries in my Spanner database over the last hour.
• Write Python client code to read rows from my Spanner database.
• Write Terraform for a regional Spanner instance with one node.

What does a typical session look like?

For a schema change, the agent suggests the DDL and the gcloud command to apply it. It will not run that change on its own. For example, the skill uses gcloud spanner databases ddl update to apply CREATE, ALTER, or DROP statements for tables and indexes.

For a read-only command such as listing instances, the same approach applies: the agent gives you the command to run. The skill's reference files include CLI commands for creating instances and databases, listing them, and running queries with execute-sql.

What does the skill need to work?

You need a Google Cloud account and the gcloud CLI for command-line operations. The gcloud install instructions are at docs.cloud.google.com/sdk/docs/install-sdk. If you write code, you need the Spanner client library for your language: Java, Go, Python or Node.js. For Python, the source gives pip install google-cloud-spanner. Terraform is needed only if you use the Terraform examples. The Spanner remote MCP server and the Developer Knowledge MCP server are optional and used only if you set them up.

The skill makes network calls. It does not run scripts.

• Google Cloud account and gcloud CLI for command-line work
• Spanner client library for Java, Go, Python or Node.js, if writing code
• Terraform, if using the Terraform examples
• Spanner remote MCP server and Developer Knowledge MCP server, if used

What safety rules does the skill enforce?

The skill tells the agent to get your explicit confirmation before any non-emulator database change, whether DML or DDL, and before any destructive operation such as dropping tables, indexes or other Spanner resources. The agent should output the command, for example gcloud spanner databases ddl update, and ask for approval rather than run it.

The skill also tells the agent to read the usage attribution guide before running gcloud, REST or MCP commands. For terminal commands, it adds the metrics variable CLOUDSDK_METRICS_REQUEST_ATTRIBUTION inline on each command, and does not use gcloud config set for this.

• Expect approval prompts before any schema or data change.
• If the agent cannot verify that an instance, database or table exists, it may assume the resources exist and write DDL. Check the target project and names before running anything.
• Its reference files are guides, not executable tools.

What tips help you get the best results?

Review every generated DDL statement before you approve it, especially the project, instance and database names. Use the skill for design and review, and test changes in a non-production environment first. If the skill lacks a product detail, the skill directs the agent to the search_documents tool of the Developer Knowledge MCP server.

• Give the agent your instance and database names and the language you use.
• Ask for the reasoning behind a primary key choice, not just the answer.
• Check generated Terraform and client code against your own environment before use.