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

> Customize google skills behavior by editing SKILL.md, extending Python scripts, and adjusting Terraform configs. Follow our step-by-step guide for seamless integration.

- Repository: [Google/skills](https://github.com/google/skills)
- Tags: how-to-guide
- Published: 2026-08-14

---

**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`](https://github.com/google/skills/blob/main/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:

```bash
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:

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

```

Key files for this skill include:

- [`SKILL.md`](https://github.com/google/skills/blob/main/SKILL.md) — the core definition
- [`scripts/config_utils.py`](https://github.com/google/skills/blob/main/scripts/config_utils.py) — shared validation utilities

### 3. Add or Modify Parameters in SKILL.md

Open [`SKILL.md`](https://github.com/google/skills/blob/main/SKILL.md) and locate the Parameters table. Add a new parameter by extending the table:

```markdown
| 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`](https://github.com/google/skills/blob/main/skills/cloud/agent-platform-alert-configuration/scripts/config_utils.py), add a validation function:

```python
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`](https://github.com/google/skills/blob/main/scripts/config_utils.py) to incorporate your new parameter:

```python

# 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:

```bash
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:

```bash
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

```markdown

## 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

```python

# 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

```python

# 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

```bash
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`](https://github.com/google/skills/blob/main/README.md) | Repository overview and installation | https://github.com/google/skills/blob/main/README.md |
| [`skills/cloud/agent-platform-alert-configuration/SKILL.md`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/SKILL.md)** for parameter and prompt changes, and **[`scripts/config_utils.py`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/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.