Generative AI Google Brain

agents-skill-registry-intro-skill-registry

3 min read

Intro to Skill Registry

Source notebook

Repo path: agents/skill-registry/intro_skill_registry.ipynb · Open on GitHub · intermediate

Introduces Skill Registry for creating, ingesting, registering, and semantically retrieving agent skills.

Summary

This notebook teaches how to use the Gemini Enterprise Agent Platform Skill Registry as a private repository for agent skills. It demonstrates creating a local SKILL.md package, registering it with the Vertex AI client, batch-ingesting skills from the google/skills GitHub repository, and retrieving relevant skills with semantic search.

Key code patterns

Initialize Agent Platform client

vertexai.init(project=PROJECT_ID, location=LOCATION)
 
client = vertexai.Client(
    project=PROJECT_ID,
    location=LOCATION,
)

Creates the central client used to manage Skill Registry resources.

Create a local skill package

local_skill_dir = "/tmp/sample_math_skill"
os.makedirs(local_skill_dir, exist_ok=True)
 
with open(os.path.join(local_skill_dir, "SKILL.md"), "w") as f:
    f.write(skill_md_content)

A skill package must contain a SKILL.md file with YAML frontmatter and instructions.

Register a local skill

skill = client.skills.create(
    display_name="Sample math skill",
    description="This skill provides functions to perform math calculations",
    config={
        "skill_id": user_skill_id,
        "local_path": "/tmp/sample_math_skill",
    },
)

Registers and indexes a local skill folder in the Skill Registry.

Parse skills from a repository

for root, dirs, files in os.walk(repo_dir):
    lower_files = {f.lower(): f for f in files}
    if "skill.md" in lower_files:
        dirs[:] = []
        name, description = parse_skill_md(filepath)
        skills.append(Skill(name, description, root))

Finds skill packages by locating SKILL.md files and extracting frontmatter metadata.

Semantic skill retrieval

response = client.skills.retrieve(
    query="firebase",
    config={"top_k": 2},
)
 
for retrieved in response.retrieved_skills:
    print(retrieved.skill_name)
    print(retrieved.description)

Uses natural-language semantic search to discover relevant registered skills.

Models & APIs used

  • APIs / services: Vertex AI, Agent Platform API, Gemini Enterprise Agent Platform
  • SDKs / libraries: vertexai, google-cloud-aiplatform, PyYAML

When to use this

Use this pattern when agents need runtime discovery of private, indexed skills from local packages or Git repositories.

Gotchas & caveats

  • Requires google-cloud-aiplatform==1.152.0 in the notebook.
  • The notebook says to ignore pip dependency errors.
  • Colab requires auth.authenticate_user().
  • The Agent Platform API must be enabled.
  • PROJECT_ID must be set or available from GOOGLE_CLOUD_PROJECT.
  • The notebook uses LOCATION=“us-central1”.
  • SKILL.md must include YAML frontmatter with name and description.
  • The GitHub download helper hardcodes the master branch.

Best practices

  • Use a mandatory SKILL.md file with YAML frontmatter and markdown instructions.
  • Make the skill name a unique identifier matching the skill package name.
  • Start the skill description in third person as a capability statement.
  • Use local_path so the SDK packages, compresses, uploads, provisions, and indexes the skill.
  • Use timestamped skill IDs to avoid collisions during registration.
  • Deduplicate imported skills by skill name.
  • Prune subdirectories after finding a SKILL.md to avoid deeper recursion within a skill folder.
  • Retrieve skills with top_k to limit semantic search results.

Graph View

Backlinks