Manage skills

After registering a standalone skill in Agent Registry, you can view its details, update its description, override its active revision pointer (default_revision), manage its lifecycle states, or delete it from Agent Registry. You can also list and view Google-created skills, which are visible immediately when you set up Agent Registry.

This document explains how to perform these administrative tasks.

Before you begin

Before you start, set up Agent Registry and register a standalone skill. 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 manage 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.

List and view skills

You can browse all registered skills or search for specific capabilities:

Console

In the Google Cloud console, go to the Agent Registry page:
Go to Agent Registry
Select the Skills tab.
Review the list of skills. You can filter the display using the Location or Status menus.
Click any skill name to open its Skill Details page, which displays the name, description, active version, skill URN, last updated, custom metadata, and revision history.

gcloud

To list all skills in a location:

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

To view details of a specific skill:

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

Replace the following:

SKILL_ID: The ID of the skill you want to review.
PROJECT_ID: The project ID.
LOCATION: The registry location.

REST

To retrieve the list of all skills:

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

To retrieve a single skill container:

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

Replace the following:

PROJECT_ID: The project ID.
LOCATION: The registry location.
SKILL_ID: The ID of the skill you want to review.

Update skill metadata or default revision

You can modify a skill's display name, description, or manually change the default revision pointer to deploy a different version. To create new skill revisions, see Manage skill revisions.

To update skill metadata or the default revision of a particular skill, follow these steps:

Console

In the Google Cloud console, go to the Agent Registry page:
Go to Agent Registry
Select the Skills tab.
Review the list of skills. You can filter the display using the Location or Status menus.
Click any skill name to open its Skill Details page, which displays the name, description, active version, skill URN, last updated, custom metadata, and revision history.
Choose between the following options:
- Update skill metadata:
  1. Click Edit.
  2. In the Edit skill panel, update the display name or description of your skill.
  3. Click Save.
- Update the default revision:
  1. Locate the Version history table.
  2. Find the revision you want to set as active.
  3. In the actions column, click Activate version.

gcloud

To update a skill's metadata:

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

To update a skill's default serving revision:

gcloud alpha agent-registry skills update SKILL_ID \
  --project=PROJECT_ID \
  --location=LOCATION \
  --default-revision="projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions/REVISION_ID"

Replace the following:

SKILL_ID: The ID of the skill you want to update.
PROJECT_ID: The project ID.
LOCATION: The registry location.
DISPLAY_NAME: The updated display name.
DESCRIPTION: The updated description.
REVISION_ID: The ID of the skill revision you want to set as default.

REST

Send a PATCH request specifying the fields you want to update:

curl -X PATCH \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      -H "Content-Type: application/json" \
      -d '{
        "displayName": "DISPLAY_NAME",
        "description": "DESCRIPTION",
        "defaultRevision": "projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions/REVISION_ID"
      }' \
      "https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID?updateMask=displayName,description,defaultRevision"

Replace the following:

DISPLAY_NAME: The updated display name of the skill.
DESCRIPTION: The updated description of the skill.
PROJECT_ID: The project ID.
LOCATION: The registry location.
SKILL_ID: The ID of the skill you want to update.
REVISION_ID: The ID of the skill revision you want to activate.

Manage skill lifecycle states

To control how a skill is resolved at runtime, you can change the skill's target state:

Draft: The skill is in its initial creation or development phase. It isn't served at runtime, and payload downloads are blocked. You can modify the skill configuration and payloads freely in this state before promoting the skill to the Active target state.
Active: The skill is served and fully resolvable.
Disabled: Resolving the skill fails immediately, and downloads are blocked. Unlike the Decommissioned state, you can re-enable the skill later, which means returning it to the Active target state.
Deprecated: The skill remains loadable but returns warning headers indicating it will be sunset.
Decommissioned: The skill is permanently deactivated, no longer served, and cannot be reverted back to Active or any other state. A skill can be decommissioned only after it has already been deprecated. Provide sufficient time to migrate before decommissioning the skill. This is a terminal state, recommended to be used with extreme caution.

To transition a skill's lifecycle state:

Console

In the Google Cloud console, go to the Agent Registry page:
Go to Agent Registry
Select the Skills tab.
Review the list of skills. You can filter the display using the Location or Status menus.
Click any skill name to open its Skill Details page, which displays the name, description, active version, skill URN, last updated, custom metadata, and revision history.
Use the status control buttons to transition the target state. The buttons that the page displays depend on the current state of the skill, for example, Enable, Disable, Deprecate, or Decommission.

gcloud

Update the skill container with the --target-state flag:

gcloud alpha agent-registry skills update SKILL_ID \
  --project=PROJECT_ID \
  --location=LOCATION \
  --target-state=DISABLED

Allowed values for the target state are:

DRAFT
ACTIVE
DISABLED
DEPRECATED
DECOMMISSIONED.

REST

Send a PATCH request specifying the targetState in the body and in the update mask:

curl -X PATCH \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      -H "Content-Type: application/json" \
      -d '{
        "targetState": "TARGET_STATE_DISABLED"
      }' \
      "https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID?updateMask=targetState"

Allowed values for the target state are:

TARGET_STATE_DRAFT
TARGET_STATE_ACTIVE
TARGET_STATE_DISABLED
TARGET_STATE_DEPRECATED
TARGET_STATE_DECOMMISSIONED.

Delete a skill

Deleting a skill container permanently deletes the skill container and all associated immutable SkillRevision version history. Agents attempting to resolve the deleted skill URN fail at runtime.

Console

In the Google Cloud console, go to the Agent Registry page:
Go to Agent Registry
Select the Skills tab.
Review the list of skills. You can filter the display using the Location or Status menus.
Click the name of the skill you want to delete.
In the Skill Details page, click Delete.
In the confirmation dialog, enter DELETE and click Delete.

gcloud

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

REST

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

What's next

Learn how to upload new revisions and download packages.
Understand roles and permissions for governing skills.

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

Before you begin

Required roles

List and view skills

Console

gcloud

REST

Update skill metadata or default revision

Console

gcloud

REST

Manage skill lifecycle states

Console

gcloud

REST

Delete a skill

Console

gcloud

REST

What's next

Manage skills