Skip to navigation

Configure Skills

View as MarkdownOpen in Claude

The skills section of FabricConfig tells NVIDIA NeMo Fabric which skills an agent can load. A skill is a folder that holds a SKILL.md file, plus any scripts or reference files the skill uses.

The section has four fields:

FieldWhat It Sets
pathsA list of skill paths. Each adapter decides what a path means.
directoriesA list of entries. Each entry names one skill or a folder of skills. NeMo Fabric defines the rules.
bundledWhich skills that ship with the harness load.
duplicatesWhat happens when two directories entries supply skills with the same name.

Use paths or directories, not both. directories, bundled, and duplicates work only with adapters that support them. Planning rejects a request that the selected adapter does not support. Refer to Adapter Support.

Choose paths or directories

skills.paths works as it always has. Each adapter defines what a path must contain and how the harness loads it, so the same paths list can load different skills on different harnesses. Refer to each adapter guide for its rules.

skills.directories gives every adapter the same meaning. Each entry sets exactly one key:

  • skill: one skill’s folder. It must hold a readable SKILL.md.
  • folder: a folder of skills. The adapter finds the skills inside it.

The following rules apply:

  • Set directories only when paths is empty. paths: [] is the same as leaving paths out.
  • An entry with both keys, neither key, or another key fails validation. Each path must be a non-empty string.
  • directories: [] is valid and loads no external skills. It needs no adapter support.
  • Relative paths resolve against the config base directory, as paths do. NeMo Fabric does not expand ~ or environment variables such as ${VAR}.

The following layout contains five skills:

/mnt/team-skills/
├── debugging/
│ ├── SKILL.md
│ └── scripts/
│ └── collect-logs.sh
├── code-review/
│ ├── SKILL.md
│ └── references/
│ └── checklist.md
├── drafts/ # Ignored: no SKILL.md
└── README.md # Ignored: not a folder
/mnt/project-skills/
├── project-setup/
│ └── SKILL.md
└── integration-testing/
└── SKILL.md
/mnt/release-review/
├── SKILL.md
└── references/
└── release-checklist.md

Assume that each SKILL.md names its skill after its folder. A folder entry for /mnt/team-skills supplies debugging and code-review. A skill entry for /mnt/release-review supplies release-review. Whether the agent can use each skill also depends on the harness’s own rules, such as required front-matter fields.

Common Setups

NeMo Fabric does not decide whether an agent can change a skill. The mount or the file system enforces read-only access, not NeMo Fabric. Mount a folder read-only to keep skills fixed, or read-write to let the agent change them. NeMo Fabric does not change file permissions and does not grant write access.

When the agent tries to change a skill on a read-only mount, the harness’s write fails with a permission error. The harness reports that failure, not NeMo Fabric. For example, Hermes Agent returns the error to the agent as the result of its tool call. The run report does not list these failures.

The following examples show the skills section in YAML and in Python. Each Python example assumes a config that is a FabricConfig.

Load a Folder of Skills, Read-Only

Mount the folder read-only, then add one folder entry:

skills:
directories:
- folder: /mnt/team-skills
from nemo_fabric import SkillConfig, SkillDirectory
config.skills = SkillConfig(
directories=[SkillDirectory(folder="/mnt/team-skills")],
)

Load Chosen Skills, Read-Only

Mount each skill read-only, then add one skill entry for each skill:

skills:
directories:
- skill: /mnt/skills/code-review
- skill: /mnt/skills/release-review
from nemo_fabric import SkillConfig, SkillDirectory
config.skills = SkillConfig(
directories=[
SkillDirectory(skill="/mnt/skills/code-review"),
SkillDirectory(skill="/mnt/skills/release-review"),
],
)

Load a Folder the Agent Can Change

Mount the folder read-write, then add one folder entry. The harness can edit the skills in place. Whether the harness also saves new skills into this folder depends on the harness. Refer to the adapter guide.

skills:
directories:
- folder: /mnt/agent-skills
from nemo_fabric import SkillConfig, SkillDirectory
config.skills = SkillConfig(
directories=[SkillDirectory(folder="/mnt/agent-skills")],
)

Mix Entries

One list can hold both entry kinds and both kinds of mount. The following example loads a read-only team folder, a read-write folder for the agent, and one read-only skill. It also sets a duplicate policy, so a later entry’s skill wins over an earlier one with the same name:

skills:
directories:
- folder: /mnt/team-skills # read-only
- folder: /mnt/agent-skills # read-write
- skill: /mnt/release-review # read-only
duplicates: last_wins
from nemo_fabric import SkillConfig, SkillDirectory
config.skills = SkillConfig(
directories=[
SkillDirectory(folder="/mnt/team-skills"),
SkillDirectory(folder="/mnt/agent-skills"),
SkillDirectory(skill="/mnt/release-review"),
],
duplicates="last_wins",
)

Sharing a Writable Skills Volume

You can mount one read-write folder into several sandboxes at once. Each sandbox runs its own runtime. Plan for these limits:

  • No locking: NeMo Fabric does not lock skill files between sandboxes. Hermes Agent’s skill_manage tool locks a skill while it edits it, but the lock file is in its own home, so it does not stop another sandbox. Two agents that write the same skill at the same time can overwrite each other’s changes or leave a mix of both.
  • Checks run at start: The adapter runs its start checks, applies duplicates, and builds the run report once, when the runtime starts. It does not check or report a skill that another sandbox writes later until the next start. That includes two skills with the same name. At the next start, the rules in Skills That Share a Name apply.
  • Early loading: The harness can still load a new skill before the next start. Hermes Agent’s skill tools search the passed folders again when they change. OpenClaw watches the passed folders and refreshes its skill list on the next agent turn. With a duplicates policy, the adapter passes each selected skill’s folder instead of the entry’s folder, so a new skill written beside them loads only after the next start.
  • No volume lock: With runtime.keep_state, NeMo Fabric locks each agent’s state folder, so a second runtime of the same agent fails to start while the first one holds it. A skills volume has no such lock.

How the Adapter Loads directories

The adapter checks each entry in the task environment when the runtime starts, because that is where the folders are mounted. It checks the entries in list order.

Start Checks

Start fails when an entry breaks one of these rules:

ProblemFailure Reason
The path does not exist.not_found
The path is not a folder, or it cannot be accessed.invalid
A skill entry has no readable SKILL.md.invalid
A folder entry cannot be listed.invalid
Skills share a name under an explicit duplicates policy. Refer to Skills That Share a Name.duplicate
Under an explicit duplicates policy, the adapter can’t tell which name the harness reads for a skill. Refer to How the Adapter Reads a Skill.unsupported_frontmatter_name
Under an explicit duplicates policy, the adapter can’t tell whether the harness accepts a skill, and the policy’s result depends on it.unsupported_frontmatter

A not_found failure uses the adapter’s <adapter>_skill_not_found error code, such as hermes_skill_not_found. Every other failure uses <adapter>_skill_invalid. The adapter’s error metadata gives the failing field, such as skills.directories[1].skill, the reason, and the path. Through the SDK, the start error’s code is the adapter’s code, and its message includes that metadata. An adapter can add checks of its own. Refer to Harness Differences.

An empty folder entry is valid. It loads nothing, and the run report lists it.

Discovery Inside a Folder

A candidate is a folder that holds SKILL.md. The adapter searches a folder entry by the rules in its descriptor: how deep it searches, and whether it looks for more skills inside a skill. Refer to Harness Differences.

The following rules apply to every adapter that uses the shared NeMo Fabric loader:

  • A candidate that the harness refuses is skipped, never silently. The run report gives the reason, such as unreadable, no_name, invalid_frontmatter, missing_frontmatter_field:<field>, or empty_frontmatter_field:<field>. Each adapter guide lists the reasons its adapter uses.
  • A skipped candidate is never counted as a duplicate, so a copy the harness would refuse doesn’t fail a duplicates policy.
  • Discovery does not enter .git or node_modules folders, or other folders that the harness skips. Subfolders that cannot be read hold no skills.
  • The same folder reached through several entries loads once.
  • A skill’s name is the name field of its SKILL.md front matter. When the front matter has no name, the adapter uses the folder name if its descriptor allows that fallback. Otherwise it skips the skill with the reason no_name.

NeMo Fabric reads only the front matter. It never reports file contents.

How the Adapter Reads a Skill

After discovery, the adapter reads each candidate’s front matter once, at start. It finds the skill’s name and whether the harness accepts the skill. Each adapter reads with its harness’s own parser, so the names and refusals match what the harness loads. Refer to Harness Differences.

When an adapter can’t read a skill the way its harness does, for example because the harness’s parser can’t run, it reads only simple front matter: a single-line name: value, plain or quoted. Two problems can follow:

  • Uncertain name: The adapter can’t tell the harness’s name for a skill whose name is written another way, such as a block scalar, an anchor, an alias, a tag, or an explicit ? key. Without a duplicates policy, the skill keeps the name the adapter read, or its folder name. The run report marks it with "name_uncertain": true, and the adapter writes a warning. With a policy, start fails with unsupported_frontmatter_name, because a wrong name could pick the wrong copy. Write the name as a plain name: value to fix it.
  • Unknown validity: The adapter can’t tell whether the harness accepts a skill. It keeps the skill, because the harness may load it. With a policy, start fails with unsupported_frontmatter when the result for a name depends on whether that skill loads.

Bundled Skills

Some harnesses ship their own skills. skills.bundled chooses which of them load. It works with paths or directories, or with neither.

ConfigurationWhat Loads
bundled left outThe harness default.
bundled: {} or BundledSkills()Every eligible bundled skill.
enabled: falseNo bundled skills.
include: [a, b]Only bundled skills a and b.
include: []No bundled skills.
exclude: [a]Every bundled skill except a.
exclude: []Every eligible bundled skill.

Validation rejects these combinations:

  • include and exclude together, even when one is empty.
  • enabled: false with either list.
  • An empty name in either list.

The following example loads every bundled skill except github-auth:

skills:
bundled:
exclude: [github-auth]
from nemo_fabric import BundledSkills, SkillConfig
config.skills = SkillConfig(bundled=BundledSkills(exclude=["github-auth"]))

At start, the adapter reads the list of bundled skills from the installed harness, because that list changes between harness versions. A name in include or exclude that is not on the list fails start with <adapter>_skill_invalid and the reason unknown_bundled_skill. The error names the field and the name. Bundled selection does not bypass the harness’s own requirements for a skill, and it does not grant extra tools or permissions.

A bundled skill that bundled leaves out does not hide a configured or local skill with the same name.

Some harnesses always load certain bundled skills. An adapter that can’t leave them out doesn’t advertise supports_disable or supports_include, so planning rejects enabled: false and include. Use exclude to leave out the other bundled skills. Refer to Harness Differences.

Skills That Share a Name

skills.duplicates sets what happens when two directories entries supply skills with the same name. It requires directories.

ValueResult
Left outThe harness’s own behavior, as before.
rejectStart fails and names both entries.
first_winsThe earlier entry’s skill loads.
last_winsThe later entry’s skill loads.

The following rules apply:

  • A policy applies only between separate directories entries, in list order.
  • With any policy set, two skills with the same name inside one folder entry fail start. The error names the entry and both paths.
  • With first_wins or last_wins, the other copies do not load. The run report lists them.
  • A clash with a bundled skill or a skill in the harness’s own folders follows the harness’s own order. The policy does not change it.
  • When duplicates is left out, every copy reaches the harness unchanged and the harness decides. The run report lists each clash. Its outcome is ambiguous unless the adapter can tell which copy the harness loads.

Run Report

When a run uses directories, even an empty list, or bundled, the adapter adds a skills block to the result output. It leaves out empty parts. The block never includes file contents.

KeyContents
loadedEach loaded skill: name, path, and origin. The origin is external for a directories skill, which also has entry (the field that supplied it), bundled for a skill shipped with the harness, and local for a skill in the harness’s own folders, such as a workspace skill or one the agent installed. name_uncertain: true marks a skill whose name the adapter couldn’t read the way the harness does, so the harness may use a different name. Refer to How the Adapter Reads a Skill. An adapter that reports every skill its harness loads lists bundled and local skills too, and an empty loaded list then means no skill loads. Each adapter guide says which skills it lists.
empty_entriesThe fields of folder entries that found no skills.
skippedEach skipped candidate: path, entry, and reason.
duplicatesEach clash: name, outcome (selected, shadowed, or ambiguous), the selected path when known, and each copy’s origin (external, bundled, or local), path, and entry.
bundledselected: the selected bundled skills that load. unavailable: each selected bundled skill that does not load, with name and reason. An adapter guide lists any extra keys, such as Hermes’s essential.

The following example shows a report for the mixed setup. In this example, /mnt/team-skills also holds a release-review skill, its debugging skill has no description field that the harness requires, /mnt/agent-skills is empty, and the workspace holds a notes skill that the harness loads too:

{
"skills": {
"loaded": [
{"name": "code-review", "path": "/mnt/team-skills/code-review", "entry": "skills.directories[0]", "origin": "external"},
{"name": "release-review", "path": "/mnt/release-review", "entry": "skills.directories[2]", "origin": "external"},
{"name": "notes", "path": "/workspace/skills/notes", "origin": "local"}
],
"empty_entries": ["skills.directories[1]"],
"skipped": [
{"path": "/mnt/team-skills/debugging", "entry": "skills.directories[0]", "reason": "missing_frontmatter_field:description"}
],
"duplicates": [
{
"name": "release-review",
"outcome": "selected",
"selected": "/mnt/release-review",
"copies": [
{"origin": "external", "path": "/mnt/team-skills/release-review", "entry": "skills.directories[0]"},
{"origin": "external", "path": "/mnt/release-review", "entry": "skills.directories[2]"}
]
}
]
}
}

The adapter also writes one line to standard error for each skipped candidate, empty entry, clash, uncertain name, and unavailable bundled skill when the runtime starts.

The report shows what the adapter sees at start. A skill in one of the harness’s own folders, including a skill the agent writes, can hide a configured skill with the same name. The report lists these clashes where the adapter can see them at start, so a skill the agent writes later can hide a configured skill in later runtimes.

Adapter Support

Each Adapter Descriptor states which structured skill features its adapter implements, in a top-level skills block. Planning, plan(...), and doctor(...) check the configuration against that block before the runtime starts:

ConfigurationRequired Descriptor Support
A non-empty directoriesskills.directory_loading, with every entry kind used listed in supported_entries.
bundled with no listsskills.bundled.supports_enable
bundled.enabled: falseskills.bundled.supports_disable
bundled.include, including []skills.bundled.supports_include
bundled.exclude, including []skills.bundled.supports_exclude
duplicates: <policy>skills.duplicates.supported_policies lists the policy.

The adapter must also list skills in config.accepts. An unsupported request fails with the field and the reason. For example, a policy the adapter does not support fails at skills.duplicates, and the error lists the policies it does support. NeMo Fabric never drops a skill setting silently. paths keeps its existing check.

Refer to Stage 1: Describe the Adapter for the skills block fields.

Harness Differences

The OpenClaw and Hermes Agent adapters support directories, bundled, and duplicates. The LangChain Deep Agents adapter supports directories and duplicates; Deep Agents ships no bundled skills, so planning rejects bundled. The harnesses still load skills in different ways. This table is the one place that compares them. Each adapter guide covers the rest of its harness’s behavior.

BehaviorHermes AgentOpenClawLangChain Deep Agents
A paths entryPassed to skills.external_dirs without checks. Hermes Agent skips a missing path silently.Must be a folder that holds SKILL.md. Passed to skills.load.extraDirs.A folder that holds SKILL.md is one skill; any other folder is a folder of skills, loaded as for directories. An absolute path that exists only under the workspace, such as /.agents/skills, names that workspace folder. A missing path fails start.
Where directories entries goskills.external_dirs. With a duplicates policy, the adapter passes each selected skill’s folder instead. A folder that Hermes Agent already searches through another passed folder is not passed again.skills.load.extraDirs. With a duplicates policy, the adapter passes each selected skill’s folder instead, through the path it found the skill by, never a symbolic link’s target. A skill entry whose folder an earlier entry already supplies is not passed again.Each entry is a Deep Agents skills source, in list order. The adapter routes the entry’s selected skills into the Deep Agents backend at the path of the folder that holds them, so file tools and local_shell commands reach them where they are. Nothing is copied. A skill entry exposes only that skill, not its siblings.
How the adapter reads names and validityWith Hermes Agent’s own front-matter parser and skill catalog rules.With OpenClaw’s own front-matter parser, run through node. When the parser can’t run, the adapter reads simple front matter instead.With Deep Agents’ own front-matter parser.
Search inside a folder entryEvery level below the folder, with no fixed depth limit.2 levels deep, or 6 when the folder it searches is named skills. A skills subfolder directly inside the searched folder is searched 6 levels deep. When only the entry’s skills subfolder holds skills, OpenClaw searches that subfolder, and a skills subfolder that itself holds SKILL.md loads as one skill. A skill whose real folder is outside the searched folder does not load and is reported with the reason path_escape.The folder’s immediate child folders only.
A folder entry that holds SKILL.mdThe folder loads as a skill, along with the skills below it.Start fails with the reason folder_is_skill. Use a skill entry instead.The folder itself does not load. Its child folders that hold SKILL.md do. Use a skill entry for the folder.
Skills inside a skill’s folderAlso load. With a duplicates policy, start fails when a copy that should not load sits inside a selected skill’s folder.Do not load. Discovery stops at a skill’s folder, and at any folder holding an entry named SKILL.md, even a folder or a broken link. Such a SKILL.md is skipped with the reason unreadable.Do not load.
Folders discovery skipsThe folders Hermes Agent skips, such as .git, .hub, .archive, node_modules, venv, .venv, site-packages, and __pycache__, and a skill’s references, templates, assets, and scripts folders.Every folder whose name starts with ., and node_modules.None.
Required front-matter fieldsNonedescription, not empty after trimmingname and description
Name when the front matter has noneThe folder nameThe name of the folder OpenClaw reaches the skill through, so a symbolic link gives its own name. A folder entry that holds a skill and a link to it loads the skill under both names, and the run report lists both.No fallback. The skill is skipped with the reason invalid_frontmatter.
Front matter that does not parseSimple key: value lines are recovered.The skill is skipped with the reason invalid_frontmatter before duplicates applies. Under first_wins or last_wins, the next copy of its name loads instead. A hard-linked SKILL.md is skipped the same way, with the reason hardlinked_skill_file, and so is a SKILL.md that resolves outside its skill folder, with the reason path_escape.The skill is skipped with the reason invalid_frontmatter before duplicates applies.
Two configured skills share a name and duplicates is left outHermes Agent refuses both as ambiguous. It also refuses a skill whose name is another skill’s folder name.The copy from the later entry loads. Copies inside one entry are reported as ambiguous.The copy from the later entry loads, and the run report records the clash as selected. Copies inside one entry are reported as ambiguous.
The harness’s own skill folders, ranked above the configured entriesThe Hermes home’s skills folder, which holds the bundled skills and the skills the agent creates. Hermes Agent saves every new skill there, never in a directories entry.Highest first: the workspace’s skills and .agents/skills folders, then the state folder’s skills folder and the Skill Workshop folder, then the selected shipped skills. A directories entry inside a workspace folder keeps that folder’s rank, so it wins over a shipped skill with the same name. A copy OpenClaw refuses hides nothing.None. Deep Agents loads only the configured skills.
How bundled skills are chosenWhen the selection leaves out a bundled skill, Hermes Agent copies the selected bundled skills into its home from a per-runtime copy, read through HERMES_BUNDLED_SKILLS. Otherwise it copies from its installation.When the selection leaves out a shipped skill, OpenClaw reads a per-runtime copy of the selected shipped skills through OPENCLAW_BUNDLED_SKILLS_DIR. Otherwise it reads the package folder. The skills OpenClaw’s own extensions ship, such as canvas, are bundled skills too: a left-out one is turned off by name with skills.entries, unless another copy has its name. Start fails when the extension’s copy of a left-out name still loads, or when OpenClaw can’t say which copy loads.Deep Agents ships no bundled skills.
A bundled skill that bundled leaves out shares a name with a configured skillThe configured skill, from paths or directories, loads. The left-out bundled skill never reaches the Hermes home, so it hides nothing, and the agent’s own skill with that name in the Hermes home loads too. A changed earlier copy of the left-out skill in a kept home fails start.The configured skill loads. The left-out bundled skill is not loaded at all, so it hides nothing.Not applicable.
Bundled skills that always loadhermes-agent. Use bundled: {} or exclude, which can’t name it. The adapter doesn’t support include, even include: [] or include: [hermes-agent], or enabled: false, so planning rejects them.NoneNone
Error codeshermes_skill_not_found, hermes_skill_invalidopenclaw_skill_not_found, openclaw_skill_invaliddeepagents_skill_not_found, deepagents_skill_invalid

Refer to the Hermes Agent guide, the OpenClaw guide, and the LangChain Deep Agents guide for details.