feat(skills): publish an Agent Skills discovery index

[nibzard]

Problem

isitagentready.com scores checks.discovery.agentSkills as fail: no index at /.well-known/agent-skills/index.json.

Unlike most of the other discovery fails, this one describes something Steel genuinely has. Five skills ship through steel-dev/skills and are documented under /overview/skills, but an agent can only find them by reading the docs or already knowing the repo name.

Change

Publish the index defined by the Cloudflare Agent Skills Discovery RFC (schema 0.2.0), generated from the upstream catalog:

{
  "$schema": "https://schemas.agentskills.io/discovery/0.2.0/schema.json",
  "skills": [
    {
      "name": "steel-browser",
      "type": "skill-md",
      "description": "Skill for agent-driven web workflows using Steel cloud browsers and API tools.",
      "url": "https://raw.githubusercontent.com/steel-dev/skills/35bf2783.../steel-browser/SKILL.md",
      "digest": "sha256:9dee3ac2724d64b37d1b38c56950d84fe821e575faaceaa91f049aa04f65af49"
    }
  ]
}

All five skills are included, beta ones too, since the docs already advertise them.

Artifact URLs are pinned to a commit, not to main. The schema requires a digest over the artifact's raw bytes. Against a branch URL, any upstream edit to a SKILL.md would silently invalidate every digest we publish, and a client that verifies would reject the artifact. Pinned, the URL and digest stay consistent permanently, and each build re-pins to whatever main holds at that moment.

Generated at build, not committed. It runs inside bun run generate alongside llms.txt and is gitignored. If GitHub is unreachable the generator warns and skips rather than failing the build: a docs deploy should not hinge on it, and an absent index is honest where a stale one would not be.

Verification

Six unit tests on the builder, written failing first, covering the schema URI, one entry per skill, commit pinning, the digest, and rejection of invalid names, over-long descriptions and an empty catalog.

The digest was checked independently of the code that wrote it, by fetching the pinned URL and hashing it:

$ curl -sL .../35bf2783.../steel-browser/SKILL.md | shasum -a 256
9dee3ac2724d64b37d1b38c56950d84fe821e575faaceaa91f049aa04f65af49
$ jq -r '.skills[0].digest' public/.well-known/agent-skills/index.json
sha256:9dee3ac2724d64b37d1b38c56950d84fe821e575faaceaa91f049aa04f65af49

Served over HTTP as 200 application/json with all five entries. Full suite 218 pass / 0 fail, bun run check and bun run typecheck clean.

Not in this PR

auth.md was on the shortlist until we checked what it actually is: WorkOS's agent registration protocol, where an agent signs up for a service on a user's behalf and is issued credentials. Steel has no such flow, so publishing it would advertise a capability that does not exist. Same reasoning retires oauthDiscovery, oauthProtectedResource, mcpServerCard and a2aAgentCard: those checks should keep failing until the underlying thing exists.

apiCatalog remains open and is real work rather than a stub: the generated OpenAPI spec is gitignored and unreachable (docs.steel.dev/openapi.json 404s), so publishing the spec is the valuable half and the RFC 9727 linkset follows from it.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview	Jul 30, 2026 11:38am