How to Customize the Behavior of google/skills: A Step-by-Step Guide

You can customize google/skills by editing SKILL.md files to modify parameters and prompts, extending Python validation scripts, and adjusting generated Terraform configurations.

The google/skills repository contains skill definitions that power Google-based AI agents. Each skill lives in its own directory under skills/ with a SKILL.md file at its core, optionally supported by reference files, scripts, and Terraform templates. When you run npx skills add google/skills, the CLI parses these markdown files to build runnable agent harnesses. Customizing the behavior of google/skills therefore means modifying these source files to match your organization's policies, naming conventions, or operational requirements.

Understanding the google/skills Architecture

Before diving into customization, it's essential to understand how the repository structures its components. The SKILL.md file in each skill directory defines the conversational flow, default parameters, and validation rules. Supporting files in references/ and scripts/ directories provide supplemental documentation and runtime utilities.

Component	Purpose	Customization Point
skills/**/SKILL.md	Core skill definition	Edit prompts, add parameters, modify validation logic
skills/**/references/	Documentation and helper scripts	Replace examples, add custom scripts
skills/**/scripts/	Runtime helpers (linting, Terraform generation)	Extend utility functions
plugins/**	Google-product plugins used by the CLI	Add or replace plugin definitions

Step-by-Step: Customize a Skill in google/skills

1. Clone the Repository

Start by cloning the google/skills repository to your local environment:

git clone https://github.com/google/skills.git
cd skills

2. Select a Skill to Customize

Navigate to your target skill directory. This guide uses Agent Platform Alert Configuration as a concrete example:

cd skills/cloud/agent-platform-alert-configuration/

Key files for this skill include:

• SKILL.md — the core definition
• scripts/config_utils.py — shared validation utilities

3. Add or Modify Parameters in SKILL.md

Open SKILL.md and locate the Parameters table. Add a new parameter by extending the table:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `custom_alert_label` | string | no | A free-form label attached to every generated alert policy. |

The CLI automatically surfaces this new field when the skill runs.

4. Extend Validation Logic in Python

For parameters requiring validation, modify the corresponding utility file. In skills/cloud/agent-platform-alert-configuration/scripts/config_utils.py, add a validation function:

def validate_custom_label(label: str) -> list[str]:
    """Ensures the custom label follows `^[a-z0-9_-]{1,30}$`."""
    errors = []
    if not re.fullmatch(r"[a-z0-9_-]{1,30}", label):
        errors.append(
            f"Custom label '{label}' is invalid: must be 1-30 lowercase alphanumerics, '-', or '_'"
        )
    return errors

Integrate this validation into the main pipeline by calling it from lint_query or a dedicated validate_skill_parameters function.

5. Modify Generated Resources

Agent Platform skills typically emit Terraform or HCL. Update the generation logic in scripts/config_utils.py to incorporate your new parameter:

# Within extract_alert_policies

if policy.get("custom_alert_label"):
    block_content = block_content.replace(
        'resource "google_monitoring_alert_policy"',
        f'resource "google_monitoring_alert_policy" "{policy["custom_alert_label"]}"'
    )

6. Test Your Customizations Locally

Validate your changes using dry-run mode:

npx skills run agent-platform-alert-configuration \
  --dry-run \
  --param custom_alert_label=my-test-label

Verify that the generated HCL includes your custom label and produces no validation errors.

7. Commit and Distribute

Once validated, commit your changes:

git add .
git commit -m "Add custom_alert_label to Agent Platform Alert Configuration"
git push origin main

Users can now access the updated skill through the CLI with the new parameter available.

Common Customization Patterns for google/skills

Pattern 1: Adding Optional Parameters to SKILL.md

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `project_id` | string | yes | Google Cloud project where alerts will be created. |
| `custom_alert_label` | string | no | Optional label attached to every alert policy. |

Pattern 2: Parameter Validation Functions

# skills/cloud/agent-platform-alert-configuration/scripts/config_utils.py

def validate_custom_label(label: str) -> list[str]:
    """Validate `custom_alert_label` format."""
    if not re.fullmatch(r"[a-z0-9_-]{1,30}", label):
        return [f"Invalid label '{label}'. Must be 1-30 lowercase alphanumerics, '-' or '_'."]
    return []

Pattern 3: Injecting Values into Generated HCL

# Within extract_alert_policies (same file)

if policy.get("custom_alert_label"):
    block_content = block_content.replace(
        'resource "google_monitoring_alert_policy"',
        f'resource "google_monitoring_alert_policy" "{policy["custom_alert_label"]}"'
    )

Pattern 4: Running with Custom Parameters

npx skills run agent-platform-alert-configuration \
  --param project_id=my-gcp-project \
  --param custom_alert_label=my_test_label

Key Source Files for Customizing google/skills

File	Role	Link
README.md	Repository overview and installation	https://github.com/google/skills/blob/main/README.md
skills/cloud/agent-platform-alert-configuration/SKILL.md	Example skill with parameters and validation	https://github.com/google/skills/blob/main/skills/cloud/agent-platform-alert-configuration/SKILL.md
skills/cloud/agent-platform-alert-configuration/scripts/config_utils.py	Validation and policy extraction utilities	https://github.com/google/skills/blob/main/skills/cloud/agent-platform-alert-configuration/scripts/config_utils.py
skills/cloud/workload-manager-basics/SKILL.md	Custom Rego rules pattern	https://github.com/google/skills/blob/main/skills/cloud/workload-manager-basics/SKILL.md
plugins/cloud/data-agent-kit/README.md	Plugin-level customizations	https://github.com/google/skills/blob/main/plugins/cloud/data-agent-kit/README.md

Summary

• Skills are source-driven — behavior lives in SKILL.md markdown files and supporting scripts
• Four customization points: parameters, prompts, validation utilities, and generated Terraform/HCL
• Development workflow: clone → edit → npx skills run --dry-run → commit
• Extensibility: contribute new skills under skills/ or plugins under plugins/

Following these steps lets you tailor any Google skill to your requirements without modifying the core CLI.

Frequently Asked Questions

What files should I edit to customize a skill's behavior in google/skills?

Edit SKILL.md for parameter and prompt changes, and scripts/config_utils.py (or equivalent) for validation and resource generation logic. These files are parsed by the CLI to build the runnable agent harness.

How do I add a new parameter to an existing google/skills skill?

Add the parameter to the Parameters table in SKILL.md, then optionally create a validation function in the skill's scripts/ directory. The CLI automatically detects and surfaces new parameters on the next run.

Can I test skill customizations without deploying them?

Yes. Use npx skills run <skill-name> --dry-run to validate your changes locally. This mode executes the skill logic without creating actual resources, letting you verify parameter handling and generated output.

Where should I place custom scripts that support my skill modifications?

Place helper scripts in the skill's references/ or scripts/ directory. Files in references/ are typically for documentation and examples, while scripts/ contains executable utilities used during skill execution.

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