Skill Definition Format v1

A skill is a single JSON document — the manifest. It declares the skill's identity, its input/output contract, the capabilities it needs, and how to run it. Hosts (marketplaces, agent runtimes, the CLI) read this document and nothing else to decide whether a skill is installable, runnable, and safe.

#Top-level fields

#Identity: name, version, description

##name

The skill's slug. Lowercase ASCII letters, digits, and single hyphens; must start and end with an alphanumeric; max 64 characters. Names are namespaced per publisher on marketplaces, so acme/web-search and you/web-search can coexist — the bare name here is the unqualified slug.

// valid
"web-search"      // ✓
"pdf2md"          // ✓ digits fine
"a"               // ✓ single char ok

// invalid — validator rejects these
"Web-Search"      // ✗ uppercase
"web_search"      // ✗ underscore
"-web-search"     // ✗ leading hyphen
"web--search"     // ✗ double hyphen

##version

Strict semver 2.0.0: MAJOR.MINOR.PATCH with optional pre-release and build metadata. No leading v — that's a display convention, not part of the version. Pre-release versions (e.g. 2.0.0-beta.1) install only with an explicit --pre flag. Versions below 0.1.0 are treated as drafts and hidden from marketplace search.

##description

One or two sentences a human would read in a listing. Must be non-blank. Under 20 characters or over 280 triggers a warning: short descriptions rank poorly, long ones get truncated in cards.

#Schemas: inputs & outputs

Both fields are schema objects in a JSON-Schema-like dialect. The shape is always:

{
  "type": "object",          // conventional; enforced by convention, not by type error
  "required": ["query"],       // every entry MUST exist in properties — else error
  "properties": {
    "query": {
      "type": "string",       // required per property (warning if missing)
      "description": "The search query.",
      "minLength": 1
    },
    "limit": {
      "type": "integer",
      "default": 5,            // applied by hosts when the caller omits the field
      "minimum": 1, "maximum": 50
    },
    "format": {
      "type": "string",
      "enum": ["json", "markdown"]  // must be a non-empty array
    },
    "filters": {
      "type": "array",
      "items": { "type": "string" }  // warning if omitted on arrays
    }
  }
}

##Allowed property types

Unknown type strings are errors (there is no guessing). A required entry that names a property not declared in properties is an error. Missing type on a property is a warning.

#Permissions

Capabilities are deny-by-default. A skill that doesn't declare permissions runs fully sandboxed: no network, no filesystem, no subprocesses. Declare only what you need — least privilege isn't just good hygiene, it determines your review lane on publish.

#Runtime requirements

Optional hints to the host about how to execute the skill. All fields optional; hosts apply their own caps (marketplace defaults: 5 min timeout, 2048 MB memory).

#Examples

An array of { name, input, output } objects. input and output must be objects. Examples are user documentation and machine fixtures: skill test runs each example's input and diffs the output. Give every example a descriptive name — unnamed examples draw a warning.

"examples": [
  {
    "name": "basic query",
    "input": { "query": "agentskills spec", "limit": 3 },
    "output": { "results": [ … ], "took_ms": 812 }
  }
]

#Metadata: author, license, tags

Optional but recommended. author is a display string shown on listings. license should be an SPDX identifier (MIT, Apache-2.0); publishing without one marks the skill UNLICENSED (private). tags are lowercase search keywords, max 10.

#Full annotated example

{
  "name": "web-search",            // slug — lowercase, hyphenated
  "version": "1.2.0",               // semver, no leading v
  "description": "Searches the public web and returns ranked results with titles, URLs, and snippets.",
  "author": "Acme Labs",
  "license": "MIT",
  "tags": ["web", "search", "research"],

  "inputs": {                            // what the caller provides
    "type": "object",
    "required": ["query"],
    "properties": {
      "query": { "type": "string", "minLength": 1 },
      "limit": { "type": "integer", "default": 5, "minimum": 1, "maximum": 50 }
    }
  },
  "outputs": {                           // what the skill returns
    "type": "object",
    "required": ["results"],
    "properties": {
      "results": {
        "type": "array",
        "items": { "type": "object" }
      }
    }
  },

  "permissions": ["net.http"],      // least privilege: only outbound HTTPS
  "runtime": {
    "engine": "skill-engine>=0.4",
    "timeout_ms": 15000,
    "memory_mb": 256
  },
  "examples": [
    {
      "name": "basic query",
      "input": { "query": "agentskills spec", "limit": 3 },
      "output": { "results": [], "took_ms": 812 }
    }
  ]
}

Paste this into the validator → — it passes with zero errors and zero warnings.

#Validation rules summary

Exit codes follow the same split: the CLI's skill validate exits 0 on pass (even with warnings) and 1 on any error. See the CLI reference.