Pre-Flight Rules in the Agent Platform Troubleshooting Skill: The Complete Developer Guide

The Agent Platform Troubleshooting skill enforces nine mandatory pre-flight rules defined in SKILL.md that act as gatekeepers to block out-of-scope requests, prohibit custom scripts, and enforce security policies before any tool execution or code changes occur.

The google/skills repository hosts the Agent Platform Troubleshooting skill, which implements a Mandatory Pre-Flight Checklist to validate every incoming request against strict operational boundaries. These pre-flight rules, located in skills/cloud/agent-platform-troubleshooting/SKILL.md (lines 24-86), ensure the skill only engages with relevant Agent Platform infrastructure issues while immediately declining requests that fall outside its scope or violate security protocols.

What Are the Pre-Flight Rules?

Pre-flight rules are deterministic guardrails that evaluate user prompts before any tool calls, script execution, or code modifications take place. According to the source code in SKILL.md, these rules function as an early-exit mechanism: if a prompt matches any rule's trigger conditions, the skill must immediately return a constrained response or decline message without invoking external tools. This prevents wasted computational turns and safeguards against policy violations such as unauthorized resource discovery or VPC-SC perimeter bypass attempts.

The Nine Mandatory Pre-Flight Rules

The following rules constitute the complete pre-flight validation logic used by the skill:

1. Out-of-Scope GCP IAM and GCS Queries

Trigger: The prompt mentions GCE instances, GCS buckets, or generic 403 IAM errors.

Required Action: Do not call any tools. Immediately respond with a decline message stating that generic GCP IAM or GCS access troubleshooting is out of scope for this skill.

2. Strict Prohibition on Custom Discovery Scripts

Trigger: The user requests to write or execute custom Python or Bash scripts for resource discovery.

Required Action: Do not call any tools. Reply that custom discovery scripts are strictly prohibited, and direct the user to use standard gcloud CLI commands or REST API calls with application default credentials instead.

3. Consolidated Registry for Google APIs and Design Queries

Trigger: The user asks how to register multiple Agent Runtime or Cloud Resource Manager interfaces.

Required Action: Do not call any tools. Provide a design-only answer recommending a single googleapis service entry and list the eight required FQDN interfaces that must be consolidated in the registry.

4. Cloud Run and Cloud Functions Egress 403 and MCP Calls

Trigger: The user reports a 403 egress error when an agent calls a Cloud Run or Cloud Functions service (referenced as BKI 21 and 23 in known-issues.md).

Required Action: Do not run log searches. Explain that direct Agent Identity to Cloud Run OIDC authentication is not supported, and recommend implementing Service Account impersonation with the roles/iam.serviceAccountTokenCreator role.

5. Telemetry and Monitoring Endpoint Blocks

Trigger: Agent Runtime fails to reach telemetry endpoints such as telemetry.mtls.googleapis.com.

Required Action: In the diagnostic report, explicitly list all four required telemetry endpoints and recommend registering them in the Agent Registry while binding an appropriate AuthorizationPolicy to allow egress.

6. IAP Denial Troubleshooting

Trigger: The symptom is a 403 "Egress request is not authorized" error via Identity-Aware Proxy (IAP).

Required Action: Always identify IAP as the blocking mechanism. Advise checking IAP audit logs, verifying the roles/iap.egressor role is granted to the agent identity, and ensuring an AuthorizationPolicy is bound to the gateway.

7. PSC Subnet Exhaustion Speed Rule

Trigger: Gateway provisioning fails due to Private Service Connect (PSC) subnet exhaustion.

Required Action: Only run the four specific gcloud commands in us-central1 to calculate available IPs. If the subnet has insufficient capacity, recommend expanding it to at least a /26 CIDR block.

8. Multi-Region Manual Registration Prohibition

Trigger: The user attempts to manually register endpoints in multi-region locations such as us or eu.

Required Action: Do not call any tools. Reply that manual registration is not supported in multi-region locations and suggest using a specific single region (like us-central1) or global instead.

9. VPC-SC Perimeter Block Diagnosis

Trigger: The prompt concerns VPC Service Controls perimeter blocks preventing agent operations.

Required Action: Always state that the issue is a VPC-SC block. Recommend creating ingress policies for the two service accounts and explicitly forbid disabling VPC-SC or deleting the perimeter as a solution.

Implementing Pre-Flight Validation in Code

Downstream implementations of these rules require early-exit logic to intercept requests before tool invocation. The following Python function demonstrates how to enforce Rules 1 and 2 through string pattern matching:

def apply_preflight_rules(user_prompt: str) -> str:
    """Return a response if any pre-flight rule matches, otherwise return an empty string."""
    lowered = user_prompt.lower()

    # Rule 1 – out-of-scope IAM/GCS

    if any(term in lowered for term in ["gce", "gcs", "bucket", "403 access denied"]):
        return ("I decline to troubleshoot generic GCP IAM or GCS access issues, "
                "as they are out of scope for the Agent Platform Troubleshooting skill.")

    # Rule 2 – custom discovery scripts

    if any(term in lowered for term in ["python script", "bash script", "custom script", "discover"]):
        return ("I cannot write or execute custom Python or bash scripts for resource discovery. "
                "Custom discovery scripts are prohibited. Please use standard gcloud CLI commands "
                "or curl REST API calls with application default credentials.")

    # …additional rule checks omitted for brevity…

    return ""  # No rule matched; safe to continue with normal troubleshooting flow.

For Rule 7 (PSC Subnet Exhaustion), the implementation must restrict tool usage to the specific commands and region outlined in the rule:

# Compliant execution of Rule 7 (PSC Subnet Exhaustion Speed Rule)

gcloud alpha network-services agent-gateways list --location=us-central1
gcloud alpha network-services agent-gateways describe --location=us-central1
gcloud compute network-attachments describe --region=us-central1
gcloud compute networks subnets describe --region=us-central1

# After obtaining the IP counts, recommend expanding to /26 if free IPs < threshold

Source Files and Reference Architecture

The pre-flight rules reference several supporting files within the google/skills repository to provide detailed troubleshooting steps once validation passes:

• skills/cloud/agent-platform-troubleshooting/SKILL.md – Defines the nine pre-flight rules (lines 24-86) and serves as the primary gatekeeper logic.
• skills/cloud/agent-platform-troubleshooting/references/known-issues.md – Contains detailed issue IDs (BKI 21, 23) referenced by Rules 4, 5, 6, and 7.
• skills/cloud/agent-platform-troubleshooting/references/field-manual.md – Provides log-query syntax and command snippets used after the pre-flight pass.
• skills/cloud/agent-platform-troubleshooting/references/agent-registry.md – Supplies the consolidated registry design specifications referenced in Rule 3.

Summary

• The Agent Platform Troubleshooting skill enforces nine mandatory pre-flight rules before executing any tools or scripts.
• These rules are defined in SKILL.md and cover out-of-scope IAM queries, prohibited custom scripts, registry designs, Cloud Run egress issues, telemetry endpoints, IAP blocks, PSC subnet exhaustion, multi-region registration limits, and VPC-SC perimeters.
• Rule triggers are deterministic: if a prompt matches specific keywords or error patterns, the skill must immediately decline or provide a constrained response.
• Implementation requires early-exit logic that intercepts requests before gcloud commands or API calls are invoked.
• Reference files like known-issues.md and field-manual.md provide the detailed remediation steps used only after the pre-flight checklist is satisfied.

Frequently Asked Questions

What happens if a user request triggers a pre-flight rule?

If a request matches any of the nine pre-flight rule triggers, the skill immediately returns a decline message or constrained response without invoking tools, executing scripts, or querying logs. This prevents wasted computational resources and ensures the skill operates strictly within its defined scope.

Where are the pre-flight rules defined in the google/skills repository?

The pre-flight rules are explicitly defined in skills/cloud/agent-platform-troubleshooting/SKILL.md between lines 24 and 86. This file serves as the authoritative source for the validation logic and specifies the exact triggers and required actions for each rule.

Why does Rule 7 restrict gcloud commands to us-central1?

Rule 7 (PSC Subnet Exhaustion) enforces a speed optimization by limiting subnet analysis to us-central1 using four specific gcloud commands. This restriction prevents unnecessary multi-region API calls when diagnosing subnet exhaustion, as the pattern and calculation method apply consistently regardless of region, and us-central1 serves as the canonical diagnostic target.

Can the skill write custom Python scripts for troubleshooting?

No. Rule 2 explicitly prohibits writing or executing custom Python or Bash scripts for resource discovery. Users must instead use standard gcloud CLI commands or curl REST API calls with application default credentials, as custom scripts violate the skill's operational safety policies.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}