Context

The Agent Skills spec currently defines the individual skill format well — SKILL.md with frontmatter, optional scripts/, references/, assets/ directories, progressive disclosure, validation via skills-ref. What's missing is any standard for package-level metadata: when a repo contains multiple skills, there's no structured way to declare what's inside without scanning the filesystem and parsing every SKILL.md's frontmatter.

This gap has spawned half a dozen competing approaches in the package manager ecosystem. skmr, skillman, skillbox, skills-manifest, skills-supply, and konstruct all reinvent skill discovery by walking directories and parsing frontmatter independently. Each has slightly different scanning logic, leading to inconsistent behaviour across tools.

Proposal

Add an optional skill.json (singular) file to the specification as a package-level companion to SKILL.md. It lives at the root of a skill package and provides a structured index of what skills exist in the package, with metadata that tooling can consume without parsing markdown.

Minimal example:

{
 "name": "my-skill-pack",
 "version": "1.0.0",
 "description": "A collection of useful skills",
 "skills": [
   {
     "name": "pdf",
     "path": "./pdf",
     "description": "Read, create, merge, split, and OCR PDF files"
   }
 ]
}

Per-skill entries support optional fields for integrity hashing (SRI format), categories, tags, runtime tool requirements (requires.tools), intra-package dependencies, per-skill license/author overrides, and an entrypoint field (defaults to SKILL.md).

Relationship to SKILL.md

skill.json wraps SKILL.md, it doesn't replace it. SKILL.md remains the authoritative runtime instruction file that agents read. skill.json is for tooling — package managers, registries, search indexes — that need structured metadata without parsing markdown frontmatter.

If skill.json and SKILL.md frontmatter conflict on fields like name or description, skill.json is authoritative for tooling; SKILL.md remains authoritative for the agent at runtime.

What it covers that SKILL.md frontmatter doesn't

• Package-level metadata: version, author, license, repository, homepage, keywords — things that belong to the package, not to individual skills
• Skill enumeration: Explicit list of what skills exist and where (path), eliminating filesystem scanning
• Integrity hashing: SRI-format content hashes for verification and cache-based deduplication
• Search metadata: category and tags per skill for registry/search tooling
• Runtime requirements: requires.tools (e.g. ["python3"]) and requires.min_agent_versions for compatibility constraints
• Intra-package dependencies: Declare that skill B requires skill A from the same package
• Cross-package dependencies: requires.skills using "package-name/skill-name" format

Why "skill.json" (singular)?

Multiple consumer-side tools (skmr, skillman, konstruct) already use skills.json (plural) for their project manifests. The singular form avoids filename collisions and creates a clear semantic distinction: skill.json = publisher-side "what's in this package" (like package.json), skills.json = consumer-side "what does this project need".

Scope within the spec

This would be an optional addition. A valid skill package can still contain just SKILL.md (as today). skill.json is opt-in — package managers should fall back to SKILL.md scanning when it's absent.

The skills-ref validation tool could be extended to validate skill.json when present, and to cross-check that every skill declared in skill.json has a corresponding SKILL.md at the declared path.

Spec and schema

Full specification with design rationale and a JSON Schema: https://github.com/velvet-tiger/skill.json. The specification can be incorporated into agentskills, or adapted as required.

Related discussions

Proposal to use skill.json for Skills.sh

Examples

https://github.com/aurabx/skills contains a skill.json file

DISCLOSURE

The skill.json project and this comment were generated with AI based on detailed instructions and review, along with analysis of common patterns across existing repositories.