How to use the Filestore Capacity Autoscale agent skill

What the skill makes the agent do

An agent skill is a folder with a SKILL.md file that tells an AI agent how to handle a specific task. When this skill applies, the agent lists the Filestore instances in a project, reads each instance's capacity and tier, and measures how much space is used using the Cloud Monitoring metric file.googleapis.com/nfs/server/used_bytes. It then calculates the percentage of free space for each instance and sorts each one into a verdict about whether it needs to scale.

• Scale up when free space is below 15%. The default increase is 10% of capacity, rounded to the tier's step increment.
• Scale down when free space is above 30% and the instance is eligible. The default reduction is 10% of current capacity, aligned to the step increment.
• Basic HDD and Basic SSD instances can scale up but cannot scale down.
• Zonal and Regional instances can scale down, but not below their minimum floor or below the amount of data they currently hold.

Install the skill from the ZIP

Download the skill ZIP from this page and unzip it. The skill folder, google-cloud-filestore-autoscale, should contain SKILL.md and its references folder. Put it in one of two places depending on how you want to use it.

For a personal setup available across your projects, unzip it into ~/.claude/skills/. For a single project, unzip it into the .claude/skills/ folder inside that project. You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills.

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

Set up Google Cloud before the first run

The skill needs a Google Cloud project with the Filestore API and the Cloud Monitoring API enabled, the gcloud CLI installed and authenticated, and the right IAM roles on the service account the agent uses. The source names roles/file.editor for listing instances and making resize updates, roles/monitoring.viewer for reading the used_bytes metric, and roles/mcp.toolUser only if the agent uses Filestore MCP tools.

You can enable the two APIs with the command below. The skill's quick start lists this as the setup step after installing gcloud.

• Install gcloud if needed, using the gcloud installation guide linked from the skill.
• Enable the required APIs.

Trigger the skill with natural requests

You do not need a special command to start the skill. Describe what you want in plain language and mention Filestore, storage capacity, or instance headroom. The skill is written to be used when you monitor headroom, resize shares, set up growth or shrink thresholds, or want to prevent out-of-space outages.

Be clear about the kind of answer you want. If you only want an explanation, say so. If you want the agent to avoid running any commands, say that too. The skill handles both cases differently, as described in the next section.

• Check whether any Filestore instances in my project are running low on space.
• Review capacity across all Filestore instances in project my-project and suggest any scale-down candidates.
• Explain the difference between Basic and Zonal Filestore tiers. (A conceptual question, answered without commands.)
• Read-only: show me which Filestore instances need more capacity, but do not run any commands.

What a capacity review looks like

For a fleet review, the skill makes one bulk Cloud Monitoring request for the whole project rather than one query per instance, and it does not filter by zone or region. If an instance has no metric data, the skill treats its used bytes as 0. The result is a summary table with used bytes and free space percentage for each instance and an Autoscale Needed value.

When an instance needs a resize, the response states the current free space percentage, the target capacity, and the gcloud update command. The skill ends by asking you to confirm before it changes anything. A typical closing question looks like this: Would you like me to proceed with scaling an instance from A TiB to B TiB? Please confirm to execute.

• Free Space % = ((capacityGb - used_bytes_gb) / capacityGb) × 100
• Scale-up step sizes: 256 GiB for the Small Band (1 to 9.75 TiB) and 2.5 TiB for the Large Band (10 to 100 TiB)
• Attribution: gcloud commands are prefixed with CLOUDSDK_METRICS_ENVIRONMENT so the skill's calls are tagged

Understand the safety rules and limits

The skill is built to stop before changing capacity. Even when you ask for command syntax or a read-only review, the response still ends with a request for your confirmation before any resize command runs. For conceptual questions, the skill answers from its own knowledge and does not call tools.

If you tell the agent not to run commands, the skill avoids the run_command tool. It first tries Filestore MCP tools such as list_instances and get_instance, then looks for instance data in local reference files, and if it finds nothing it prints the commands for you to run yourself. The skill also says it should not read evaluation config files such as EVAL.yaml during evaluation runs.

The skill runs scripts and uses the network, because it calls Google Cloud APIs and gcloud. Its IAM note says resizing can affect running workloads, and it expects editor-level permissions. Review those roles before you use it on a production project.

• Confirmation is required before any resize, so it is not an unattended scaler.
• Capacity cannot shrink below used_bytes for Zonal or Regional instances.
• Custom thresholds apply globally across projects in session memory, according to the skill description, so check the thresholds you set before each review.

Troubleshoot common scale-down errors

The troubleshooting reference covers the two scale-down errors you are most likely to see. Both come from Google Cloud's rules for each tier, not from a fault in the skill.

The first error, capacity for file share may only be increased, means you tried to shrink a Basic HDD or Basic SSD instance. The reference says these are backed by single Persistent Disks, which cannot shrink. The fix is to delete and recreate the instance, or to move to a Zonal or Regional tier if you need to scale down. The second error, cannot decrease capacity below current usage, means the target is smaller than the data already stored. Choose a target at or above used_bytes.

• capacity for file share may only be increased: target is a Basic tier instance.
• cannot decrease capacity below current usage: target is smaller than used_bytes.