NylorunDocsBeta
BuildDefine

Skills

Load an Agent Skills catalog folder that the harness serves to the model.

Load Agent Skills from a local catalog folder with .skills(path):

import { Agent } from "@nylorun/agents";

export const assistant = Agent({ id: "assistant", name: "Order assistant" })
  .instructions("Use lookup_order for orders.")
  .tools(lookupOrder)
  .skills("./assistant-skills");

.skills() reads files, so it is on the Agent from @nylorun/agents, not from @nylorun/agents/define. In an agent manifest, the catalog is the folder's skills/, one skills/<name>/SKILL.md per skill.

Each subdirectory under the catalog must contain a SKILL.md with YAML frontmatter (name, description) per Agent Skills. The secrets a skill's scripts read are listed apart from it; see Secrets for a skill's scripts. Every file of a skill's folder, binary included, is part of the agent manifest.

assistant-skills/
  lookup-order/SKILL.md
  refund/
    SKILL.md
    references/policy.md

.skills(directory) takes no options. Each call adds one catalog, and the catalog is named after its folder (assistant-skills), so two catalogs whose folders have the same name fail the build. Skill names are unique among the agent's skills, a plugin's included.

Files

The manifest names each file by path and SHA-256 (skills.<name>.files). The build skips .git/, node_modules/, OS files such as .DS_Store, and .env and .env.* files. No file and no count of files has a limit of its own: one skill's files hold at most the Tenant's skill limit together (2 GiB by default; npx nylorun tenant settings skills, or set the Tenant's skill limit), and a runtime section's limits.skills.totalBytes may set a lower one. The save checks it.

client.agentManifests.save and npx nylorun apply upload the files the Runtime does not hold, then save the agent manifest. The Runtime refuses a manifest that names a file it lacks (400 definition_files_missing, with the hashes in details.missing). client.files uploads them by hand: PUT /v1/files/sha256:<hex> with the raw bytes, and HEAD to check. See Upload a definition file.

Skills need a sandbox: saving an agent with skills and a runtime of kind none, or no runtime section, is refused with 422 manifest_inconsistent, and nylorun check refuses such a folder offline. Save it with kind virtual or pod.

Serving

The harness serves the skills, with no call to your process. Our harness writes the skill catalog into the model's instructions and offers two tools:

ToolInputRole
load_skill{ name }The skill's SKILL.md body and the paths of its other files
read_skill_resource{ name, path }One text file of the skill

Our harness reads a skill's files from the Runtime as it needs them, and puts at most 10 MiB of one file into the model's context. read_skill_resource refuses a binary file (skill.binary_resource) and a larger one (skill.resource_too_large); the model uses those in the sandbox.

Before each sandbox call, our harness puts each skill's files read-only under /skills/<name>@<hash>/, so the model can run a skill's scripts with bash. <hash> is 12 hex characters of the SHA-256 of the skill's file list, so each version of a skill has its own folder. A folder is written once and never replaced: sessions whose agents carry different versions of a skill share an Agent, and run turns at once, without changing each other's files. The instructions and load_skill's sandboxPath give the folder. In a SKILL.md, name the skill's files by paths relative to its own folder, never /skills/<name>/. A custom harness serves skills its own way, or not at all.

Each call of a skill names it: tool.completed and session.toolCalls() carry skill for load_skill and read_skill_resource, and for a sandbox tool whose input names the skill's folder, with the skill's plugin when a plugin brought it. See Events.

Secrets for a skill's scripts

A skill whose CLI needs a key, such as gh or aws, gets it from an environment_secret of a pod Agent, without the value entering the sandbox. See Shell credentials. In an agent manifest, list the environment variables a skill's scripts read in AGENT.md's skills block, and declare each as a slot in runtime.json:

pr-bot/AGENT.md
---
name: pr-bot
description: Opens pull requests.
skills:
  open-pr:
    secrets: [GH_TOKEN]
---
Open a pull request for the change the user describes.
pr-bot/runtime.json
{
  "kind": "pod",
  "secrets": {
    "GH_TOKEN": { "type": "environment_secret", "required": true, "allowedHosts": ["api.github.com"] }
  }
}

The list becomes the skill's secrets in the harness section. Each must be an environment_secret or environment_variable slot of the runtime section; nylorun check and the save refuse a gap (manifest_inconsistent). Without the slot in runtime.json:

$ npx nylorun check pr-bot
pr-bot/AGENT.md:6:14 error: harness.skills.open-pr.secrets "GH_TOKEN" is not a secret slot in runtime.secrets
pr-bot: 1 error

secrets in a skill's SKILL.md frontmatter is deprecated, since Agent Skills does not define it. An agent manifest refuses it (skill_secrets), and npx nylorun check --fix or npx nylorun migrate folder moves the list to AGENT.md. .skills(), .plugin(), composeManifest(), and nylorun apply on the deprecated three-file format still read it; .skills() emits a DeprecationWarning. A skill whose secrets is not a list of environment variable names is skipped with a warning.

To install the CLI itself, give the pod runtime setup commands or input files, which run when the Agent's disk is made. See Setup and input files.

.plugin() can also contribute skills from an Agent Plugin package. See Plugins.

Next step

On this page