Consider adopting agentskills.io .well-known discovery distribution

[mathieubellon]

Context

The cross-vendor Agent Skills standard (agentskills.io) is converging on a
.well-known discovery spec for skill distribution (agentskills/agentskills#255,
spec in PR #254, plus Cloudflare's independent "Agent Skills Discovery RFC").
We should decide whether — and how — this repo participates as a publisher.

Publishers serve a discovery index at /.well-known/agent-skills/index.json:

{
  "$schema": "https://schemas.agentskills.io/discovery/0.2.0/schema.json",
  "skills": [
    {
      "name": "scan-secrets",
      "type": "skill-md",
      "description": "Detect hardcoded secrets in files, git history, ...",
      "url": "/.well-known/agent-skills/scan-secrets/SKILL.md",
      "digest": "sha256:..."
    }
  ]
}

Clients fetch the index, verify $schema, download artifacts by url, and
validate against digest before use. No registry required — any domain can publish.

Why this matters for us

Today we distribute through per-vendor manifests (.claude-plugin/,
.cursor-plugin/, .codex-plugin/, .agents/plugins/) plus the skills.sh CLI.
A .well-known endpoint is a vendor-neutral layer underneath all of that:
exposing our four skills (scan-secrets, create-honeytokens, scan-machine,
check-hmsl) on a GitGuardian-controlled domain lets any conformant agent
discover them without our marketplace plumbing.

Open questions

• Which domain would host /.well-known/agent-skills/index.json? (gitguardian.com?
  docs.gitguardian.com? a docs/static deploy we already control?)
• Is the spec stable enough to adopt, or do we wait for it to land?
  ($schema is still 0.2.0; PR #254 is unmerged.)
• How do digest values get generated and kept in sync in CI so the index
  can't drift from disk? (ties into our existing duplicated-reference drift concern)
• Do we serve type: "skill-md" per-skill, or type: "archive" bundles?
• Does adopting this change anything about how we version the plugin?

Non-goals (for now)

• Not committing to host anything yet — this issue is to decide direction.
• Not replacing the existing Claude/Cursor/Codex manifests; this would sit alongside them.

Related

• Package-manifest side (skill.json): tracked separately in Consider adopting agentskills.io skill.json package manifest #52

Links

• Discovery proposal: Proposal: .well-known URI for skill discovery and distribution agentskills/agentskills#255
• Discovery spec PR: Add spec for .well-known URI agentskills/agentskills#254
• Spec home: https://agentskills.io