feat: add agent-skills discovery release pipeline

[gregnr]

Implements part 1 of Cloudflare's agent-skills discovery RFC - builds per-skill archives and an index.json that are meant to live in /.well-known/agent-skills/.... Part 2 is getting our www site to pull these release artifacts at build time and serve them from https://supabase.com/.well-known/agent-skills/....

Artifacts live in GitHub releases within this repo. Releases will auto-generate upon any change to ./skills in main. Since each skill has their own independent version, these bundled releases just use the current date+commit hash as the tag.

GitHub Release (e.g. 2026-04-14-a3f9c2)
├── index.json               # discovery index per RFC v0.2.0
├── supabase.tar.gz
│   ├── SKILL.md
│   └── references/
└── supabase-postgres-best-practices.tar.gz
    ├── SKILL.md
    └── references/

[Rodriguespn]

Thanks for taking care of this @gregnr! I went through the PR and also compared our build-release.ts with jonathanhefner/agentskills-build-for-well-known — the GitHub Action Jonathan built for this (referenced in agentskills/agentskills#254). The Action isn't published yet (no releases/tags, hasn't been transferred to the agentskills org), so we can't use it directly. But it has a few improvements worth pulling into our script so we're closer to spec and aligned for when it ships.

Suggested improvements to build-release.ts

1. Deterministic archives (source)

Our current tar czf includes timestamps, uid/gid, and gzip header timestamps — so identical skill content produces different hashes on each build. The Action fixes this with a two-step process that zeroes all metadata:

// Two-step: uncompressed tar with zeroed metadata, then gzip without header timestamp
await execFileAsync("tar", [
  "--mtime=@0",
  "--owner=0",
  "--group=0",
  "--numeric-owner",
  "--no-recursion",
  "-cf",
  tarPath,
  "-C",
  skillDir,
  ...sortedEntries,
]);

// gzip -n: omit original name and timestamp from header
// gzip -f: force overwrite, replaces tarPath with tarPath.gz
await execFileAsync("gzip", ["-nf", tarPath]);

This means digests only change when content actually changes, which is the whole point of the digest field for client-side caching.

2. File listing with exclude patterns (walker, exclude matching)

Our archives include everything in the skill directory. The Action walks the dir, applies .gitignore-style excludes, and returns sorted paths. It also collects parent directories (here) since tar with --no-recursion needs explicit dir entries:

// Patterns without "/" match basenames at any depth; with "/" match relative paths
function matchesExclude(relPath: string, patterns: string[]): boolean {
  for (const pattern of patterns) {
    const target = pattern.includes("/") ? relPath : relPath.split("/").pop()!;
    if (matchesGlob(target, pattern)) return true;
  }
  return false;
}

// Default excludes
const DEFAULT_EXCLUDES = [".git", ".gitignore", ".gitattributes", ".DS_Store",
  "Thumbs.db", ".vscode", ".idea", "*.swp", ".*.swp", "*~", ".*~"];

Not a problem today since our skill dirs are clean, but good hygiene.

3. Auto-detect skill-md vs archive type (source)

We currently hardcode type: "archive" for everything. Both our skills today have references/, so it's correct, but per the spec single-file skills should use type: "skill-md". The Action checks after listing files:

if (isSingleFile) {
  // Single-file skill: copy SKILL.md directly
  type = "skill-md";
  const destDir = join(outputDir, skill.name);
  await mkdir(destDir, { recursive: true });
  artifactPath = join(destDir, "SKILL.md");
  await copyFile(skillMdPath, artifactPath);
  url = `${skill.name}/SKILL.md`;
} else {
  // Multi-file skill: create archive
  type = "archive";
  artifactPath = join(outputDir, `${skill.name}.tar.gz`);
  url = `${skill.name}.tar.gz`;
  await createTarGz(skill.directory, files, artifactPath);
}

4. Relative URLs instead of absolute (skill-md, archive)

We emit /.well-known/agent-skills/supabase.tar.gz (path-absolute). The Action emits supabase.tar.gz (relative). Both are valid per RFC 3986 Section 5, but relative is more portable — the consumer (supabase/supabase#44878) controls the serving path.

5. Validate both name and description in frontmatter (source)

We only validate description. The Action validates both fields exist and are strings:

function parseFrontmatter(content: string, filePath: string): SkillFrontmatter {
  const { data } = matter(content);

  if (!data.name || typeof data.name !== "string") {
    throw new Error(`Missing or invalid 'name' in frontmatter: ${filePath}`);
  }
  if (!data.description || typeof data.description !== "string") {
    throw new Error(`Missing or invalid 'description' in frontmatter: ${filePath}`);
  }

  return { name: data.name, description: data.description };
}

What's good as-is

• The release workflow and {DATE}-{SHA} tagging — the Action doesn't handle releases, so our workflow stays either way.
• The overall approach of building artifacts in this repo and consuming them from www at build time is solid and matches how the RFC expects things to work.

Happy to pick up any of these changes if you want!

[gregnr]

Closing in favor of #77.