Configure Skills
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:
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 readableSKILL.md.folder: a folder of skills. The adapter finds the skills inside it.
The following rules apply:
- Set
directoriesonly whenpathsis empty.paths: []is the same as leavingpathsout. - 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
pathsdo. NeMo Fabric does not expand~or environment variables such as${VAR}.
The following layout contains five skills:
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:
Load Chosen Skills, Read-Only
Mount each skill read-only, then add one skill entry for each skill:
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.
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:
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_managetool 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
duplicatespolicy, 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:
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>, orempty_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
duplicatespolicy. - Discovery does not enter
.gitornode_modulesfolders, 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
namefield of itsSKILL.mdfront 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 reasonno_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
nameis written another way, such as a block scalar, an anchor, an alias, a tag, or an explicit?key. Without aduplicatespolicy, 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 withunsupported_frontmatter_name, because a wrong name could pick the wrong copy. Write the name as a plainname: valueto 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_frontmatterwhen 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.
Validation rejects these combinations:
includeandexcludetogether, even when one is empty.enabled: falsewith either list.- An empty name in either list.
The following example loads every bundled skill except 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.
The following rules apply:
- A policy applies only between separate
directoriesentries, in list order. - With any policy set, two skills with the same name inside one
folderentry fail start. The error names the entry and both paths. - With
first_winsorlast_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
duplicatesis left out, every copy reaches the harness unchanged and the harness decides. The run report lists each clash. Its outcome isambiguousunless 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.
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:
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:
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.
Refer to the Hermes Agent guide, the OpenClaw guide, and the LangChain Deep Agents guide for details.