# Best Practices for Developing Custom Skills for google/skills: Complete Authoring Guide

> Learn best practices for developing custom google/skills. Follow SKILL.md structure, use public APIs, enforce least-privilege IAM, and organize docs for efficient skill creation.

- Repository: [Google/skills](https://github.com/google/skills)
- Tags: best-practices
- Published: 2026-08-16

---

**The best practices for developing custom skills for google/skills include following the declarative [`SKILL.md`](https://github.com/google/skills/blob/main/SKILL.md) structure, restricting API usage to public surfaces only, enforcing least-privilege IAM roles, and organizing supplementary documentation in a `references/` directory.**

The **Google Skills** repository hosts self-contained, markdown-driven skills that teach agents how to work with Google Cloud products. Each skill follows strict architectural conventions that make it easy for the runtime to parse, for authors to maintain, and for users to consume. Whether you're extending an existing skill or authoring a new one from scratch, adhering to these patterns ensures compatibility with the Google Skills runtime and a consistent experience for end users.

## Core Skill File Anatomy ([`SKILL.md`](https://github.com/google/skills/blob/main/SKILL.md))

Every skill lives in its own directory under `skills/<category>/<skill-name>/SKILL.md`. This file combines YAML front matter with well-structured markdown sections to provide a complete, machine-readable definition.

### Required Sections

| Section | Purpose | Critical Elements |
|---------|---------|-----------------|
| **Header block** (`---`) | Runtime identification and discovery | `name`, `metadata.category`, `description` |
| **Intro** | Human-readable product overview | Context and user expectations |
| **Use This Flow** | Visual workflow guidance | Mermaid diagram showing typical sequence |
| **Core API Constraints** | Security enforcement | Public API only, no internal endpoints |
| **Prerequisites** | Setup and authentication steps | API enablement, ADC, least-privilege IAM |
| **Quick Client-Library Example** | Runnable starter code | Language-appropriate snippets with installation |
| **Reference Directory** | Supplementary documentation | Bulleted links to `references/*.md` files |
| **Authoritative References** | Official documentation links | Google Cloud docs, PyPI packages, REST reference |

The **Workload Manager skill** at [`skills/cloud/workload-manager-basics/SKILL.md`](https://github.com/google/skills/blob/main/skills/cloud/workload-manager-basics/SKILL.md) demonstrates this structure in practice, including a complete workflow diagram and properly constrained API surface.

## Security and API Usage Rules

The repository enforces strict security boundaries that every custom skill must observe.

### Public-Only API Surface

All interactions must use:
- Officially published client libraries (e.g., `google-cloud-workloadmanager`)
- Public REST endpoints (`workloadmanager.googleapis.com/v1`)

**Internal RPCs and undisclosed endpoints are prohibited.** This constraint appears in the "Core API Constraints" section of every [`SKILL.md`](https://github.com/google/skills/blob/main/SKILL.md) and prevents accidental reliance on private APIs that may change or disappear.

### Least-Privilege IAM Defaults

Skills always specify the most restrictive role that permits required operations:
- `viewer` for read-only operations
- `evaluationAdmin` for evaluation management
- `admin` only when full control is necessary

The exact role appears in the Prerequisites section, ensuring users grant only necessary permissions.

### Sandbox-Friendly Fallback

When authentication fails or APIs are unavailable (e.g., blocked by Context-Aware Access), skills must display static example code and curated findings rather than entering retry loops. This pattern appears in lines 49-57 of the Workload Manager skill file.

### No Invented CLI Groups

The repository explicitly notes that **no `gcloud workload-manager` command group exists**. Agents should use `gcloud` strictly for authentication and token acquisition, avoiding unsupported CLI territory.

## Metadata and Categorization Standards

Consistent metadata ensures discoverability and proper runtime behavior.

- **`metadata.category`** — Use existing taxonomy values like `CloudObservabilityAndMonitoring`, `Analytics`, or `Ads`. Choose the most specific match; propose new categories via issue if needed.
- **`description`** — Single paragraph stating intent and appropriate scenarios.
- **Directory naming** — Match the `name` field exactly: lowercase with hyphens (e.g., `workload-manager-basics`).

## Reference Files and Reusable Assets

Every skill includes a `references/` folder containing:

- **Core concepts** — High-level product explanations
- **General best practices** — Organizational policies, tagging standards
- **Client-library usage** — Language-specific reusable snippets
- **REST usage** — Raw HTTP examples for environments without client libraries

Link to these from [`SKILL.md`](https://github.com/google/skills/blob/main/SKILL.md) using relative paths; the runtime renders them as clickable markdown.

## Documentation Style Guidelines

Follow these formatting conventions for consistency:

- Headings use plain language: `## Prerequisites`, `## Quick Client Library Example`

- Code blocks specify language: ````python`, ````bash`, ````mermaid`
- Mermaid diagrams illustrate workflows
- Authoritative links use full Google Cloud URLs, not internal repo references

## Minimal `SKILL.md` Skeleton

```yaml
---
name: my-custom-skill
metadata:
  category: CloudObservabilityAndMonitoring
description: >-
  Use this skill to demonstrate best-practice authoring for a new Google Cloud product.
---

# My Custom Skill

## Use This Flow

```mermaid
flowchart LR
    Start["User request"] --> Auth["Authenticate"]
    Auth --> Action["Call API"]
    Action --> Result["Present findings"]

```

## Core API Constraints

* **Public Surface Only** — Use the official client library `<language-specific-library>` **or** the REST API `https://<service>.googleapis.com/v1`.
* **No internal RPCs** — Do not reference private endpoints.

## Prerequisites

1. Enable the `<service>` API:
   ```bash
   gcloud services enable <service>.googleapis.com --quiet
   ```

2. Authenticate with ADC:
   ```bash
   gcloud auth application-default login
   ```

3. Grant the least-privileged IAM role, e.g., `roles/<service>.viewer`.

## Quick Client Library Example (Python)

```bash
python3 -m pip install --upgrade google-cloud-<service>

```

```python
from google.cloud import <service>_v1

client = <service>_v1.<Service>Client()

# Example call – replace with real request

response = client.list_<resources>(parent="projects/PROJECT_ID")
print(response)

```

## Reference Directory

- [Core Concepts](references/core-concepts.md)
- [REST Usage](references/rest-usage.md)
- [IAM & Security](references/iam-security.md)

## Authoritative References

- Official product overview — https://cloud.google.com/<service>/docs/overview
- Python client library — https://pypi.org/project/google-cloud-<service>/

```

## Example Reference File Structure

Create `references/client-library-usage.md` for reusable code patterns:

```markdown

# Client Library Usage

The `<service>` client library provides idiomatic methods for every REST verb.

| Operation | Python client method | Example |
|-----------|---------------------|---------|
| List resources | `client.list_<resources>` | `client.list_instances(parent="projects/PROJECT_ID")` |
| Get a single resource | `client.get_<resource>` | `client.get_instance(name="projects/PROJECT_ID/locations/us-central1/instances/INSTANCE_ID")` |
| Create a resource | `client.create_<resource>` | `client.create_instance(parent=parent, instance=instance)` |
| Delete a resource | `client.delete_<resource>` | `client.delete_instance(name=instance_name)` |

All calls respect application-default credentials and automatically handle pagination.

```

## Contribution Workflow

As documented in [`CONTRIBUTING.md`](https://github.com/google/skills/blob/main/CONTRIBUTING.md) at the repository root, external contributions are **not currently accepted**. For internal Google teams:

1. Fork the repository in the internal Google Workspace
2. Edit or add [`SKILL.md`](https://github.com/google/skills/blob/main/SKILL.md) and accompanying reference files
3. Run the internal "Agent Skills Program" validation suite (checks required sections, metadata correctness, and forbidden API references)
4. Submit an internal change request for review and approval

## Testing and Validation Checklist

Before submitting a custom skill for google/skills, verify:

- **Static lint** — Markdown parses without errors; front-matter delimiters are correct
- **Live execution** — Code snippets run successfully with Application Default Credentials
- **Permission verification** — The specified IAM role covers all API calls in examples

## Summary

- **Structure skills as [`SKILL.md`](https://github.com/google/skills/blob/main/SKILL.md) with YAML front matter** and eight required sections
- **Restrict API usage to public surfaces only** — official client libraries or documented REST endpoints
- **Enforce least-privilege IAM** with specific roles listed in Prerequisites
- **Organize deep documentation in `references/`** and link relatively
- **Follow contribution workflow** per [`CONTRIBUTING.md`](https://github.com/google/skills/blob/main/CONTRIBUTING.md) (internal teams only)
- **Validate all code** through static linting and live sandbox execution

## Frequently Asked Questions

### What file structure must a custom skill for google/skills follow?

Every skill requires a [`SKILL.md`](https://github.com/google/skills/blob/main/SKILL.md) file at `skills/<category>/<skill-name>/SKILL.md` with YAML front matter and standardized sections, plus optional `references/*.md` files for supplementary documentation.

### Can external contributors submit new skills to google/skills?

No. According to [`CONTRIBUTING.md`](https://github.com/google/skills/blob/main/CONTRIBUTING.md), external contributions are not accepted; only internal Google teams may submit skills through the internal change request process.

### How does the Google Skills runtime handle authentication failures?

Skills must implement sandbox-friendly fallback behavior: when authentication fails or APIs are unavailable, display static example code and curated findings rather than retrying or failing.

### What IAM roles should custom skills specify?

Always default to the least-privileged role that permits required operations—typically `viewer`, `evaluationAdmin`, or `admin`—and explicitly document the chosen role in the Prerequisites section.