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

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions