[Feature]: Read skill.json from source repos for install, recommend, and translate

[xtfer]

Problem

SkillKit discovers skills by scanning cloned repos for SKILL.md files in several workflows, and each would benefit from structured publisher-side metadata:

1. Install — skillkit install anthropics/skills clones and walks the directory tree to find SKILL.md files. No structured index exists, so large repos require a full scan.

2. Recommend — skillkit recommend analyses the project and matches against available skills. Currently this matching relies on parsing skill descriptions from SKILL.md frontmatter. Structured tags and categories from the publisher would significantly improve recommendation precision and reduce false positives.

3. Translate — skillkit translate my-skill --to cursor converts between agent formats. The translation currently works from SKILL.md content alone. Publisher-declared requires.tools or requires.min_agent_versions could inform smarter translation — for example, warning that a skill requiring python3 may not work well in agents without shell access.

4. Marketplace — skillkit marketplace browses curated repos. Structured metadata (category, tags, version, author) from the source would make indexing and search far richer without SkillKit having to parse and infer everything from markdown.

5. Validate — skillkit validate checks skill format. Could additionally validate skill.json and cross-check it against actual SKILL.md files in the package.

Proposed Solution

Support reading an optional skill.json (singular) from the root of source repos as a preferred metadata source. When present, use it to accelerate discovery, improve recommendations, and enrich the marketplace index. When absent, fall back to existing SKILL.md scanning.

Example skill.json in a source repo:

{
  "name": "anthropic-skills",
  "version": "2.1.0",
  "description": "Official AI agent skills from Anthropic",
  "author": { "name": "Anthropic", "url": "https://anthropic.com" },
  "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": "frontend-design",
      "path": "./frontend-design",
      "description": "Production-grade UI with distinctive design",
      "category": "development",
      "tags": ["frontend", "css", "react", "design"]
    }
  ]
}

Benefits per feature

Install: Pre-built skill index eliminates filesystem scanning. The interactive TUI could group skills by category and show tags alongside descriptions.

Recommend: skillkit recommend currently infers what a skill is about from its description text. Publisher-declared tags like ["nextjs", "react", "app-router"] give exact matching against detected project characteristics — same approach, much higher signal-to-noise ratio.

Translate: The requires.tools field tells SkillKit which skills depend on shell/runtime features. This could generate warnings during translation to agents with limited execution environments, or skip incompatible skills entirely.

Marketplace: author, version, category, tags, and license are all fields that marketplace browsing and search need. Currently these have to be inferred or manually curated. skill.json provides them from the source.

Validate: skillkit validate could validate skill.json against the JSON Schema and cross-check that every declared skill has a SKILL.md at the declared path.

No filename conflict

SkillKit uses skillkit.yaml for its own project config. No collision with skill.json.

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