summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorZahra Jabini <zahra.arch@gmail.com>2026-08-21 14:55:25 -0400
committerGitHub <noreply@github.com>2026-08-21 14:55:25 -0400
commitdd089a8c752c966dee8bf0f27cb625ba193ffd9e (patch)
tree460483e099c480b51cf51bebba53f0564105cb0a
parentb8caa260a420a73042e35521de4b5c8baf6446cc (diff)
parent9da6e5ad92e7fd7292b779abf076bf5dbad783ac (diff)
Merge pull request #320 from vercel-labs/zeejab/agent-skills-discovery-indexagent-skills-dd089a8c752c966dee8bf0f27cb625ba193ffd9e
feat: ✨ publish Agent Skills discovery index
-rw-r--r--.github/workflows/agent-skills-discovery.yml49
-rw-r--r--.gitignore2
-rw-r--r--README.md11
-rw-r--r--package-lock.json27
-rw-r--r--package.json8
-rw-r--r--scripts/build-discovery-index.mjs154
6 files changed, 251 insertions, 0 deletions
diff --git a/.github/workflows/agent-skills-discovery.yml b/.github/workflows/agent-skills-discovery.yml
new file mode 100644
index 0000000..8a76c89
--- /dev/null
+++ b/.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
diff --git a/.gitignore b/.gitignore
index 64c214a..bdc1c6f 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,3 +1,5 @@
.DS_Store
.vercel
.env*.local
+dist
+node_modules
diff --git a/README.md b/README.md
index daecfea..04a1a5a 100644
--- a/README.md
+++ b/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:
diff --git a/package-lock.json b/package-lock.json
new file mode 100644
index 0000000..bf6a642
--- /dev/null
+++ b/package-lock.json
@@ -0,0 +1,27 @@
+{
+ "name": "@vercel-labs/agent-skills",
+ "lockfileVersion": 3,
+ "requires": true,
+ "packages": {
+ "": {
+ "name": "@vercel-labs/agent-skills",
+ "dependencies": {
+ "yaml": "2.9.0"
+ }
+ },
+ "node_modules/yaml": {
+ "version": "2.9.0",
+ "integrity": "sha512-2AvhNX3mb8zd6Zy7INTtSpl1F15HW6Wnqj0srWlkKLcpYl/gMIMJiyuGq2KeI2YFxUPjdlB+3Lc10seMLtL4cA==",
+ "license": "ISC",
+ "bin": {
+ "yaml": "bin.mjs"
+ },
+ "engines": {
+ "node": ">= 14.6"
+ },
+ "funding": {
+ "url": "https://github.com/sponsors/eemeli"
+ }
+ }
+ }
+}
diff --git a/package.json b/package.json
new file mode 100644
index 0000000..8ca4be2
--- /dev/null
+++ b/package.json
@@ -0,0 +1,8 @@
+{
+ "name": "@vercel-labs/agent-skills",
+ "private": true,
+ "type": "module",
+ "dependencies": {
+ "yaml": "2.9.0"
+ }
+}
diff --git a/scripts/build-discovery-index.mjs b/scripts/build-discovery-index.mjs
new file mode 100644
index 0000000..84a1e93
--- /dev/null
+++ b/scripts/build-discovery-index.mjs
@@ -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}`);