google / google/skills

Document registry default vs revision actually loaded by an agent

Open Beginner friendly
#183 0 comments 0 reactions 0 assignees View on GitHub
enhancement
Dominant language
Python
Stars
20k
Forks
1.6k
Avg merge
3d 13h
Merged PRs (30d)
1

Description

## Problem

The Skill Registry docs correctly distinguish a mutable `Skill` from immutable `Skill revision` resources, and the bundled skill can upload/update, monitor the LRO, list revisions, and fetch one revision.

What is still easy for an operator (or an agent using this skill) to overclaim is the last boundary:

- upload/update operation succeeded;
- revision exists;
- revision is now the registry default;
- a particular agent run actually loaded that revision.\n
Those are different facts. A long-lived or offline agent may still have an older revision cached even after the registry default changes. Today `references/manage-skills.md` stops after “monitor the operation,” while `references/query-skills.md` documents revision lookup separately, so there is no end-to-end verification recipe and no warning that registry state is not runtime consumption evidence.

## Requested documentation/workflow

Please add a small read-only **verify revision state** recipe to `skills/cloud/agent-platform-skill-registry`, for example:

1. monitor the upload/update LRO to terminal success;
2. `get` the mutable skill and record the returned default revision resource;
3. `get-revision` for that immutable revision and record its full resource name/metadata;
4. report these as `operation_succeeded` and `registry_default_revision`;
5. explicitly report `runtime_loaded_revision: unknown` unless the consuming agent/loader supplies that evidence.

A helper command is optional; a documented sequence plus an example JSON result would already close the ambiguity. It should avoid raw skill contents or local paths in the proof record.

## Falsification / acceptance test

A useful test is:

1. agent A loads revision `r1`;
2. an operator updates the skill and the registry default becomes `r2`;
3. agent A continues without a reload;
4. run the verification recipe.

The result must be able to say “registry default is `r2`; runtime-loaded revision is unknown (or `r1` if the loader reports it)” rather than implying that successful publication/defaulting proves consumption.

This would make the existing lifecycle guidance safer without requiring tracing or a new registry API.

Contributor guide

Open the contributing guide

Research direction

Read the existing lifecycle guidance in skills/cloud/agent-platform-skill-registry/references/manage-skills.md and revision lookup guidance in references/query-skills.md. Add a read-only verification recipe and example JSON covering operation success, the registry default revision, and runtime_loaded_revision as unknown unless loader evidence exists. Validate it against the r1/r2 cached-agent scenario without including raw skill contents or local paths.

Written by the indexing model from the issue text.

Assessment

Tech stack
google-cloud
Domain
cloud, documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
78/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.