> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/nemo/gym/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/nemo/gym/_mcp/server.

# nemo_gym.skills

Agent skills: a directory of skills made available to an agent at rollout time.

Skills follow the open `Agent Skills standard <https://agentskills.io/specification>`\_
used by Codex CLI and Claude Code. A skill is a *directory* containing a `SKILL.md`
file (YAML frontmatter + markdown body) plus optional supporting files. The `skills.path`
config points at a directory of such skill directories.

Skills are a run-level knob (specified on `gym eval run`), applied to a fixed,
skill-agnostic dataset -- mirroring how `prompt.py` applies a prompt template. They are
*not* a dataset-row field, so the same dataset is reusable across skill variants. Each
rollout result is stamped with a `skills_ref` for provenance/grouping in reward profiling.

The `skills_ref` carries a content `hash` (a short sha256 over the skill directory's
sorted relative paths + file bytes) so that variants that mutate a skill *in place* at the
same path -- as optimizer loops like ACE, GEPA, and EvoSkill commonly do -- remain
distinguishable when comparing rollouts. Identity is derived from bytes on disk, so it
requires no cooperation from the optimizer.

## Module Contents

### Classes

| Name                                              | Description                                                                        |
| ------------------------------------------------- | ---------------------------------------------------------------------------------- |
| [`SkillMetadata`](#nemo_gym-skills-SkillMetadata) | Metadata parsed from a single skill's `SKILL.md` YAML frontmatter.                 |
| [`SkillsConfig`](#nemo_gym-skills-SkillsConfig)   | Run-level skills config: `skills.path` points at a directory of skill directories. |
| [`SkillsRef`](#nemo_gym-skills-SkillsRef)         | Provenance stamp describing the skills made available for a run.                   |

### Functions

| Name                                                            | Description                                                                             |
| --------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| [`_resolve_skills_path`](#nemo_gym-skills-_resolve_skills_path) | Resolve a skills path. Relative paths check cwd first, then the Gym root (PARENT\_DIR). |
| [`hash_skill_dir`](#nemo_gym-skills-hash_skill_dir)             | Compute a stable short sha256 over a skill directory's contents.                        |
| [`load_skill_directory`](#nemo_gym-skills-load_skill_directory) | Load a directory of skills, returning a `SkillsRef` (path, content hash, metadata).     |
| [`parse_skill_md`](#nemo_gym-skills-parse_skill_md)             | Parse a `SKILL.md` file's YAML frontmatter into `SkillMetadata`.                        |
| [`stage_skills`](#nemo_gym-skills-stage_skills)                 | Copy the directory of skills at `path` into `dest_skills_dir`.                          |

### Data

[`SKILL_MD_FILENAME`](#nemo_gym-skills-SKILL_MD_FILENAME)

[`_HASH_PREFIX_LEN`](#nemo_gym-skills-_HASH_PREFIX_LEN)

### API

```python
class nemo_gym.skills.SkillMetadata()
```

**Bases:** `BaseModel`

Metadata parsed from a single skill's `SKILL.md` YAML frontmatter.

```python
class nemo_gym.skills.SkillsConfig()
```

**Bases:** `BaseModel`

Run-level skills config: `skills.path` points at a directory of skill directories.

```python
class nemo_gym.skills.SkillsRef()
```

**Bases:** `BaseModel`

Provenance stamp describing the skills made available for a run.

Stamped onto rollout result rows (not source datasets). `hash` is a content
digest so two skill *versions* at the same `path` do not collide in profiling.

```python
nemo_gym.skills._resolve_skills_path(
    path: str
) -> pathlib.Path
```

Resolve a skills path. Relative paths check cwd first, then the Gym root (PARENT\_DIR).

This matches how `input_jsonl_fpath` and `config_paths` are resolved.

```python
nemo_gym.skills.hash_skill_dir(
    root: pathlib.Path
) -> str
```

Compute a stable short sha256 over a skill directory's contents.

Walks files in sorted relative-path order, folding each file's relative path and bytes
into the digest. Including the relative path means renaming or adding/removing files also
changes the hash -- a skill *is* its file layout, not just `SKILL.md`'s bytes.

```python
nemo_gym.skills.load_skill_directory(
    path: str
) -> nemo_gym.skills.SkillsRef
```

Load a directory of skills, returning a `SkillsRef` (path, content hash, metadata).

The directory at `path` contains one subdirectory per skill, each with a `SKILL.md`.
Raises `ValueError` with an actionable message if the path is missing, is not a
directory, contains no skills, or contains a malformed skill.

```python
nemo_gym.skills.parse_skill_md(
    skill_md_path: pathlib.Path
) -> nemo_gym.skills.SkillMetadata
```

Parse a `SKILL.md` file's YAML frontmatter into `SkillMetadata`.

Frontmatter is delimited by lines containing only `---`. Raises `ValueError` with a
clear message if the frontmatter is missing, malformed, or lacks a `name`.

```python
nemo_gym.skills.stage_skills(
    path: str,
    dest_skills_dir: pathlib.Path
) -> None
```

Copy the directory of skills at `path` into `dest_skills_dir`.

Used by agent runtimes to materialize skills into a location their native discovery
mechanism scans (e.g. `<CLAUDE_CONFIG_DIR>/skills/` for Claude Code). `dest_skills_dir`
must not already exist. Raises `ValueError` if the source path is missing or not a directory.

```python
nemo_gym.skills.SKILL_MD_FILENAME = 'SKILL.md'
```

```python
nemo_gym.skills._HASH_PREFIX_LEN = 12
```