Context
The cross-vendor Agent Skills standard (agentskills.io) is proposing an optional
skill.json package manifest (agentskills/agentskills#214). We should decide
whether — and how — this repo participates as a package.
skill.json lives at the repo root and provides publisher-side metadata that
tooling can consume without walking the tree or parsing individual SKILL.md
files:
- package metadata (name, version, license, repository)
- the skill list with paths, descriptions, SRI digests, categories, tags
- runtime requirements (
requires.tools, requires.min_agent_versions)
- intra- and cross-package skill dependencies
Singular skill.json (publisher declaration) is deliberately distinct from
plural skills.json (consumer-side requirements). When the two disagree,
skill.json is authoritative for tooling; SKILL.md stays authoritative for
runtime agents.
Why this matters for us
A root skill.json would declare our four skills (scan-secrets,
create-honeytokens, scan-machine, check-hmsl) with digests and
requires.tools: ["ggshield"], so package managers (skmr, skillman, skillbox, …)
stop re-deriving our skill list by walking the directory tree. It is low-cost
and low-risk relative to standing up a hosted endpoint — potentially worth
shipping first.
Open questions
Non-goals (for now)
- Not committing to ship
skill.json yet — this issue is to decide direction.
- Not replacing the existing Claude/Cursor/Codex manifests or
SKILL.md
frontmatter; this would sit alongside them.
Related
Links
Context
The cross-vendor Agent Skills standard (agentskills.io) is proposing an optional
skill.jsonpackage manifest (agentskills/agentskills#214). We should decidewhether — and how — this repo participates as a package.
skill.jsonlives at the repo root and provides publisher-side metadata thattooling can consume without walking the tree or parsing individual
SKILL.mdfiles:
requires.tools,requires.min_agent_versions)Singular
skill.json(publisher declaration) is deliberately distinct fromplural
skills.json(consumer-side requirements). When the two disagree,skill.jsonis authoritative for tooling;SKILL.mdstays authoritative forruntime agents.
Why this matters for us
A root
skill.jsonwould declare our four skills (scan-secrets,create-honeytokens,scan-machine,check-hmsl) with digests andrequires.tools: ["ggshield"], so package managers (skmr, skillman, skillbox, …)stop re-deriving our skill list by walking the directory tree. It is low-cost
and low-risk relative to standing up a hosted endpoint — potentially worth
shipping first.
Open questions
digestvalues get generated and kept in sync in CI so themanifest can't drift from disk? (ties into our existing duplicated-reference
drift concern)
requires? At minimumggshield; do we pin a min version?skill.jsonduplicate anything already in our per-vendor manifestsin a way that could drift? How do we keep them aligned?
Non-goals (for now)
skill.jsonyet — this issue is to decide direction.SKILL.mdfrontmatter; this would sit alongside them.
Related
.well-known/agent-skills): tracked in Consider adopting agentskills.io .well-known discovery distribution #51Links
skill.jsonproposal: [Proposal]: Add skill.json as an optional package-level metadata file agentskills/agentskills#214