packages/eslint-plugin-agent-skills/src/schema.json (introduced in #67) declares a forward-looking \$id:
https://gtbuchanan.github.io/tooling/schemas/agent-skills/skill-frontmatter.json
…which doesn't resolve and we have no plan to host. The schema is bundled in the published package so the lint rule works without it, but the URL was a placeholder.
Goal
Give the schema a canonical, URL-addressable identity so other tools that validate Agent Skills can reference the same source of truth — skills-ref, @vibe-agent-toolkit/agent-skills, and any future bespoke tooling that wants to consume the schema by URL rather than vendoring its own copy.
Preferred path: upstream to agentskills.io
The schema describes the Agent Skills specification, so the spec authors are the natural canonical host. Steps:
- Open a PR/issue against the agentskills/agentskills repo proposing they host the JSON Schema, likely under something like
https://agentskills.io/schemas/skill-frontmatter.json.
- If accepted: update our
\$id to point at their URL.
- Add a scheduled CI job that fetches the upstream schema, diffs against the bundled copy in
src/schema.json, and opens a PR if it has changed. Bumps stay automated; we don't hand-maintain a vendored mirror that silently drifts.
Open questions
- What to do with the placeholder
\$id until upstream lands? Options: drop it entirely (schemas don't require \$id), keep it as a non-resolving forward-looking marker, or replace with a less-committal placeholder. Probably drop until we know the real URL — the bundled schema works without it.
- What if upstream declines or is unresponsive? Possible self-host paths: GitHub Pages on this repo, a dedicated tiny static site, or just stay bundle-only forever. Decide based on actual demand.
- SchemaStore registration? SchemaStore mostly helps the VSCode YAML extension, which targets
*.yaml/*.yml and doesn't validate Markdown frontmatter natively. Worth investigating which Markdown extensions (if any) consume SchemaStore entries for frontmatter before pursuing a registration PR.
Out of scope
Migrating our lint pipeline to fetch the schema by URL at lint time. The plugin already validates against the bundled schema object; remote fetch is a separate, larger feature with real complexity — caching to avoid network calls per lint, offline behavior, and determinism (we'd need to detect when an upstream silently changes).
packages/eslint-plugin-agent-skills/src/schema.json(introduced in #67) declares a forward-looking\$id:…which doesn't resolve and we have no plan to host. The schema is bundled in the published package so the lint rule works without it, but the URL was a placeholder.
Goal
Give the schema a canonical, URL-addressable identity so other tools that validate Agent Skills can reference the same source of truth —
skills-ref,@vibe-agent-toolkit/agent-skills, and any future bespoke tooling that wants to consume the schema by URL rather than vendoring its own copy.Preferred path: upstream to agentskills.io
The schema describes the Agent Skills specification, so the spec authors are the natural canonical host. Steps:
https://agentskills.io/schemas/skill-frontmatter.json.\$idto point at their URL.src/schema.json, and opens a PR if it has changed. Bumps stay automated; we don't hand-maintain a vendored mirror that silently drifts.Open questions
\$iduntil upstream lands? Options: drop it entirely (schemas don't require\$id), keep it as a non-resolving forward-looking marker, or replace with a less-committal placeholder. Probably drop until we know the real URL — the bundled schema works without it.*.yaml/*.ymland doesn't validate Markdown frontmatter natively. Worth investigating which Markdown extensions (if any) consume SchemaStore entries for frontmatter before pursuing a registration PR.Out of scope
Migrating our lint pipeline to fetch the schema by URL at lint time. The plugin already validates against the bundled schema object; remote fetch is a separate, larger feature with real complexity — caching to avoid network calls per lint, offline behavior, and determinism (we'd need to detect when an upstream silently changes).