Register skills

In Agent Registry, a skill represents a standalone, executable capability that an agent can have. It contains instructions in a SKILL.md file, code scripts, and assets that extend an agent's reasoning. By registering standalone skills in Agent Registry, you can centrally govern, version, and share capabilities across your organization's AI agents.

Google-created skills are visible immediately when you set up Agent Registry. This document explains how to manually register your own standalone skills in Agent Registry.

Before you begin

Before you start, set up Agent Registry. You need the project ID to perform these tasks.

To use the Google Cloud CLI commands in this document, make sure you have set up your gcloud CLI environment.

Required roles

To get the permissions that you need to register skills in Agent Registry, ask your administrator to grant you the Agent Registry User (roles/agentregistry.user) IAM role on the project. For more information about granting roles, see Manage access to projects, folders, and organizations.

You might also be able to get the required permissions through custom roles or other predefined roles.

Ingestion payload constraints

To register a skill, you must package the capability's source files into a ZIP archive. The archive must include a SKILL.md instruction file at its root. During the ingestion phase of the skill registration process, Agent Registry validates that the payload complies with the following constraints:

  • ZIP archive size: Maximum compressed archive size of 500 KB.
  • Total uncompressed payload size: Maximum uncompressed size of 10 MB.
  • Individual file size: Maximum uncompressed size of 1 MB per file.
  • Deep nesting: Maximum directory nesting depth of 8 levels.
  • Specification compliance: The SKILL.md file must contain a valid YAML front matter section defining the name, description, and metadata as defined in the Agent Skills Specification.

Register a skill

Google-created skills are visible immediately when you set up Agent Registry. However, you can also manually register your own skills. Each skill has a default revision and can contain multiple versioned skill revisions.

To register your own skills, you create a logical skill container and upload the initial revision payload in a single operation. Later, you can manage your registered skills and their subsequent skill revisions.

The skills that you or other users create are automatically assigned to the default private publisher to avoid name collisions with Google-created skills. For that reason, the published ID of a particular skill becomes private-SKILL_ID. You can't specify a custom publisher during skill creation.

For example, if you create a skill with the ID workspace-tools, the resource name is created as projects/PROJECT_ID/locations/LOCATION/skills/private-workspace-tools. The logical Uniform Resource Name (URN) is assigned as urn:skill:projects-PROJECT_NUMBER:locations:LOCATION:private-workspace-tools. You must use this published ID (private-workspace-tools) for all subsequent skill operations.

To register a skill, follow these steps:

Console

  1. In the Google Cloud console, go to the Agent Registry page:

    Go to Agent Registry

  2. From the project picker, select your Google Cloud project.

  3. Select the Skills tab.

  4. In the Skills tab, the Add skill button displays two options. You can choose one of the following:

    • Add skill: Create a new skill container in the registry. You can optionally upload a skill package to create the first revision.
    • Import skill: Onboard a new custom skills package by uploading a ZIP bundle containing your code or prompt instructions (SKILL.md) file.

  5. In the Create skill or Import skill panel, specify the following details:

    • Display name: Enter a user-friendly name for the skill.
    • Description: Enter a brief summary explaining the skill capabilities.
    • Location: Select the geographic region, for example, global, us, or eu.

  6. In the Payload source section, choose one of the following:

    • File: Drag your packaged skill ZIP file, or browse your local directory.

    • Bucket: Enter the path to your ZIP archive stored in a Cloud Storage bucket, in the format gs://BUCKET_NAME/SKILL_PACKAGE.zip.

  7. Click Create.

Your skill is created. For all subsequent skill operations, refer to your skill as private-SKILL_ID, as displayed in the Google Cloud console.

gcloud

To register a skill and upload its initial payload, you can upload either a local ZIP file or import a package stored in Cloud Storage.

Replace the following:

  • SKILL_ID: The resource ID of the skill, for example, workspace-docs-skill. After creation, the registry automatically prepends the private- prefix. You must use the prefixed ID in all subsequent skill commands, for example private-workspace-docs-skill.
  • PROJECT_ID: The project ID.
  • LOCATION: The geographic region, for example, global, us, or eu.
  • DISPLAY_NAME: A user-friendly name for the skill.

  • DESCRIPTION: A brief summary explaining the skill capabilities.

  • Upload a local ZIP file: To register a skill using a local ZIP payload:

    gcloud alpha agent-registry skills create SKILL_ID \
  --project=PROJECT_ID \
  --location=LOCATION \
  --display-name="DISPLAY_NAME" \
  --description="DESCRIPTION" \
  --payload="LOCAL_ZIP_PATH"

    Replace LOCAL_ZIP_PATH with the path to your packaged skill archive on your local machine, for example, ./workspace-docs-skill.zip.

  • Import from a Cloud Storage bucket: To register a skill using a ZIP archive hosted in a Cloud Storage bucket:

    gcloud alpha agent-registry skills create SKILL_ID \
  --project=PROJECT_ID \
  --location=LOCATION \
  --display-name="DISPLAY_NAME" \
  --description="DESCRIPTION" \
  --gcs-source-uri="gs://BUCKET_NAME/SKILL_PACKAGE.zip"

    Replace the following:

    • BUCKET_NAME: The Cloud Storage bucket name that contains the ZIP bundle.
    • SKILL_PACKAGE: The name of the skill package containing the skill payload.

REST

To create a skill with an initial revision inline:

HTTP method and URL

POST https://agentregistry.googleapis.com/v1alpha/projects/{project}/locations/{location}/skills?skillId={skillId}

Request JSON body (local file upload)

To create a skill by uploading local ZIP archive bytes directly, use the archiveUploadSource payload:

{
  "displayName": "DISPLAY_NAME",
  "description": "DESCRIPTION",
  "type": "SIMPLE",
  "targetState": "TARGET_STATE_ACTIVE",
  "initialRevision": {
    "archiveUploadSource": {
      "archiveContent": "BASE64_ZIP_BYTES"
    }
  }
}

Replace BASE64_ZIP_BYTES with the base64-encoded string representation of your local ZIP archive.

Request JSON body (import from Cloud Storage)

Alternatively, to create a skill using an archive stored in a Cloud Storage bucket, use gcsSource:

{
  "displayName": "DISPLAY_NAME",
  "description": "DESCRIPTION",
  "type": "SIMPLE",
  "targetState": "TARGET_STATE_ACTIVE",
  "initialRevision": {
    "gcsSource": {
      "uri": "gs://BUCKET_NAME/SKILL_PACKAGE.zip"
    }
  }
}

Replace the following:

  • BUCKET_NAME: The Cloud Storage bucket name that contains the ZIP bundle.
  • SKILL_PACKAGE: The name of the skill package containing the skill payload.

curl command (local file upload)

curl -X POST \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      -H "Content-Type: application/json" \
      -d '{
        "displayName": "DISPLAY_NAME",
        "description": "DESCRIPTION",
        "type": "SIMPLE",
        "targetState": "TARGET_STATE_ACTIVE",
        "initialRevision": {
          "archiveUploadSource": {
            "archiveContent": "$(base64 -w0 local_skill.zip)"
          }
        }
      }' \
      "https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/skills?skillId=SKILL_ID"

For a Cloud Storage bucket file upload, replace the request JSON body with the corresponding fields and values.

What's next