Skip to content

feat(agents): load Skillist skills into Cloudflare Agents - #199

Open
blakebauman wants to merge 1 commit into
mainfrom
feat/cloudflare-skill-source
Open

blakebauman wants to merge 1 commit into
mainfrom
feat/cloudflare-skill-source

Conversation

@blakebauman

Copy link
Copy Markdown
Collaborator

What

Adds @skillist/agents, a SkillSource for Cloudflare's experimental Agent Skills API in the Agents SDK (agents/skills, targeting agents 0.33.x). It plugs into Think's getSkills() or loadSkillCatalog() the same way the SDK's built-in workspace(), r2() and manifest() sources do:

#skills = skillist({ skills: ["acme/release-notes", "acme/pdf-tools@1.2.0"] });
getSkills() { return [this.#skills]; }

How it works

It reads the existing public GET /{org}/{repo}/bundle route, which is already a KV-meta + R2 hot path with a versionId ETag. No API changes.

  • Fresh on the next turn. Think calls list() before every turn. Each call revalidates unpinned refs with If-None-Match: an unchanged skill gets a 304, and a new publish reaches the agent on its next turn.
  • Pinned refs (@1.2.0) are fetched once and never rechecked.
  • Fail-closed. A 404 (missing, private or retracted) drops the skill at once and never falls back to a cached copy.
  • Stale-if-error. A network error or 5xx keeps serving the last good copy. If every ref fails and nothing is cached, list() returns SkillSourceError, and the SDK catalog keeps its previous listing.
  • Version-consistent reads. readResource() serves files from the bundle fetched at the last list().
  • Encoding. Each resource's encoding follows Skillist's bundle rule: binary assets are base64, everything else is text.

Also in this PR

  • publish-packages.yml gets a publish step for @skillist/agents, after skill-format, which it depends on.
  • CLAUDE.md lists the new package in the monorepo layout.

Before the first publish

@skillist/agents doesn't exist on npm yet, so trusted publishing can't be configured for it. The first release needs a manual npm publish (a dry-run pnpm pack produced the right tarball: @skillist/skill-format: 0.3.0, peer agents: ^0.33.0). Then add the trusted publisher on npmjs.com. Until that's done, the new step will fail when the workflow runs.

Not in scope

  • Private and org-only skills. These need an authenticated bundle route.
  • Scripts. Skillist's CLI-style scripts don't fit the SDK's experimental skills.runner() contract. The README documents this.
  • Activation telemetry. The SDK activates skills on the client, so the server only sees bundle fetches.

Testing

  • 13 unit tests against a fake delivery server, including one through the SDK's own loadSkillCatalog().
  • pnpm check, pnpm typecheck and pnpm check:catalog pass.
  • Live smoke test against skillist.dev with skillist/cloudflare-deploy: first list ~600 ms, revalidation 55 ms (304), a missing ref skipped with one warning, and a reference file read through the catalog.

🤖 Generated with Claude Code

Add @skillist/agents, a SkillSource for the Agents SDK's experimental
agents/skills API. skillist({ skills: ["org/repo", "org/repo@1.2.0"] })
plugs into Think's getSkills() or loadSkillCatalog() and reads skills
from the public /{org}/{repo}/bundle delivery route.

Each list() revalidates unpinned refs with If-None-Match against the
versionId ETag, so an unchanged skill costs a KV read and a 304 while a
new publish reaches the agent on its next turn. A 404 (missing, private,
or retracted) drops the skill immediately; transport errors keep serving
the last good copy. Resource reads come from the bundle fetched at the
last list, so the model reads the version it was shown.

Public skills only for now. Also adds the package to the npm publish
workflow; its first release needs a manual publish to set up trusted
publishing.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant