Merge pull request #320 from vercel-labs/zeejab/agent-skills-discovery-index

feat: ✨ publish Agent Skills discovery index

Author: ZeeJab

.github/workflows/agent-skills-discovery.yml

@@ -0,0 +1,49 @@
+name: Agent Skills Discovery
+
+on:
+  pull_request:
+    branches: [main]
+    paths:
+      - 'skills/**'
+      - 'scripts/build-discovery-index.mjs'
+      - '.github/workflows/agent-skills-discovery.yml'
+  push:
+    branches: [main]
+    paths:
+      - 'skills/**'
+      - 'scripts/build-discovery-index.mjs'
+      - '.github/workflows/agent-skills-discovery.yml'
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - run: npm ci --ignore-scripts
+      - run: node scripts/build-discovery-index.mjs https://example.com/skills
+
+  publish:
+    if: github.event_name == 'push'
+    needs: validate
+    concurrency:
+      group: agent-skills-discovery-publish
+      cancel-in-progress: true
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    env:
+      GH_TOKEN: ${{ github.token }}
+      RELEASE_TAG: agent-skills-${{ github.sha }}
+    steps:
+      - uses: actions/checkout@v4
+      - run: npm ci --ignore-scripts
+      - run: node scripts/build-discovery-index.mjs "https://github.com/${{ github.repository }}/releases/download/${RELEASE_TAG}"
+      - run: |
+          gh release view "$RELEASE_TAG" >/dev/null 2>&1 ||
+            gh release create "$RELEASE_TAG" --draft --target "$GITHUB_SHA" \
+              --title "Agent Skills ${{ github.sha }}" \
+              --notes "Automated Agent Skills discovery release for ${{ github.sha }}."
+          gh release upload "$RELEASE_TAG" dist/* --clobber
+          gh release edit "$RELEASE_TAG" --draft=false --latest

.gitignore

@@ -1,3 +1,5 @@
 .DS_Store
 .vercel
 .env*.local
+dist
+node_modules

README.md

@@ -215,6 +215,17 @@ Review this React component for performance issues
 Help me optimize this Next.js page
 ```
 
+## Discovery index
+
+Every change to a skill on `main` publishes an immutable GitHub release with
+an Agent Skills discovery index and one artifact per skill. Build the same
+artifacts locally with:
+
+```bash
+npm ci --ignore-scripts
+node scripts/build-discovery-index.mjs https://example.com/skills
+```
+
 ## Skill Structure
 
 Each skill contains:

package-lock.json

@@ -0,0 +1,8 @@
+{
+  "name": "@vercel-labs/agent-skills",
+  "private": true,
+  "type": "module",
+  "dependencies": {
+    "yaml": "2.9.0"
+  }
+}

package.json

@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+
+import { createHash } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import {
+  mkdirSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { join } from 'node:path';
+import { parse } from 'yaml';
+
+const schema = 'https://schemas.agentskills.io/discovery/0.2.0/schema.json';
+const baseUrl = process.argv[2];
+const outputDirectory = 'dist';
+const archiveEnvironment = {
+  ...process.env,
+  GIT_AUTHOR_DATE: '2000-01-01T00:00:00Z',
+  GIT_AUTHOR_EMAIL: 'agent-skills@vercel.com',
+  GIT_AUTHOR_NAME: 'Agent Skills',
+  GIT_COMMITTER_DATE: '2000-01-01T00:00:00Z',
+  GIT_COMMITTER_EMAIL: 'agent-skills@vercel.com',
+  GIT_COMMITTER_NAME: 'Agent Skills',
+};
+
+if (!baseUrl) {
+  throw new Error(
+    'Usage: node scripts/build-discovery-index.mjs <artifact-base-url>',
+  );
+}
+
+const readMetadata = (directory) => {
+  const path = `skills/${directory}/SKILL.md`;
+  const source = execFileSync('git', ['show', `HEAD:${path}`], {
+    encoding: 'utf8',
+  });
+  const frontmatter = source.match(/^---\r?\n([\s\S]*?)\r?\n---/)?.[1];
+  if (!frontmatter) throw new Error(`Missing frontmatter in ${path}`);
+
+  let metadata;
+  try {
+    metadata = parse(frontmatter);
+  } catch (error) {
+    throw new Error(`Invalid frontmatter in ${path}`, { cause: error });
+  }
+
+  if (!metadata || typeof metadata !== 'object') {
+    throw new Error(`Invalid frontmatter in ${path}`);
+  }
+
+  const { name, description } = metadata;
+  if (typeof name !== 'string' || typeof description !== 'string') {
+    throw new Error(`Missing name or description in ${path}`);
+  }
+
+  if (
+    name.length === 0 ||
+    name.length > 64 ||
+    !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name) ||
+    !description ||
+    description.length > 1024
+  ) {
+    throw new Error(`Invalid name or description in ${path}`);
+  }
+
+  return { name, description };
+};
+
+const createArchive = (directory) => {
+  const tree = execFileSync(
+    'git',
+    ['rev-parse', `HEAD:skills/${directory}`],
+    { encoding: 'utf8' },
+  ).trim();
+  const commit = execFileSync('git', ['commit-tree', tree], {
+    encoding: 'utf8',
+    env: archiveEnvironment,
+    input: 'Agent Skills archive\n',
+  }).trim();
+  const tar = execFileSync('git', ['archive', '--format=tar', commit]);
+  return execFileSync('gzip', ['-n', '-9', '-c'], { input: tar });
+};
+
+const createArtifact = (directory) => {
+  const entries = execFileSync(
+    'git',
+    ['ls-tree', '-r', `HEAD:skills/${directory}`],
+    { encoding: 'utf8' },
+  )
+    .trim()
+    .split('\n');
+  if (entries.some((entry) => !/^100(?:644|755) blob /.test(entry))) {
+    throw new Error(`Unsupported archive entry in skills/${directory}`);
+  }
+
+  const files = entries.map((entry) => entry.slice(entry.indexOf('\t') + 1));
+
+  if (files.length === 1 && files[0] === 'SKILL.md') {
+    return {
+      content: execFileSync('git', [
+        'show',
+        `HEAD:skills/${directory}/SKILL.md`,
+      ]),
+      extension: 'md',
+      type: 'skill-md',
+    };
+  }
+
+  return {
+    content: createArchive(directory),
+    extension: 'tar.gz',
+    type: 'archive',
+  };
+};
+
+rmSync(outputDirectory, { force: true, recursive: true });
+mkdirSync(outputDirectory);
+
+const directories = execFileSync(
+  'git',
+  ['ls-tree', '-d', '--name-only', 'HEAD:skills'],
+  { encoding: 'utf8' },
+)
+  .trim()
+  .split('\n');
+
+const skills = directories
+  .map((directory) => {
+    const metadata = readMetadata(directory);
+    const artifact = createArtifact(directory);
+    const filename = `${metadata.name}.${artifact.extension}`;
+    writeFileSync(join(outputDirectory, filename), artifact.content);
+
+    return {
+      ...metadata,
+      type: artifact.type,
+      url: `${baseUrl.replace(/\/$/, '')}/${filename}`,
+      digest: `sha256:${createHash('sha256')
+        .update(artifact.content)
+        .digest('hex')}`,
+    };
+  })
+  .sort((a, b) => a.name.localeCompare(b.name));
+
+if (new Set(skills.map(({ name }) => name)).size !== skills.length) {
+  throw new Error('Skill names must be unique');
+}
+
+writeFileSync(
+  join(outputDirectory, 'index.json'),
+  `${JSON.stringify({ $schema: schema, skills }, null, 2)}\n`,
+);
+
+console.log(`Published ${skills.length} skills to ${outputDirectory}`);