Manage skill revisions

In Agent Registry, skill revisions let you version-control your standalone skills as immutable snapshots without disrupting active agents. Each skill has a default revision and can contain multiple versioned skill revisions. When you update the instructions or optional scripts of a skill, you can create, list, inspect, download, and delete skill revisions in Agent Registry. For information about updating the default revision of a skill, see Update skill metadata or default revision.

Before you begin

Set up Agent Registry.
Get the project ID for the governance project where Agent Registry is enabled.
Register a standalone skill.
To use the Google Cloud CLI commands in this document, set up your gcloud CLI environment.

Required roles

To get the permissions that you need to manage skill revisions in Agent Registry, ask your administrator to grant you the following IAM roles on the governance project where Agent Registry is enabled:

List, view, and download skill revisions: Agent Registry API Viewer (roles/agentregistry.viewer)
Create, update, and delete skill revisions: Agent Registry User (roles/agentregistry.user)
Manage skill revisions and other Agent Registry resources: Agent Registry API Editor (roles/agentregistry.editor)

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.

Other Agent Registry roles might also include the permissions required to view, download, create, update, and delete skill revisions. For more information, see Agent Registry roles and permissions.

Create a skill revision

Creating a new revision uploads a new ZIP payload to the existing skill container. When validation succeeds, the revision enters the Active state. To serve the new revision as the default revision for the skill, update the default revision of the skill to point to the new active revision. Only revisions in the Active state can be downloaded.

For information about pricing and feature costs for skills, see Agent Registry pricing.

The maximum ZIP file size of a skill revision is 500 KB.

Console

In the Google Cloud console, go to the Agent Registry page:
Go to Agent Registry
Select the Skills tab, and click the name of your skill.
In the Skill Details page, locate the Version history table.
Click Add version.
In the Add version panel, choose one of the following options:
- File: upload the package or ZIP file containing your SKILL.md instructions file and optional scripts. You can click Browse to find your file in your local environment.
- Bucket: provide a gs://... Cloud Storage URI containing a valid ZIP bundle. You can click Browse to find your file in your Cloud Storage buckets.
  
  Important: Before Agent Registry can access your skill files, you must grant its service agent access to the ZIP archive in your Cloud Storage bucket. The Agent Registry service agent uses the following format: service-PROJECT_NUMBER@gcp-sa-agentregistry.iam.gserviceaccount.com. If this service agent doesn't exist in your project, create it for the Agent Registry API. For instructions, see Create and grant roles to service agents. The service agent requires the storage.objects.get permission on the Cloud Storage bucket containing your ZIP archive. For instructions on granting Identity and Access Management (IAM) permissions on bucket resources, see IAM for Cloud Storage.
Click Create.

The Skill Details page displays the skill revision in the Version history table.

gcloud

You can create a skill revision by uploading either a local ZIP file or importing a package stored in Cloud Storage.

Replace the following:

REVISION_ID: the ID you want to assign to the skill revision.
SKILL_ID: the ID of the skill you are using for the revision. For manually registered skills, include the private- prefix, such as private-my-skill.
PROJECT_ID: the project ID.
LOCATION: the registry location.
Upload a local ZIP file: to create a skill revision using a local ZIP payload, run the gcloud alpha agent-registry skills revisions create command:
```
gcloud alpha agent-registry skills revisions create REVISION_ID \
    --skill=SKILL_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --payload="LOCAL_ZIP_PATH"
```
Replace LOCAL_ZIP_PATH with the path to your packaged skill archive on your local machine.
Import from a Cloud Storage bucket: to create a skill revision using a ZIP archive hosted in a Cloud Storage bucket, run the gcloud alpha agent-registry skills revisions create command:
```
gcloud alpha agent-registry skills revisions create REVISION_ID \
    --skill=SKILL_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --gcs-source-uri="gs://BUCKET_NAME/SKILL_PACKAGE.zip"
```
Important: Before Agent Registry can access your skill files, you must grant its service agent access to the ZIP archive in your Cloud Storage bucket. The Agent Registry service agent uses the following format: service-PROJECT_NUMBER@gcp-sa-agentregistry.iam.gserviceaccount.com. If this service agent doesn't exist in your project, create it for the Agent Registry API. For instructions, see Create and grant roles to service agents. The service agent requires the storage.objects.get permission on the Cloud Storage bucket containing your ZIP archive. For instructions on granting IAM permissions on bucket resources, see IAM for Cloud Storage.

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

REST

To create a skill revision, send a POST request to the revisions collection. You can upload the ZIP payload directly or point to a Cloud Storage path.

Upload a local ZIP file: specify archiveUploadSource containing the base64-encoded ZIP bytes in the request body. You can use the inline base64 command in curl:

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{
        "archiveUploadSource": {
          "archiveContent": "'"$(base64 -w0 local_skill.zip)"'"
        }
      }' \
    "https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions?skillRevisionId=REVISION_ID"

Import from a Cloud Storage bucket: specify gcsSource in the request body pointing to your bucket path:

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{
        "gcsSource": {
          "uri": "gs://BUCKET_NAME/SKILL_PACKAGE.zip"
        }
      }' \
    "https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions?skillRevisionId=REVISION_ID"

Replace the following:

PROJECT_ID: the project ID.
LOCATION: the registry location.
SKILL_ID: the ID of the skill container. For manually registered skills, include the private- prefix, such as private-my-skill.
REVISION_ID: the ID you want to assign to this revision.
BUCKET_NAME: the Cloud Storage bucket name containing the ZIP.
SKILL_PACKAGE: the name of the ZIP package.

List and describe revisions

You can view the list of all revisions for a skill and inspect their metadata. If you want to update the default revision of a skill, see Update skill metadata or default revision.

To list and see details of a revision, follow these steps:

Console

In the Google Cloud console, go to the Agent Registry page:
Go to Agent Registry
Select the Skills tab, and click the name of your skill.
In the Skill Details page, locate the Version history table.
Review the version IDs, creation time, revision state, and available actions.

gcloud

To list all revisions for a skill, run the gcloud alpha agent-registry skills revisions list command:

gcloud alpha agent-registry skills revisions list \
    --skill=SKILL_ID \
    --project=PROJECT_ID \
    --location=LOCATION

To describe metadata of a specific revision, run the gcloud alpha agent-registry skills revisions describe command:

gcloud alpha agent-registry skills revisions describe REVISION_ID \
    --skill=SKILL_ID \
    --project=PROJECT_ID \
    --location=LOCATION

Replace the following:

SKILL_ID: the ID of the skill container. For manually registered skills, include the private- prefix, such as private-my-skill.
PROJECT_ID: the project ID.
LOCATION: the registry location.
REVISION_ID: the ID of the skill revision.

REST

To list revisions:

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions"

To get metadata for a single revision:

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions/REVISION_ID"

Replace the following:

PROJECT_ID: the project ID.
LOCATION: the registry location.
SKILL_ID: the ID of the skill container. For manually registered skills, include the private- prefix, such as private-my-skill.
REVISION_ID: the ID of the skill revision.

Download revision payload

You can download a specific revision's ZIP file payload for local verification or debugging.

To download the payload, both of the following conditions must be met:

Skill: the skill must be in the Active or Deprecated state. To change the skill's target state, see Manage skill lifecycle states.
Skill revision: the revision must be in the Active state. Revisions in Failed or Creating states can't be downloaded. To review the state of a skill revision, list and describe revisions.

To download the revision payload of an active revision, follow these steps:

Console

In the Google Cloud console, go to the Agent Registry page:
Go to Agent Registry
Select the Skills tab, and click the name of your skill.
In the Skill Details page, locate the Version history table.
Find the revision you want to download.
In the Actions column, click Download. The ZIP payload downloads to your local machine.

gcloud

To download a revision's archive payload, run the gcloud alpha agent-registry skills revisions download command and specify the destination path:

gcloud alpha agent-registry skills revisions download REVISION_ID \
    --skill=SKILL_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --destination="./skill_payload.zip"

Replace the following:

REVISION_ID: the ID of the skill revision to download.
SKILL_ID: the ID of the skill container. For manually registered skills, include the private- prefix, such as private-my-skill.
PROJECT_ID: the project ID.
LOCATION: the registry location.

REST

Send a GET request to the revision's resource URL adding the query parameter alt=media. You must use the -L flag with curl to follow HTTP redirect streams:

curl -L -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -o skill_payload.zip \
    "https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions/REVISION_ID?alt=media"

Replace the following:

PROJECT_ID: the project ID.
LOCATION: the registry location.
SKILL_ID: the ID of the skill container. For manually registered skills, include the private- prefix, such as private-my-skill.
REVISION_ID: the ID of the skill revision to download.

Delete a specific revision

Deleting a specific revision removes its ZIP payload and metadata history from Agent Registry.

Deleting individual revisions is typically restricted to administrators. If you delete the revision that is set as the skill's default revision, Agent Registry clears the defaultRevision pointer and transitions an Active skill to the Disabled state. To keep the skill active, update the default revision of the skill to point to another active revision before deleting the previous default revision.

To delete a specific revision, follow these steps:

Console

In the Google Cloud console, go to the Agent Registry page:
Go to Agent Registry
Select the Skills tab, and click the name of your skill.
In the Skill Details page, locate the Version history table.
Find the revision you want to delete.
In the Actions column, click Delete and confirm the action.

gcloud

To delete a revision, run the gcloud alpha agent-registry skills revisions delete command:

gcloud alpha agent-registry skills revisions delete REVISION_ID \
    --skill=SKILL_ID \
    --project=PROJECT_ID \
    --location=LOCATION

Replace the following:

REVISION_ID: the ID of the skill revision to delete.
SKILL_ID: the ID of the skill container. For manually registered skills, include the private- prefix, such as private-my-skill.
PROJECT_ID: the project ID.
LOCATION: the registry location.

REST

To delete a revision, send a DELETE request:

curl -X DELETE \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions/REVISION_ID"

Replace the following:

PROJECT_ID: the project ID.
LOCATION: the registry location.
SKILL_ID: the ID of the skill container. For manually registered skills, include the private- prefix, such as private-my-skill.
REVISION_ID: the ID of the skill revision to delete.

What's next

Learn how to explore verified publishers.
Understand quotas and limits for skill revisions.

Manage skill revisions Stay organized with collections Save and categorize content based on your preferences.

Before you begin

Required roles

Create a skill revision

Console

gcloud

REST

List and describe revisions

Console

gcloud

REST

Download revision payload

Console

gcloud

REST

Delete a specific revision

Console

gcloud

REST

What's next

Manage skill revisions