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

The best practices for developing custom skills for google/skills include following the declarative 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)

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

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

   gcloud services enable <service>.googleapis.com --quiet

2. Authenticate with ADC:

   gcloud auth application-default login

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

Quick Client Library Example (Python)

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

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
• REST Usage
• IAM & Security

Authoritative References

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

## 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 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 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 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 (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 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, 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.

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