Proposal: skills.json format for Agent Skills registry

[JAORMX]

Pre-submission Checklist

• I have verified this would not be more appropriate as a feature request in a specific repository
• I have searched existing discussions to avoid duplicates

Your Idea

The MCP registry does a great job enabling discovery and distribution of MCP servers via server.json. I'd like to propose extending this to cover Agent Skills - the open format for extending AI agents with specialized capabilities.

Agent Skills have seen rapid adoption across tools (Claude Code, Cursor, VS Code/Copilot, Codex, etc.), but there's no standardized way to discover and distribute them through a registry. Skills are currently shared via git repos or manual copying.

Proposal: skills.json

A registry entry format for skills, inspired by server.json but adapted for the Agent Skills spec. Here's a minimal example:

{
  "namespace": "io.github.bob",
  "name": "hello-world",
  "description": "A simple example skill that greets users.",
  "version": "0.1.0",
  "packages": [
    {
      "registryType": "git",
      "url": "https://github.com/bob/hello-world-skill.git",
      "ref": "main"
    }
  ]
}

Design notes

The format borrows heavily from what the MCP registry already does well:

• Uses namespace/name identity with reverse-DNS (so existing auth/ownership verification works)
• Supports both git and OCI distribution (git is easier to start, OCI adds supply chain guarantees)
• Keeps required fields minimal - just the basics to find and fetch a skill

Why extend the registry?

• Skills and MCP servers are complementary (skills often use MCP tools)
• Shared authentication/namespace infrastructure
• Single place for agentic tool discovery
• Could leverage the registry extension API initially

I have a more complete spec with JSON Schema, but wanted to gauge interest first. Happy to share details or iterate based on feedback.

Scope

• Protocol Specification
• SDK Features
• Documentation
• Developer Experience
• Other

[thoorp]

Like the idea but this may belong to a different project unless I'm missing something.

[JAORMX]

The registry supports a servers.json for MCP servers. The idea is to start bringing skills into the registry, and thus, this would be an equivalent concept.

[evan-rash]

What about extending the MCP protocol itself so that the sever can expose skills natively? Similar to how a server can expose resources.

Your concept of a skills.json could then pull in skills for remote repos, but also from the MCP server itself.

I'm able to hack this now by creating a local MCP server that installs the relevant skills in the project at startup, but it would be much more elegant if the protocol supported this natively

[JAORMX]

@evan-rash that's also a valid approach that several pf us have been trying with mixed results. We did do a PoC of expressing skills via MCP Resources. And the base of the approach is not too hard to implement. The tricky thing has been to get clients to pick that up. I know another team member had some ways to work around this.

Regardless, while this solves delivery and usage of skills. Adding skills to the registry and thus the skills.json format aims to standardize packaging + distribution which is a different issue.

[xtfer]

Following up on this discussion with a concrete proposal that's complementary to the skills.json registry format described here.

The original format proposed here is a registry entry — it describes how to find and fetch a skill from a registry's perspective. There's a separate need for a publisher-side package metadata file that lives inside the skill repo itself, describing what skills exist and providing metadata for registries to ingest.

We've drafted a skill.json format (singular, to avoid collision with consumer-side skills.json files from tools like skmr and skillman) that serves this role:

{
  "name": "my-skill-pack",
  "version": "1.0.0",
  "description": "A collection of useful skills",
  "repository": {
    "type": "git",
    "url": "https://github.com/org/repo.git"
  },
  "skills": [
    {
      "name": "my-skill",
      "path": "./my-skill",
      "description": "What the skill does",
      "integrity": "sha256-...",
      "category": "development",
      "tags": ["react", "frontend"]
    }
  ]
}

A registry ingestion pipeline could read skill.json from source repos and generate registry entries from it — mapping name → namespace, version → version, repository → packages, and enriching with tags/category/integrity for search and verification.

This gives skill authors a single file to maintain, and registries a structured source to index from, rather than requiring both authors and registries to independently scan for and parse SKILL.md frontmatter.

Full spec: https://github.com/velvet-tiger/skill.json

Related

• [Proposal]: Add skill.json as an optional package-level metadata file in https://github.com/agentskills/agentskills
• [Feature]: Support skill.json for publisher-side skill discovery in https://github.com/vercel-labs/skills

[Starlight143]

I like the split that seems to be emerging here between:

• registry-side discovery metadata (skills.json)
• publisher-side package metadata (skill.json)

That feels cleaner than trying to force one file to solve both discovery and packaging concerns.

If this moves forward, I’d strongly suggest making room for runtime / safety metadata early, even if some of it starts as optional.

For skills that influence tool execution or workflow behavior, the most useful metadata often isn’t just:

• where to fetch it
• what version it is
• what tags it has

It’s also:

• does it introduce side effects?
• does it expect MCP tools?
• does it require approvals / human review?
• what environments is it intended for?
• what audit fields or execution evidence does it emit?
• is it safe to auto-run vs suggest-only?

I could imagine a nice division of responsibility like this:

• skills.json: registry/discovery/package resolution
• skill.json: publisher-authored manifest for execution semantics and ingestible metadata

That would help registries stay lightweight while still letting downstream tools reason about trust, risk, and compatibility.

My bias would be to keep the required fields minimal, but define extension points now so security / execution metadata doesn’t become an afterthought later.

I’ve been thinking about this from the angle of runtime authorization and approval-aware skills, and this two-file split feels like the right foundation.