The agentskills.io spec

Anatomy of a skill

A skill is a directory containing a skill.json manifest plus its implementation. The manifest is the contract: it tells the agent host the skill's name and version, what it does, what it needs, and what it promises to return. Agents never execute a skill whose manifest fails validation.

my-skill/
├── skill.json        # manifest (required)
├── README.md         # human docs (recommended)
├── prompts/          # system prompts, templates
├── tools/            # executables the skill invokes
└── tests/            # eval cases for the skill

Required fields

Six fields are mandatory. A manifest missing any of them is rejected at install time.

Field	Type	What it means
name	string	Unique slug, lowercase a–z, digits, and hyphens, 3–48 chars. This is the skill's identity on the marketplace (e.g. deep-researcher).
version	string	Strict semver MAJOR.MINOR.PATCH. Installs are pinned to exact versions; breaking changes require a major bump.
description	string	Plain-language summary, 40–280 characters. This is what agents read when deciding whether to invoke the skill — make it concrete.
inputs	object	JSON-Schema-style map of accepted parameters. Each key declares a type, a human description, and whether it is required.
outputs	object	JSON-Schema-style map of what the skill returns. Agents use this to know what to expect and how to chain skills together.
permissions	string[]	The capability allowlist — see the permissions model. Anything not listed is denied at runtime.

Optional fields

Field	Type	What it means
author	string	Publisher name or org shown on the marketplace listing.
license	string	SPDX identifier (e.g. MIT, Apache-2.0). Defaults to UNLICENSED if omitted.
category	string	One of the marketplace categories (e.g. Development, Data). Defaults to Productivity.
homepage	string	URL with more information about the skill.
repository	string	Source-code URL.
entrypoint	string	Relative path to the executable invoked by the host. Defaults to ./run.sh.
runtime	string	Runtime hint: shell, node, python, or docker. Defaults to shell.
min_host_version	string	Minimum askill CLI version required.
tags	string[]	Up to 8 lowercase search tags.

Permissions model

Permissions are a deny-by-default allowlist. The skill declares the capabilities it needs; the host enforces them at runtime. A skill that touches the network must declare net:http — otherwise its requests are blocked and logged.

Permission	Grants
net:http	Outbound HTTPS requests
net:dns	DNS resolution (implied by net:http)
fs:read	Read files inside the agent workspace
fs:write	Write files inside the agent workspace (never outside it)
exec:shell	Run shell subprocesses
exec:docker	Spawn containers via the host Docker socket
env:read	Read non-secret environment variables
secret:read	Read named secrets from the host vault (each access is logged)
browser:headless	Drive a sandboxed headless browser

Annotated example

A complete, valid skill.json for a small research skill. Comments are shown with // for annotation — strip them before publishing, since strict JSON doesn't allow comments.

// Every manifest starts with the spec version it was written against.
{
  "spec": "agentskills.io/v1",

  // REQUIRED: unique marketplace slug + semver version.
  "name": "deep-researcher",
  "version": "2.1.0",

  // REQUIRED: 40–280 chars. Agents match on this text, so be specific.
  "description": "Plans a research brief, queries multiple web sources in
    parallel, cross-checks claims, and returns a cited Markdown
    report with a confidence score per section.",

  // REQUIRED: what the skill accepts. JSON-Schema style.
  "inputs": {
    "topic": {
      "type": "string",
      "description": "Research question or topic.",
      "required": true,
      "minLength": 8
    },
    "depth": {
      "type": "string",
      "description": "How deep to go.",
      "required": false,
      "enum": ["quick", "standard", "deep"],
      "default": "standard"
    }
  },

  // REQUIRED: what the skill returns. Enables chaining.
  "outputs": {
    "report_markdown": {
      "type": "string",
      "description": "Full cited report in Markdown."
    },
    "sources": {
      "type": "array",
      "description": "URLs consulted, in citation order."
    },
    "confidence": {
      "type": "number",
      "description": "0–1 aggregate confidence."
    }
  },

  // REQUIRED: deny-by-default allowlist. This skill needs the web
  // and a scratch file, so it declares exactly those two.
  "permissions": ["net:http", "fs:write"],

  // OPTIONAL but recommended: identity, license, discoverability.
  "author": "AgentWorks",
  "license": "Apache-2.0",
  "category": "Research",
  "homepage": "https://anthropicskills.com/skills/deep-researcher.html",
  "repository": "https://github.com/agentworks/deep-researcher",
  "entrypoint": "./run.sh",
  "runtime": "shell",
  "tags": ["research", "web", "citations", "reports"]
}

Validation rules

Run askill validate ./skill.json before submitting. The validator enforces:

• name matches ^[a-z0-9-]{3,48}$ and is unique on the marketplace.
• version is strict semver; new publishes must be greater than the latest published version.
• description is 40–280 characters, no URLs, no marketing superlatives ("best", "ultimate").
• Every inputs entry declares type (one of string, number, boolean, array, object) and description.
• outputs has at least one entry; keys must be valid identifiers.
• permissions contains only values from the table above; duplicates are rejected.
• If entrypoint is set, the referenced file must exist and be executable.
• The whole manifest must parse as strict JSON (no comments, no trailing commas) and stay under 32 KB.

Installing skills

The askill CLI validates the manifest locally, checks the version pin, and sandboxes declared permissions before the skill ever runs:

# install the latest 2.x of a skill
askill install deep-researcher

# pin an exact version for reproducible agents
askill install deep-researcher@2.1.0

# see what a skill can do before installing
askill info deep-researcher

# remove it again
askill remove deep-researcher