Skill Format

3 min read

Overview

The skill format defines how a skill is structured on disk, what files it contains, and which of those files is the AI interface versus local installation metadata. The agent-facing SKILL.md convention is unchanged. Installation tooling may add skill.yaml to record how a particular copy was resolved and installed.

Directory Structure

<skill-name>/
├── SKILL.md         ← REQUIRED. The AI interface. Agent reads only this.
├── skill.yaml       ← REQUIRED by this installation format. Agent never reads this.
├── scripts/         ← Optional. Executables and helpers invoked by the skill.
│   └── main.py
├── references/      ← Optional. Supplementary docs the agent may read on demand.
│   └── api.md
├── templates/       ← Optional. File templates the skill scaffolds.
└── assets/          ← Optional. Static data (schemas, configs, etc.).

SKILL.md Agent Interface

SKILL.md is the only file the agent reads. Its format is unchanged from the existing Hermes convention. Neither the registry nor the installation client modifies it, extends it, or adds fields to it.

Standard frontmatter:

---
name: skill-name
description: Use when <trigger>. <one-line behaviour>.
version: 1.0.0
author: Author Name
license: MIT
metadata:
  hermes:
    tags: [tag1, tag2]
    related_skills: [other-skill]
---

No backing metadata, no capability tags, no install information belongs in SKILL.md. Anything that is not directly useful to the agent reading the skill does not belong here.

skill.yaml Installation Metadata

skill.yaml is written by the local installation client and read by local management tooling such as the CLI, daemon, or pre-flight checker. The deployed Gateway does not write into the consumer’s filesystem, and the agent never loads this file.

It records the provenance of the installed copy: where it came from, what version was installed, what hash the client verified, and which runtime the client used. It can retain capabilities and other registry metadata so local tools can inspect the resolved record without querying the Gateway again.

Per-skill skill.yaml (written at install time)

# Written by the local skill installation client. Not read by the agent.

name: web-scraper
version: 2.3.1
installed_at: 2026-06-01T14:22:00Z
installed_by: skill-cli/1.0.0

source:
  type: oci                             # oci | npm | pip | nix | wasm | git
  ref: skillhub.io/skills/web-scraper:2.3.1
  digest: sha256:a1b2c3d4e5f6...        # immutable content address
  registry: skillhub.io
  signed: true
  signature_ref: skillhub.io/skills/web-scraper:sha256-a1b2c3...sig

# npm-backed skill example:
# source:
#   type: npm
#   package: "@agent-skills/web-tools"
#   version: "3.0.0"
#   registry: https://registry.npmjs.org
#   integrity: sha512-abc123...
#   node_modules_path: .skills/web-scraper/.npm/node_modules
#   node_version_required: ">=18"
#   node_version_used: "20.11.0"

# pip-backed skill example:
# source:
#   type: pip
#   package: "pandas-agent"
#   version: "1.2.3"
#   registry: https://pypi.org/simple
#   hash: sha256:def456...
#   venv_path: .skills/web-scraper/.venv
#   python_version_required: ">=3.10"
#   python_version_used: "3.11.8"

# nix-backed skill example:
# source:
#   type: nix
#   flake: "github:org/skills#web-scraper"
#   flake_lock_hash: sha256:ghi789...
#   nix_store_path: /nix/store/abc123-web-scraper-2.3.1

runtime:
  required_commands: []
  required_env: []
  platforms: [linux/amd64, linux/arm64, darwin/arm64]

# Copied from registry metadata for local inspection. Never exposed to the agent.
capabilities: [web-scraping, html-parsing, http-client]

# Set if this skill was installed as part of a bundle
bundle: null  # or "data-science-suite@1.0.0"

Root skill.yaml Workspace Dependency Manifest

The root skill.yaml lives at the workspace root alongside the code. It is committed to version control. It is the declaration of what skills this workspace needs analogous to package.json.

# skill.yaml  committed to VCS, analogous to package.json

name: my-agent-workspace
version: 1.0.0
description: Skill dependencies for the data pipeline agent

skills:
  web-scraper: "^2.0.0"
  code-executor: "skillhub.io/core/code-executor@sha256:abc123"
  data-analysis:
    source: pip:pandas-agent
    version: ">=1.2.0"
  frontend-tools:
    source: npm:@agent-skills/frontend
    version: "3.0.0"

bundles:
  data-science-suite: "skillhub.io/bundles/data-science@1.4.0"

registries:
  default: skillhub.io
  internal: registry.corp.example.com/skills

nix:
  enabled: false   # set true to wrap npm/pip skills in a Nix shell for reproducibility

platforms: [linux/amd64, linux/arm64, darwin/arm64]

.skills/ Installed Skills Directory

.skills/ is analogous to node_modules/. It is gitignored and managed by the local installation client. Each installed skill gets its own subdirectory. Backing-system artifacts such as virtual environments or node_modules can be isolated per skill within that subdirectory.

.skills/
├── web-scraper/
│   ├── SKILL.md
│   ├── skill.yaml
│   └── scripts/
├── frontend-tools/
│   ├── SKILL.md
│   ├── skill.yaml
│   ├── scripts/
│   │   └── entrypoint.sh     ← installer-generated, delegates to .npm/
│   └── .npm/
│       └── node_modules/
└── data-analysis/
    ├── SKILL.md
    ├── skill.yaml
    ├── scripts/
    │   └── entrypoint.sh     ← installer-generated, activates .venv
    └── .venv/

The installation client generates skills.lock alongside the root skill.yaml after a successful install. It contains fully resolved, hash-pinned records for every skill and transitive dependency. It is committed to VCS and provides the input needed for reproducible installation.

OCI Packaging

When a skill is published to an OCI registry, the skill directory is packaged as an OCI artifact. The per-installation skill.yaml is not included in the artifact. The local installation client writes it from the Gateway resolution, OCI manifest annotations, and facts observed during installation.

For skills with platform-specific binaries, an OCI Image Index is used to provide per-arch layers:

OCI Image Index  skillhub.io/skills/<name>:2.3.1
├── manifest [linux/amd64]
│   ├── layer: SKILL.md + references/ + templates/   (arch-agnostic)
│   └── layer: scripts/                              (linux/amd64 binaries)
├── manifest [linux/arm64]
│   ├── layer: SKILL.md + references/ + templates/
│   └── layer: scripts/                              (linux/arm64 binaries)
└── manifest [darwin/arm64]
    ├── layer: SKILL.md + references/ + templates/
    └── layer: scripts/                              (darwin/arm64 binaries)

For pure-script skills (no platform-specific binaries), a single manifest with no platform split is sufficient.

OCI manifest annotations mirror the key fields from skill.yaml: name, version, platforms, capabilities, backing type, and signing reference.

Skill Gateway the registry and discovery service that supplies resolution and provenance metadata
Skills the skill concept and lifecycle
Skill Evaluation evaluation artifacts are co-distributed with the skill