Document registry default vs revision actually loaded by an agent
- 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
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