[Feature]: Read skill.json from source repos for install and sync

[xtfer]

Problem

OpenSkills discovers skills in two places where filesystem scanning creates friction:

1. Install — openskills install anthropics/skills clones the repo, walks the directory tree to find SKILL.md files, and presents them in an interactive TUI for selection. On large repos this scan is slow, and there's no structured metadata (categories, tags) available to help users pick the right skills.

2. Sync — openskills sync reads installed skills' SKILL.md frontmatter to generate the <available_skills> XML block in AGENTS.md. It can only emit name and description because that's all SKILL.md frontmatter provides. Richer metadata (categories, tags, version) would improve agent skill routing but isn't available today.

Proposed Solution

Support reading an optional skill.json (singular) from the root of source repos. When present, use it as the primary source of skill metadata for both install and sync.

Example skill.json in a source repo:

{
  "name": "anthropic-skills",
  "version": "2.1.0",
  "description": "Official AI agent skills from Anthropic",
  "skills": [
    {
      "name": "pdf",
      "path": "./pdf",
      "description": "Read, create, merge, split, and OCR PDF files",
      "category": "documents",
      "tags": ["pdf", "ocr", "merge"],
      "integrity": "sha256-yY1jg1cPGoisxK/ed7yMxPeDkU8UL7pHhPAqIci0wRA=",
      "requires": { "tools": ["python3"] }
    },
    {
      "name": "skill-creator",
      "path": "./skill-creator",
      "description": "Create and iterate on new agent skills with evals",
      "category": "development",
      "tags": ["meta", "skill", "eval"]
    }
  ]
}

Benefits for install

• The interactive TUI could show category groupings and tags alongside names and descriptions, making skill selection easier on repos with dozens of skills
• No filesystem scanning needed — the skill index is pre-built
• integrity hashes enable skipping re-install when content hasn't changed

Benefits for sync

• openskills sync could generate richer <available_skills> XML, potentially including category hints or version information that help agents route tasks more precisely
• The requires.tools field could generate warnings if a skill needs python3 but it's not available on the host
• A version field in the generated AGENTS.md would help agents and users know when skills are stale

Fallback behaviour

When skill.json is absent, fall back to existing SKILL.md scanning — no breaking change.

No filename conflict

OpenSkills doesn't use any skill.json or skills.json file of its own. It reads SKILL.md files and writes to AGENTS.md. Clean integration, no collisions.

Spec

Full schema and specification: 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

[xtfer]

Hi @numman-ali

PR opened for your consideration. Thanks.