|
| 1 | +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. |
| 2 | +# SPDX-License-Identifier: Apache-2.0 |
| 3 | +# |
| 4 | +# Licensed under the Apache License, Version 2.0 (the "License"); |
| 5 | +# you may not use this file except in compliance with the License. |
| 6 | +# You may obtain a copy of the License at |
| 7 | +# |
| 8 | +# http://www.apache.org/licenses/LICENSE-2.0 |
| 9 | +# |
| 10 | +# Unless required by applicable law or agreed to in writing, software |
| 11 | +# distributed under the License is distributed on an "AS IS" BASIS, |
| 12 | +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 13 | +# See the License for the specific language governing permissions and |
| 14 | +# limitations under the License. |
| 15 | +"""Agent skills: a directory of skills made available to an agent at rollout time. |
| 16 | +
|
| 17 | +Skills follow the open `Agent Skills standard <https://agentskills.io/specification>`_ |
| 18 | +used by Codex CLI and Claude Code. A skill is a *directory* containing a ``SKILL.md`` |
| 19 | +file (YAML frontmatter + markdown body) plus optional supporting files. The ``skills.path`` |
| 20 | +config points at a directory of such skill directories. |
| 21 | +
|
| 22 | +Skills are a run-level knob (specified on ``ng_collect_rollouts``), applied to a fixed, |
| 23 | +skill-agnostic dataset -- mirroring how ``prompt.py`` applies a prompt template. They are |
| 24 | +*not* a dataset-row field, so the same dataset is reusable across skill variants. Each |
| 25 | +rollout result is stamped with a ``skills_ref`` for provenance/grouping in reward profiling. |
| 26 | +
|
| 27 | +The ``skills_ref`` carries a content ``hash`` (a short sha256 over the skill directory's |
| 28 | +sorted relative paths + file bytes) so that variants that mutate a skill *in place* at the |
| 29 | +same path -- as optimizer loops like ACE, GEPA, and EvoSkill commonly do -- remain |
| 30 | +distinguishable when comparing rollouts. Identity is derived from bytes on disk, so it |
| 31 | +requires no cooperation from the optimizer. |
| 32 | +""" |
| 33 | + |
| 34 | +import hashlib |
| 35 | +import shutil |
| 36 | +from pathlib import Path |
| 37 | +from typing import List, Optional |
| 38 | + |
| 39 | +import yaml |
| 40 | +from pydantic import BaseModel, Field |
| 41 | + |
| 42 | +from nemo_gym import PARENT_DIR |
| 43 | + |
| 44 | + |
| 45 | +SKILL_MD_FILENAME = "SKILL.md" |
| 46 | +# 12 hex chars (48 bits) is plenty to separate the handful of variants in one experiment |
| 47 | +# while staying readable in tables / W&B. |
| 48 | +_HASH_PREFIX_LEN = 12 |
| 49 | + |
| 50 | + |
| 51 | +class SkillMetadata(BaseModel): |
| 52 | + """Metadata parsed from a single skill's ``SKILL.md`` YAML frontmatter.""" |
| 53 | + |
| 54 | + name: str |
| 55 | + description: Optional[str] = None |
| 56 | + version: Optional[str] = None |
| 57 | + |
| 58 | + |
| 59 | +class SkillsRef(BaseModel): |
| 60 | + """Provenance stamp describing the skills made available for a run. |
| 61 | +
|
| 62 | + Stamped onto rollout result rows (not source datasets). ``hash`` is a content |
| 63 | + digest so two skill *versions* at the same ``path`` do not collide in profiling. |
| 64 | + """ |
| 65 | + |
| 66 | + path: str |
| 67 | + hash: str |
| 68 | + skills: List[SkillMetadata] |
| 69 | + |
| 70 | + |
| 71 | +class SkillsConfig(BaseModel): |
| 72 | + """Run-level skills config: ``skills.path`` points at a directory of skill directories.""" |
| 73 | + |
| 74 | + path: str = Field(description="Directory of Agent Skills standard skill directories to make available.") |
| 75 | + |
| 76 | + |
| 77 | +def _resolve_skills_path(path: str) -> Path: |
| 78 | + """Resolve a skills path. Relative paths check cwd first, then the Gym root (PARENT_DIR). |
| 79 | +
|
| 80 | + This matches how ``input_jsonl_fpath`` and ``config_paths`` are resolved. |
| 81 | + """ |
| 82 | + p = Path(path) |
| 83 | + if p.is_absolute(): |
| 84 | + return p |
| 85 | + cwd_path = Path.cwd() / p |
| 86 | + return cwd_path if cwd_path.exists() else PARENT_DIR / p |
| 87 | + |
| 88 | + |
| 89 | +def hash_skill_dir(root: Path) -> str: |
| 90 | + """Compute a stable short sha256 over a skill directory's contents. |
| 91 | +
|
| 92 | + Walks files in sorted relative-path order, folding each file's relative path and bytes |
| 93 | + into the digest. Including the relative path means renaming or adding/removing files also |
| 94 | + changes the hash -- a skill *is* its file layout, not just ``SKILL.md``'s bytes. |
| 95 | + """ |
| 96 | + h = hashlib.sha256() |
| 97 | + for file_path in sorted(p for p in root.rglob("*") if p.is_file()): |
| 98 | + h.update(file_path.relative_to(root).as_posix().encode()) |
| 99 | + h.update(b"\0") |
| 100 | + h.update(file_path.read_bytes()) |
| 101 | + h.update(b"\0") |
| 102 | + return h.hexdigest()[:_HASH_PREFIX_LEN] |
| 103 | + |
| 104 | + |
| 105 | +def parse_skill_md(skill_md_path: Path) -> SkillMetadata: |
| 106 | + """Parse a ``SKILL.md`` file's YAML frontmatter into ``SkillMetadata``. |
| 107 | +
|
| 108 | + Frontmatter is delimited by lines containing only ``---``. Raises ``ValueError`` with a |
| 109 | + clear message if the frontmatter is missing, malformed, or lacks a ``name``. |
| 110 | + """ |
| 111 | + # utf-8-sig transparently strips a leading BOM if present; Claude Code's own loader tolerates |
| 112 | + # one, so a BOM should not make Gym reject a skill that would otherwise run. |
| 113 | + text = skill_md_path.read_text(encoding="utf-8-sig", errors="replace") |
| 114 | + lines = text.splitlines() |
| 115 | + if not lines or lines[0].strip() != "---": |
| 116 | + raise ValueError( |
| 117 | + f"Skill file {skill_md_path} is missing YAML frontmatter. " |
| 118 | + f"It must start with a '---' line followed by 'name:' and 'description:' fields." |
| 119 | + ) |
| 120 | + |
| 121 | + closing_idx = None |
| 122 | + for idx in range(1, len(lines)): |
| 123 | + if lines[idx].strip() == "---": |
| 124 | + closing_idx = idx |
| 125 | + break |
| 126 | + if closing_idx is None: |
| 127 | + raise ValueError( |
| 128 | + f"Skill file {skill_md_path} has an unterminated YAML frontmatter block (no closing '---' line)." |
| 129 | + ) |
| 130 | + |
| 131 | + frontmatter_text = "\n".join(lines[1:closing_idx]) |
| 132 | + try: |
| 133 | + data = yaml.safe_load(frontmatter_text) or {} |
| 134 | + except yaml.YAMLError as e: |
| 135 | + raise ValueError(f"Skill file {skill_md_path} has malformed YAML frontmatter: {e}") from None |
| 136 | + if not isinstance(data, dict): |
| 137 | + raise ValueError(f"Skill file {skill_md_path} frontmatter must be a YAML mapping, got {type(data).__name__}.") |
| 138 | + if not data.get("name"): |
| 139 | + raise ValueError(f"Skill file {skill_md_path} frontmatter is missing a required 'name' field.") |
| 140 | + |
| 141 | + # The Agent Skills spec nests version under an optional `metadata:` map |
| 142 | + # (e.g. `metadata: {version: "1.0"}`), not as a top-level key. |
| 143 | + metadata = data.get("metadata") |
| 144 | + version = str(metadata["version"]) if isinstance(metadata, dict) and metadata.get("version") is not None else None |
| 145 | + return SkillMetadata( |
| 146 | + name=str(data["name"]), |
| 147 | + description=data.get("description"), |
| 148 | + version=version, |
| 149 | + ) |
| 150 | + |
| 151 | + |
| 152 | +def load_skill_directory(path: str) -> SkillsRef: |
| 153 | + """Load a directory of skills, returning a ``SkillsRef`` (path, content hash, metadata). |
| 154 | +
|
| 155 | + The directory at ``path`` contains one subdirectory per skill, each with a ``SKILL.md``. |
| 156 | + Raises ``ValueError`` with an actionable message if the path is missing, is not a |
| 157 | + directory, contains no skills, or contains a malformed skill. |
| 158 | + """ |
| 159 | + resolved = _resolve_skills_path(path) |
| 160 | + if not resolved.exists(): |
| 161 | + raise ValueError(f"Skills path does not exist: {resolved} (from skills.path={path!r}).") |
| 162 | + if not resolved.is_dir(): |
| 163 | + raise ValueError( |
| 164 | + f"Skills path must be a directory of skill directories, but {resolved} is a file " |
| 165 | + f"(from skills.path={path!r})." |
| 166 | + ) |
| 167 | + |
| 168 | + skill_dirs = sorted(d for d in resolved.iterdir() if d.is_dir()) |
| 169 | + skills: List[SkillMetadata] = [] |
| 170 | + for skill_dir in skill_dirs: |
| 171 | + skill_md = skill_dir / SKILL_MD_FILENAME |
| 172 | + if not skill_md.is_file(): |
| 173 | + raise ValueError( |
| 174 | + f"Skill directory {skill_dir} is missing a {SKILL_MD_FILENAME} file. " |
| 175 | + f"Each skill must be a directory containing a {SKILL_MD_FILENAME}." |
| 176 | + ) |
| 177 | + skills.append(parse_skill_md(skill_md)) |
| 178 | + |
| 179 | + if not skills: |
| 180 | + raise ValueError( |
| 181 | + f"Skills path {resolved} contains no skills. Expected one or more subdirectories, " |
| 182 | + f"each containing a {SKILL_MD_FILENAME} file (from skills.path={path!r})." |
| 183 | + ) |
| 184 | + |
| 185 | + return SkillsRef(path=path, hash=hash_skill_dir(resolved), skills=skills) |
| 186 | + |
| 187 | + |
| 188 | +def stage_skills(path: str, dest_skills_dir: Path) -> None: |
| 189 | + """Copy the directory of skills at ``path`` into ``dest_skills_dir``. |
| 190 | +
|
| 191 | + Used by agent runtimes to materialize skills into a location their native discovery |
| 192 | + mechanism scans (e.g. ``<CLAUDE_CONFIG_DIR>/skills/`` for Claude Code). ``dest_skills_dir`` |
| 193 | + must not already exist. Raises ``ValueError`` if the source path is missing or not a directory. |
| 194 | + """ |
| 195 | + resolved = _resolve_skills_path(path) |
| 196 | + if not resolved.is_dir(): |
| 197 | + raise ValueError( |
| 198 | + f"Cannot stage skills: {resolved} is not a directory (from skills path {path!r}). " |
| 199 | + f"For distributed runs the skills directory must be on storage accessible to the agent." |
| 200 | + ) |
| 201 | + shutil.copytree(resolved, dest_skills_dir) |
0 commit comments