# Skills (/docs/build/skills)



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

```ts
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](/docs/build/agent-manifests#skills),
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](https://agentskills.io/home).
The secrets a skill's scripts read are listed apart from it; see
[Secrets for a skill's scripts](#secrets-for-a-skills-scripts).
Every file of a skill's folder, binary included, is part of the agent manifest.

```text
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 [#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](/reference/management/settings/set-the-tenants-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](/reference/runtime/agents/manifests/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 [#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](/docs/build/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](/docs/run/events#tool-payloads).

## Secrets for a skill's scripts [#secrets-for-a-skills-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](/docs/run/credentials#shell-credentials). In an
[agent manifest](/docs/build/agent-manifests#skills), list the environment
variables a skill's scripts read in `AGENT.md`'s `skills` block, and declare
each as a slot in `runtime.json`:

```markdown title="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.
```

```json title="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`:

```text
$ 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](/docs/run/agent-manifests#three-files)
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](/docs/run/agent-manifests#setup-and-input-files).

`.plugin()` can also contribute skills from an Agent Plugin package. See
[Plugins](/docs/build/plugins).

## Next step [#next-step]

<Cards>
  <Card title="Plugins" description="Load an Agent Plugin package." href="/docs/build/plugins" />

  <Card title="Agent builder" description="Reuse tools and instructions, and save the agent." href="/docs/build/agent" />
</Cards>
