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:
| Tool | Input | Role |
|---|---|---|
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:
---
name: pr-bot
description: Opens pull requests.
skills:
open-pr:
secrets: [GH_TOKEN]
---
Open a pull request for the change the user describes.{
"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 errorsecrets 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.