diff options
| author | Zahra Jabini <zahra.arch@gmail.com> | 2026-08-21 14:55:25 -0400 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2026-08-21 14:55:25 -0400 |
| commit | dd089a8c752c966dee8bf0f27cb625ba193ffd9e (patch) | |
| tree | 460483e099c480b51cf51bebba53f0564105cb0a | |
| parent | b8caa260a420a73042e35521de4b5c8baf6446cc (diff) | |
| parent | 9da6e5ad92e7fd7292b779abf076bf5dbad783ac (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.yml | 49 | ||||
| -rw-r--r-- | .gitignore | 2 | ||||
| -rw-r--r-- | README.md | 11 | ||||
| -rw-r--r-- | package-lock.json | 27 | ||||
| -rw-r--r-- | package.json | 8 | ||||
| -rw-r--r-- | scripts/build-discovery-index.mjs | 154 |
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 @@ -1,3 +1,5 @@ .DS_Store .vercel .env*.local +dist +node_modules @@ -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}`); |
