# Pre-Flight Rules in the Agent Platform Troubleshooting Skill: The Complete Developer Guide > Understand the nine pre-flight rules in the Agent Platform Troubleshooting skill. Learn how these rules block out-of-scope requests, prevent custom scripts, and enforce security. - Repository: [Google/skills](https://github.com/google/skills) - Tags: deep-dive - Published: 2026-09-04 --- **The Agent Platform Troubleshooting skill enforces nine mandatory pre-flight rules defined in [`SKILL.md`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/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: ```python 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: ```bash # 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`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/known-issues.md) and [`field-manual.md`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/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.