[nicknisi]

Why

Review on workos/workos#77885 caught a gap in #62. workos.com serves the latest release's index.json, and the index listed archives by relative name, so they resolved to the latest release's archives too. An index fetched or cached just before a release could pair with the next release's archives and fail its digest check.

• Each archive URL in the index now points at the release that built it, for example https://github.com/workos/skills/releases/download/v0.9.1/workos.tar.gz. Release assets don't change, so any copy of the index, however old, resolves to archives that match its digests.
• The release URL is now a required argument, so a later workflow edit can't quietly fall back to relative URLs.
• The worker on workos.com then only needs to serve index.json; #77885 drops its archive route to match.

Proof

• Served an index built with absolute URLs from a local server, with the archives under a separate /releases/download/v9/ path. npx skills add http://localhost:8799 --skill workos workos-widgets -a claude-code -y read the index from /.well-known/agent-skills/ and downloaded both archives from the release path, installing all 76 files.

Not proven

The workflow change runs on the next release. To fix the live v0.9.0 index before 0.9.1, dispatch "Publish well-known skills" with tag: v0.9.0 after merging. main will still have the v0.9.0 skill content then, so the regenerated index points at the v0.9.0 archives and their digests match.

[greptile-apps]

Confidence Score: 5/5

[Medium impact] The PR appears safe to merge.

Summary

The discovery index now points at each release’s own archives, so a cached index keeps its matching downloads after another release.

• The skills index sends clients to its release’s own archives.

Acknowledged by nicknisi: updating the live v0.9.0 index requires a manual workflow run after merging. The PR intentionally leaves that step separate.

Review checks were limited to reading code; tests were not run.

Diagram

sequenceDiagram
  participant Client
  participant Workos as workos.com
  participant Release as GitHub release vX
  Client->>Workos: Fetch index.json
  Workos-->>Client: Index with archive URLs for vX
  Note over Workos: A newer release may become latest
  Client->>Release: Download archives for vX
  Release-->>Client: Archives matching the index digests

Loading

_{Reviews (1) · Last reviewed commit: "fix: point the well-known index at each ..." · Reviewed by Greptile}