Skip to main content
While SKILL.md is the only required file, a skill.json manifest provides structured metadata for tooling — registries, package managers, and agent frameworks that want machine-readable skill information.

​
Example

{
  "name": "weather",
  "version": "1.0.0",
  "description": "Get current weather for any location",
  "author": "yourname",
  "license": "MIT",
  "entry": "run.sh",
  "args": [
    {
      "name": "location",
      "type": "string",
      "required": true,
      "description": "City name or coordinates"
    }
  ],
  "env": [
    {
      "name": "WEATHER_API_KEY",
      "required": false,
      "description": "API key for extended forecasts"
    }
  ],
  "tags": ["weather", "utility"]
}

​
Fields

FieldRequiredDescription
nameYesUnique skill identifier
versionYesSemver version string
descriptionYesOne-line summary
authorNoAuthor name or GitHub handle
licenseNoSPDX license identifier
entryNoPath to main executable (default: run.sh)
argsNoArray of expected arguments
envNoArray of environment variables the skill uses
tagsNoKeywords for discovery

​
When to use skill.json

  • Publishing to a registry — registries use it for search and display
  • Complex argument handling — document expected inputs for better agent performance
  • Environment requirements — declare what env vars the skill needs

​
When to skip it

For simple skills used locally, SKILL.md alone is sufficient. Don’t add structure you don’t need.