Skip to content

Document registry default vs revision actually loaded by an agent #183

Description

@caioribeiroclw-pixel

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions