Skip to content
Kiberon LabsAgentic Engineering Ebook

Skill Format

Overview

Section titled “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 system metadata. The format is an extension of the existing Hermes SKILL.md convention the agent-facing interface is unchanged; the gateway adds one additional file for its own use.

Directory Structure

Section titled “Directory Structure”
<skill-name>/
├── SKILL.md         ← REQUIRED. The AI interface. Agent reads only this.
├── skill.yaml       ← REQUIRED when installed. Gateway metadata. 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

Section titled “SKILL.md Agent Interface”

SKILL.md is the only file the agent reads. Its format is unchanged from the existing Hermes convention. The gateway does not modify it, extend it, or add 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 Gateway Metadata

Section titled “skill.yaml Gateway Metadata”

skill.yaml is written by the gateway at install time and is only read by gateway tooling the CLI, the daemon, the pre-flight checker. The agent never loads it.

It records the complete provenance of the installed skill: where it came from, what version was installed, what hash was verified, what runtime the backing system used, and what capabilities the skill advertises for search and dynamic injection.

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

Section titled “Per-skill skill.yaml (written at install time)”
# Written by the skill gateway. Not read by the agent.


name: web-scraper
version: 2.3.1
installed_at: 2026-06-01T14:22:00Z
installed_by: skill-gateway/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]


# Used by the gateway for search and dynamic injection. 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

Section titled “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

Section titled “.skills/ Installed Skills Directory”

.skills/ is analogous to node_modules/. It is gitignored and entirely managed by the gateway. Each installed skill gets its own subdirectory. Backing-system artifacts (venvs, node_modules) are isolated per skill within that subdirectory.

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

skills.lock is generated 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 guarantees reproducibility.

OCI Packaging

Section titled “OCI Packaging”

When a skill is published to an OCI registry, the skill directory is packaged as an OCI artifact. The skill.yaml is not included in the artifact it is written by the gateway at install time using the OCI manifest annotations as source.

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.

Section titled “Related”