diff --git a/python/packages/core/AGENTS.md b/python/packages/core/AGENTS.md index fafbc55f2f..edd4eaa158 100644 --- a/python/packages/core/AGENTS.md +++ b/python/packages/core/AGENTS.md @@ -69,7 +69,8 @@ agent_framework/ ### Skills (`_skills.py`) -- **`Skill`** - A skill definition bundling instructions (`content`) with metadata, resources, and scripts. Supports `@skill.resource` and `@skill.script` decorators for adding components. +- **`Skill`** - Abstract base for a skill definition bundling instructions (`content`) with frontmatter metadata, resources, and scripts. Concrete subclasses (`InlineSkill`, `FileSkill`, `ClassSkill`) accept a `frontmatter=SkillFrontmatter(...)` argument carrying the spec fields. Adding new spec fields is done in one place — on `SkillFrontmatter` — keeping the subclass constructors stable. +- **`SkillFrontmatter`** - L1 discovery metadata for a skill (`name`, `description`, `license`, `compatibility`, `allowed_tools`, `metadata`). All fields are mutable plain attributes; the constructor validates `name`, `description`, and `compatibility` against the spec but post-construction assignments are not re-validated. Spec fields are reachable on every skill via `skill.frontmatter`. - **`SkillResource`** - Named supplementary content attached to a skill; holds either static `content` or a dynamic `function` (sync or async). Exactly one must be provided. - **`SkillScript`** - An executable script attached to a skill; holds either an inline `function` (code-defined, runs in-process) or a `path` to a file on disk (file-based, delegated to a runner). Exactly one must be provided. - **`SkillScriptRunner`** - Protocol for file-based script execution. Any callable matching `(skill, script, args) -> Any` satisfies it. Code-defined scripts do not use a runner. diff --git a/python/packages/core/agent_framework/__init__.py b/python/packages/core/agent_framework/__init__.py index db1c43abfe..356051da3f 100644 --- a/python/packages/core/agent_framework/__init__.py +++ b/python/packages/core/agent_framework/__init__.py @@ -147,6 +147,7 @@ InlineSkillScript, InMemorySkillsSource, Skill, + SkillFrontmatter, SkillResource, SkillScript, SkillScriptRunner, @@ -432,6 +433,7 @@ "SessionContext", "SingleEdgeGroup", "Skill", + "SkillFrontmatter", "SkillResource", "SkillScript", "SkillScriptRunner", diff --git a/python/packages/core/agent_framework/_skills.py b/python/packages/core/agent_framework/_skills.py index 44755a2efd..1128a938ea 100644 --- a/python/packages/core/agent_framework/_skills.py +++ b/python/packages/core/agent_framework/_skills.py @@ -465,41 +465,23 @@ class Skill(ABC): A skill represents a domain-specific capability with instructions, resources, and scripts. Concrete implementations include - :class:`FileSkill` (filesystem-backed) and :class:`InlineSkill` - (code-defined). + :class:`FileSkill` (filesystem-backed), :class:`InlineSkill` + (code-defined), and :class:`ClassSkill` (class-based). - Skill metadata follows the - `Agent Skills specification `_. - - Attributes: - name: Skill name (lowercase letters, numbers, hyphens only). - description: Human-readable description of the skill. + Skill spec metadata (name, description, license, compatibility, + allowed_tools, metadata) is exposed via the :attr:`frontmatter` + property, which returns a :class:`SkillFrontmatter` instance. """ - def __init__( - self, - *, - name: str, - description: str, - ) -> None: - """Initialize a Skill. - - Validates the skill name and description against specification rules. - - Args: - name: Skill name (lowercase letters, numbers, hyphens only; - max 64 characters; no leading/trailing/consecutive hyphens). - description: Human-readable description of the skill - (≤1024 characters). + @property + @abstractmethod + def frontmatter(self) -> SkillFrontmatter: + """The L1 discovery metadata for this skill. - Raises: - ValueError: If the name or description is invalid. + Contains the name, description, and other spec fields as defined by + the `Agent Skills specification `_. """ - _validate_skill_name(name) - _validate_skill_description(name, description) - - self.name = name - self.description = description + ... @property @abstractmethod @@ -535,6 +517,68 @@ def scripts(self) -> list[SkillScript]: return [] +@experimental(feature_id=ExperimentalFeature.SKILLS) +class SkillFrontmatter: + """L1 discovery metadata for a :class:`Skill`. + + Encapsulates all `Agent Skills specification `_ + frontmatter fields in a single object. All fields are mutable plain + attributes; callers may freely reassign them after construction. + + The constructor validates ``name``, ``description``, and ``compatibility`` + against specification rules and raises :class:`ValueError` on invalid + input. Assignments made after construction are **not** re-validated; + callers are expected to honor the spec. + + Attributes: + name: Skill name (lowercase letters, numbers, hyphens only). + description: Human-readable description of the skill. + license: Optional license name or reference. + compatibility: Optional compatibility information (≤500 characters). + allowed_tools: Optional space-delimited pre-approved tool names. + metadata: Optional arbitrary key-value pairs (shallow-copied on + construction to avoid caller-owned dict aliasing). + """ + + def __init__( + self, + *, + name: str, + description: str, + license: str | None = None, + compatibility: str | None = None, + allowed_tools: str | None = None, + metadata: dict[str, str] | None = None, + ) -> None: + """Initialize a SkillFrontmatter. + + Args: + name: Skill name (lowercase letters, numbers, hyphens only; + max 64 characters; no leading/trailing/consecutive hyphens). + description: Human-readable description of the skill + (≤1024 characters). + license: Optional license name or reference. + compatibility: Optional compatibility information + (≤500 characters). + allowed_tools: Optional space-delimited pre-approved tool names. + metadata: Optional arbitrary key-value pairs. + + Raises: + ValueError: If the name, description, or compatibility is invalid. + """ + _validate_skill_name(name) + _validate_skill_description(name, description) + _validate_compatibility(compatibility) + + self.name = name + self.description = description + self.compatibility = compatibility + self.license = license + self.allowed_tools = allowed_tools + # Shallow-copy to avoid aliasing with caller-owned dict. + self.metadata: dict[str, str] | None = dict(metadata) if metadata is not None else None + + def _validate_skill_name(name: str) -> None: """Validate a skill name against specification rules. @@ -573,6 +617,21 @@ def _validate_skill_description(name: str, description: str) -> None: ) +def _validate_compatibility(compatibility: str | None) -> None: + """Validate an optional compatibility value against specification rules. + + Args: + compatibility: The optional compatibility value to validate. + + Raises: + ValueError: If the value exceeds the maximum allowed length. + """ + if compatibility is not None and len(compatibility) > MAX_COMPATIBILITY_LENGTH: + raise ValueError( + f"Skill compatibility must be {MAX_COMPATIBILITY_LENGTH} characters or fewer." + ) + + def _build_skill_content( name: str, description: str, @@ -639,23 +698,17 @@ class InlineSkill(Skill): All resources and scripts should be configured before the skill is registered with a :class:`SkillsProvider`. - Attributes: - name: Skill name (lowercase letters, numbers, hyphens only). - description: Human-readable description of the skill. - instructions: The skill instructions text. - Examples: - With the decorator: - .. code-block:: python skill = InlineSkill( - name="db-skill", - description="Database operations", + frontmatter=SkillFrontmatter( + name="db-skill", + description="Database operations", + ), instructions="Use this skill for DB tasks.", ) - @skill.resource def get_schema() -> str: return "CREATE TABLE ..." @@ -664,8 +717,7 @@ def get_schema() -> str: def __init__( self, *, - name: str, - description: str, + frontmatter: SkillFrontmatter, instructions: str, resources: Sequence[SkillResource] | None = None, scripts: Sequence[SkillScript] | None = None, @@ -673,19 +725,25 @@ def __init__( """Initialize an InlineSkill. Args: - name: Skill name (lowercase letters, numbers, hyphens only). - description: Human-readable description of the skill (≤1024 chars). + frontmatter: Skill specification metadata (name, description, + and optional spec fields). Construct a :class:`SkillFrontmatter` + with the desired fields. instructions: The skill instructions text. resources: Pre-built resources to attach to this skill. scripts: Pre-built scripts to attach to this skill. """ - super().__init__(name=name, description=description) + self._frontmatter = frontmatter self.instructions = instructions self._resources: list[SkillResource] = list(resources) if resources is not None else [] self._scripts: list[SkillScript] = list(scripts) if scripts is not None else [] self._cached_content: str | None = None + @property + def frontmatter(self) -> SkillFrontmatter: + """The L1 discovery metadata for this skill.""" + return self._frontmatter + @property def content(self) -> str: """Synthesized XML content with name, description, instructions, resources, and scripts. @@ -697,7 +755,11 @@ def content(self) -> str: return self._cached_content self._cached_content = _build_skill_content( - self.name, self.description, self.instructions, self._resources, self._scripts + self._frontmatter.name, + self._frontmatter.description, + self.instructions, + self._resources, + self._scripts, ) return self._cached_content @@ -932,10 +994,6 @@ class ClassSkill(Skill, ABC): Class-based skills can be distributed via shared libraries or PyPI packages, making them easy to reuse across projects. - Attributes: - name: Skill name (lowercase letters, numbers, hyphens only). - description: Human-readable description of the skill. - Examples: Decorator-based (recommended): @@ -944,8 +1002,10 @@ class ClassSkill(Skill, ABC): class UnitConverterSkill(ClassSkill): def __init__(self) -> None: super().__init__( - name="unit-converter", - description="Convert between common units.", + frontmatter=SkillFrontmatter( + name="unit-converter", + description="Convert between common units.", + ), ) @property @@ -967,8 +1027,10 @@ def convert(self, value: float, factor: float) -> str: class UnitConverterSkill(ClassSkill): def __init__(self) -> None: super().__init__( - name="unit-converter", - description="Convert between common units.", + frontmatter=SkillFrontmatter( + name="unit-converter", + description="Convert between common units.", + ), ) @property @@ -989,22 +1051,25 @@ def scripts(self) -> list[SkillScript]: def __init__( self, *, - name: str, - description: str, + frontmatter: SkillFrontmatter, ) -> None: """Initialize a ClassSkill. Args: - name: Skill name (lowercase letters, numbers, hyphens only; - max 64 characters). - description: Human-readable description of the skill - (≤1024 characters). + frontmatter: Skill specification metadata (name, description, + and optional spec fields). Construct a :class:`SkillFrontmatter` + with the desired fields. """ - super().__init__(name=name, description=description) + self._frontmatter = frontmatter self._cached_content: str | None = None self._cached_resources: list[SkillResource] | None = None self._cached_scripts: list[SkillScript] | None = None + @property + def frontmatter(self) -> SkillFrontmatter: + """The L1 discovery metadata for this skill.""" + return self._frontmatter + @staticmethod def resource( func: Callable[..., Any] | None = None, @@ -1152,7 +1217,7 @@ def resources(self) -> list[SkillResource]: resource_name = marker.get("name") or _make_method_name(attr_name) if resource_name in seen_names: raise ValueError( - f"Skill '{self.name}' already has a resource named '{resource_name}'. " + f"Skill '{self._frontmatter.name}' already has a resource named '{resource_name}'. " "Ensure each @ClassSkill.resource has a unique name." ) seen_names.add(resource_name) @@ -1212,7 +1277,7 @@ def scripts(self) -> list[SkillScript]: script_name = marker.get("name") or _make_method_name(attr_name) if script_name in seen_names: raise ValueError( - f"Skill '{self.name}' already has a script named '{script_name}'. " + f"Skill '{self._frontmatter.name}' already has a script named '{script_name}'. " "Ensure each @ClassSkill.script has a unique name." ) seen_names.add(script_name) @@ -1240,7 +1305,11 @@ def content(self) -> str: return self._cached_content self._cached_content = _build_skill_content( - self.name, self.description, self.instructions, self.resources, self.scripts + self._frontmatter.name, + self._frontmatter.description, + self.instructions, + self.resources, + self.scripts, ) return self._cached_content @@ -1250,16 +1319,13 @@ class FileSkill(Skill): """A :class:`Skill` discovered from a filesystem directory backed by a SKILL.md file. Attributes: - name: Skill name (lowercase letters, numbers, hyphens only). - description: Human-readable description of the skill. path: Absolute path to the directory containing this skill. """ def __init__( self, *, - name: str, - description: str, + frontmatter: SkillFrontmatter, content: str, path: str, resources: Sequence[SkillResource] | None = None, @@ -1268,20 +1334,26 @@ def __init__( """Initialize a FileSkill. Args: - name: Skill name (lowercase letters, numbers, hyphens only). - description: Human-readable description of the skill (≤1024 chars). + frontmatter: Skill specification metadata parsed from the + SKILL.md file's YAML frontmatter (name, description, + and optional spec fields). content: The full raw SKILL.md file content including YAML frontmatter. path: Absolute path to the skill directory on disk. resources: Resources discovered for this skill. scripts: Scripts discovered for this skill. """ - super().__init__(name=name, description=description) + self._frontmatter = frontmatter self._content = content self.path = path self._resources: list[SkillResource] = list(resources) if resources is not None else [] self._scripts: list[SkillScript] = list(scripts) if scripts is not None else [] + @property + def frontmatter(self) -> SkillFrontmatter: + """The L1 discovery metadata for this skill.""" + return self._frontmatter + @property def content(self) -> str: """The skill content provided at construction time.""" @@ -1346,6 +1418,7 @@ def __call__(self, skill: FileSkill, script: FileSkillScript, args: dict[str, An MAX_SEARCH_DEPTH: Final[int] = 2 MAX_NAME_LENGTH: Final[int] = 64 MAX_DESCRIPTION_LENGTH: Final[int] = 1024 +MAX_COMPATIBILITY_LENGTH: Final[int] = 500 DEFAULT_RESOURCE_EXTENSIONS: Final[tuple[str, ...]] = ( ".md", ".json", @@ -1366,10 +1439,24 @@ def __call__(self, skill: FileSkill, script: FileSkillScript, args: dict[str, An re.MULTILINE | re.DOTALL, ) -# Matches YAML "key: value" lines. Group 1 = key, Group 2 = quoted value, -# Group 3 = unquoted value. +# Matches top-level YAML "key: value" lines (unindented). Group 1 = key, +# Group 2 = quoted value, Group 3 = unquoted value. Only matches keys at +# column 0 so that indented children (e.g. under "metadata:") are not +# mistakenly captured as top-level fields. YAML_KV_RE = re.compile( - r"^\s*(\w+)\s*:\s*(?:[\"'](.+?)[\"']|(.+?))\s*$", + r"^([\w-]+)\s*:\s*(?:[\"'](.+?)[\"']|(.+?))\s*$", + re.MULTILINE, +) + +# Matches a YAML "metadata:" block followed by indented key-value pairs. +YAML_METADATA_BLOCK_RE = re.compile( + r"^metadata\s*:\s*$\n((?:[ \t]+\S.*\n?)+)", + re.MULTILINE, +) + +# Matches indented "key: value" lines within a metadata block. +YAML_INDENTED_KV_RE = re.compile( + r"^\s+([\w-]+)\s*:\s*(?:[\"'](.+?)[\"']|(.+?))\s*$", re.MULTILINE, ) @@ -1377,6 +1464,7 @@ def __call__(self, skill: FileSkill, script: FileSkillScript, args: dict[str, An # must not start or end with a hyphen, and must not contain consecutive hyphens. VALID_NAME_RE = re.compile(r"^[a-z0-9]([a-z0-9]*-[a-z0-9])*[a-z0-9]*$") + # Default system prompt template for advertising available skills to the model. # Use {skills} as the placeholder for the generated skills XML list. DEFAULT_SKILLS_INSTRUCTION_PROMPT = """\ @@ -1463,7 +1551,7 @@ class SkillsProvider(ContextProvider): FileSkillsSource("./skills", script_runner=my_runner), InMemorySkillsSource([my_code_skill]), ]), - predicate=lambda s: s.name != "internal", + predicate=lambda s: s.frontmatter.name != "internal", ) ) provider = SkillsProvider(source) @@ -1698,10 +1786,10 @@ def _create_instructions( lines: list[str] = [] # Sort by name for deterministic output - for skill in sorted(skills, key=lambda s: s.name): + for skill in sorted(skills, key=lambda s: s.frontmatter.name): lines.append(" ") - lines.append(f" {xml_escape(skill.name)}") - lines.append(f" {xml_escape(skill.description)}") + lines.append(f" {xml_escape(skill.frontmatter.name)}") + lines.append(f" {xml_escape(skill.frontmatter.description)}") lines.append(" ") return template.format( @@ -1920,7 +2008,7 @@ async def _run_script( def _find_skill(skills: Sequence[Skill], name: str) -> Skill | None: """Find a skill by name (case-insensitive linear scan).""" name_lower = name.lower() - return next((s for s in skills if s.name.lower() == name_lower), None) + return next((s for s in skills if s.frontmatter.name.lower() == name_lower), None) def _load_skill(self, skills: Sequence[Skill], skill_name: str) -> str: """Return the full content for the named skill. @@ -2179,19 +2267,18 @@ async def get_skills(self) -> list[Skill]: if parsed is None: continue - name, description, content = parsed + frontmatter, content = parsed - if name in skills: + if frontmatter.name in skills: logger.warning( "Duplicate skill name '%s': skill from '%s' skipped in favor of existing skill", - name, + frontmatter.name, skill_path, ) continue file_skill = FileSkill( - name=name, - description=description, + frontmatter=frontmatter, content=content, path=skill_path, ) @@ -2208,8 +2295,8 @@ async def get_skills(self) -> list[Skill]: FileSkillScript(name=sn, full_path=script_full_path, runner=self._script_runner) ) - skills[file_skill.name] = file_skill - logger.info("Loaded skill: %s", file_skill.name) + skills[file_skill.frontmatter.name] = file_skill + logger.info("Loaded skill: %s", file_skill.frontmatter.name) logger.info("Successfully loaded %d skills", len(skills)) return list(skills.values()) @@ -2438,8 +2525,9 @@ def _validate_skill_metadata( name: str | None, description: str | None, source: str, + compatibility: str | None = None, ) -> str | None: - """Validate a skill's name and description against naming rules. + """Validate a skill's name, description, and compatibility against naming rules. Enforces length limits, character-set restrictions, and non-emptiness for both file-based and code-defined skills. @@ -2449,6 +2537,7 @@ def _validate_skill_metadata( description: Skill description to validate. source: Human-readable label for diagnostics (e.g. a file path or ``"code skill"``). + compatibility: Optional compatibility value to validate. Returns: A diagnostic error string if validation fails, or ``None`` if valid. @@ -2472,24 +2561,32 @@ def _validate_skill_metadata( f"Must be {MAX_DESCRIPTION_LENGTH} characters or fewer." ) + if compatibility is not None and len(compatibility) > MAX_COMPATIBILITY_LENGTH: + return ( + f"Skill '{name}' from '{source}' has an invalid compatibility: " + f"Must be {MAX_COMPATIBILITY_LENGTH} characters or fewer." + ) + return None @staticmethod def _extract_frontmatter( content: str, skill_file_path: str, - ) -> tuple[str, str] | None: + ) -> SkillFrontmatter | None: """Extract and validate YAML frontmatter from a SKILL.md file. - Parses the ``---``-delimited frontmatter block for ``name`` and - ``description`` fields. + Parses the ``---``-delimited frontmatter block for all + `agentskills.io specification `_ + fields: ``name``, ``description``, ``license``, ``compatibility``, + ``allowed-tools``, and ``metadata``. Args: content: Raw text content of the SKILL.md file. skill_file_path: Path to the file (used in diagnostic messages only). Returns: - A ``(name, description)`` tuple on success, or ``None`` if the + A :class:`SkillFrontmatter` on success, or ``None`` if the frontmatter is missing, malformed, or fails validation. """ match = FRONTMATTER_RE.search(content) @@ -2500,35 +2597,63 @@ def _extract_frontmatter( yaml_content = match.group(1).strip() name: str | None = None description: str | None = None + license_value: str | None = None + compatibility: str | None = None + allowed_tools: str | None = None for kv_match in YAML_KV_RE.finditer(yaml_content): key = kv_match.group(1) value = kv_match.group(2) if kv_match.group(2) is not None else kv_match.group(3) - if key.lower() == "name": + key_lower = key.lower() + if key_lower == "name": name = value - elif key.lower() == "description": + elif key_lower == "description": description = value - - error = FileSkillsSource._validate_skill_metadata(name, description, skill_file_path) + elif key_lower == "license": + license_value = value + elif key_lower == "compatibility": + compatibility = value + elif key_lower == "allowed-tools": + allowed_tools = value + + # Parse metadata block (indented key-value pairs under "metadata:"). + metadata: dict[str, str] | None = None + metadata_match = YAML_METADATA_BLOCK_RE.search(yaml_content) + if metadata_match: + metadata = {} + for kv_match in YAML_INDENTED_KV_RE.finditer(metadata_match.group(1)): + mk = kv_match.group(1) + mv = kv_match.group(2) if kv_match.group(2) is not None else kv_match.group(3) + metadata[mk] = mv + + error = FileSkillsSource._validate_skill_metadata(name, description, skill_file_path, compatibility) if error: logger.error(error) return None - # name and description are guaranteed non-None after validation - return name, description # type: ignore[return-value] + # name and description are guaranteed non-None after validation; + # SkillFrontmatter re-validates as a defense-in-depth invariant. + return SkillFrontmatter( + name=cast(str, name), + description=cast(str, description), + license=license_value, + compatibility=compatibility, + allowed_tools=allowed_tools, + metadata=metadata, + ) @staticmethod def _read_and_parse_skill_file( skill_dir_path: str, - ) -> tuple[str, str, str] | None: + ) -> tuple[SkillFrontmatter, str] | None: """Read and parse the SKILL.md file in *skill_dir_path*. Args: skill_dir_path: Absolute path to the directory containing ``SKILL.md``. Returns: - A ``(name, description, content)`` tuple where *content* is the + A ``(frontmatter, content)`` tuple where *content* is the full raw file text, or ``None`` if the file cannot be read or its frontmatter is invalid. """ @@ -2540,23 +2665,21 @@ def _read_and_parse_skill_file( logger.error("Failed to read SKILL.md at '%s'", skill_file) return None - result = FileSkillsSource._extract_frontmatter(content, str(skill_file)) - if result is None: + frontmatter = FileSkillsSource._extract_frontmatter(content, str(skill_file)) + if frontmatter is None: return None - name, description = result - dir_name = Path(skill_dir_path).name - if name != dir_name: + if frontmatter.name != dir_name: logger.error( "SKILL.md at '%s' has frontmatter name '%s' that does not match the directory name '%s'; skipping.", skill_file, - name, + frontmatter.name, dir_name, ) return None - return name, description, content + return frontmatter, content @staticmethod def _discover_skill_directories(skill_paths: Sequence[str]) -> list[str]: @@ -2704,12 +2827,12 @@ async def get_skills(self) -> list[Skill]: result: list[Skill] = [] for skill in skills: - key = skill.name.lower() + key = skill.frontmatter.name.lower() if key in seen: logger.warning( "Duplicate skill name '%s': skill skipped in favor of existing skill '%s'", - skill.name, - seen[key].name, + skill.frontmatter.name, + seen[key].frontmatter.name, ) continue seen[key] = skill @@ -2730,7 +2853,7 @@ class FilteringSkillsSource(DelegatingSkillsSource): filtered = FilteringSkillsSource( inner_source=my_source, - predicate=lambda s: s.name != "internal", + predicate=lambda s: s.frontmatter.name != "internal", ) skills = await filtered.get_skills() """ diff --git a/python/packages/core/tests/core/test_skills.py b/python/packages/core/tests/core/test_skills.py index b268b31551..de39c58b2f 100644 --- a/python/packages/core/tests/core/test_skills.py +++ b/python/packages/core/tests/core/test_skills.py @@ -24,6 +24,7 @@ InMemorySkillsSource, SessionContext, Skill, + SkillFrontmatter, SkillResource, SkillScript, SkillScriptRunner, @@ -69,7 +70,7 @@ def _ctx(provider: SkillsProvider) -> tuple[dict[str, Skill], str | None, list[A ctx = provider._cached_context # pyright: ignore[reportPrivateUsage] assert ctx is not None, "_init_provider() must be called before accessing context" skills, instructions, tools = ctx - return {s.name: s for s in skills}, instructions, tools + return {s.frontmatter.name: s for s in skills}, instructions, tools def _raw_skills(provider: SkillsProvider) -> Sequence[Skill]: @@ -129,10 +130,9 @@ def _read_and_parse_skill_file_for_test(skill_dir: Path) -> FileSkill: """Parse a SKILL.md file from the given directory, raising if invalid.""" result = FileSkillsSource._read_and_parse_skill_file(str(skill_dir)) assert result is not None, f"Failed to parse skill at {skill_dir}" - name, description, content = result + frontmatter, content = result return FileSkill( - name=name, - description=description, + frontmatter=frontmatter, content=content, path=str(skill_dir), ) @@ -163,7 +163,7 @@ async def _discover_file_skills_for_test( result: dict[str, FileSkill] = {} for s in skills: assert isinstance(s, FileSkill), f"Expected FileSkill, got {type(s).__name__}" - result[s.name] = s + result[s.frontmatter.name] = s return result @@ -268,22 +268,21 @@ def test_valid_skill(self) -> None: content = "---\nname: test-skill\ndescription: A test skill.\n---\n# Body\nInstructions here." result = FileSkillsSource._extract_frontmatter(content, "test.md") assert result is not None - name, description = result - assert name == "test-skill" - assert description == "A test skill." + assert result.name == "test-skill" + assert result.description == "A test skill." def test_quoted_values(self) -> None: content = "---\nname: \"test-skill\"\ndescription: 'A test skill.'\n---\nBody." result = FileSkillsSource._extract_frontmatter(content, "test.md") assert result is not None - assert result[0] == "test-skill" - assert result[1] == "A test skill." + assert result.name == "test-skill" + assert result.description == "A test skill." def test_utf8_bom(self) -> None: content = "\ufeff---\nname: test-skill\ndescription: A test skill.\n---\nBody." result = FileSkillsSource._extract_frontmatter(content, "test.md") assert result is not None - assert result[0] == "test-skill" + assert result.name == "test-skill" def test_missing_frontmatter(self) -> None: content = "# Just a markdown file\nNo frontmatter here." @@ -327,11 +326,11 @@ def test_description_too_long(self) -> None: result = FileSkillsSource._extract_frontmatter(content, "test.md") assert result is None - def test_extra_metadata_ignored(self) -> None: + def test_extra_fields_parsed(self) -> None: content = "---\nname: test-skill\ndescription: A test skill.\nauthor: someone\nversion: 1.0\n---\nBody." result = FileSkillsSource._extract_frontmatter(content, "test.md") assert result is not None - assert result[0] == "test-skill" + assert result.name == "test-skill" # --------------------------------------------------------------------------- @@ -346,7 +345,7 @@ async def test_discovers_valid_skill(self, tmp_path: Path) -> None: _write_skill(tmp_path, "my-skill") skills = await _discover_file_skills_for_test([str(tmp_path)]) assert "my-skill" in skills - assert skills["my-skill"].name == "my-skill" + assert skills["my-skill"].frontmatter.name == "my-skill" async def test_discovers_nested_skills(self, tmp_path: Path) -> None: skills_dir = tmp_path / "skills" @@ -504,7 +503,7 @@ def test_returns_none_for_empty_skills(self) -> None: def test_default_prompt_contains_skills(self) -> None: skills = [ - InlineSkill(name="my-skill", description="Does stuff.", instructions="Body"), + InlineSkill(frontmatter=SkillFrontmatter(name="my-skill", description="Does stuff."), instructions="Body"), ] prompt = SkillsProvider._create_instructions(None, skills) assert prompt is not None @@ -514,8 +513,8 @@ def test_default_prompt_contains_skills(self) -> None: def test_skills_sorted_alphabetically(self) -> None: skills = [ - InlineSkill(name="zebra", description="Z skill.", instructions="Body"), - InlineSkill(name="alpha", description="A skill.", instructions="Body"), + InlineSkill(frontmatter=SkillFrontmatter(name="zebra", description="Z skill."), instructions="Body"), + InlineSkill(frontmatter=SkillFrontmatter(name="alpha", description="A skill."), instructions="Body"), ] prompt = SkillsProvider._create_instructions(None, skills) assert prompt is not None @@ -525,7 +524,9 @@ def test_skills_sorted_alphabetically(self) -> None: def test_xml_escapes_metadata(self) -> None: skills = [ - InlineSkill(name="my-skill", description='Uses & "quotes"', instructions="Body"), + InlineSkill( + frontmatter=SkillFrontmatter(name="my-skill", description='Uses & "quotes"'), instructions="Body" + ), ] prompt = SkillsProvider._create_instructions(None, skills) assert prompt is not None @@ -534,7 +535,7 @@ def test_xml_escapes_metadata(self) -> None: def test_custom_prompt_template(self) -> None: skills = [ - InlineSkill(name="my-skill", description="Does stuff.", instructions="Body"), + InlineSkill(frontmatter=SkillFrontmatter(name="my-skill", description="Does stuff."), instructions="Body"), ] custom = "Custom header:\n{skills}\nCustom footer." prompt = SkillsProvider._create_instructions(custom, skills) @@ -544,14 +545,14 @@ def test_custom_prompt_template(self) -> None: def test_invalid_prompt_template_raises(self) -> None: skills = [ - InlineSkill(name="my-skill", description="Does stuff.", instructions="Body"), + InlineSkill(frontmatter=SkillFrontmatter(name="my-skill", description="Does stuff."), instructions="Body"), ] with pytest.raises(ValueError, match="valid format string"): SkillsProvider._create_instructions("{invalid}", skills) def test_positional_placeholder_raises(self) -> None: skills = [ - InlineSkill(name="my-skill", description="Does stuff.", instructions="Body"), + InlineSkill(frontmatter=SkillFrontmatter(name="my-skill", description="Does stuff."), instructions="Body"), ] with pytest.raises(ValueError, match="valid format string"): SkillsProvider._create_instructions("Header {0} footer", skills) @@ -942,25 +943,28 @@ def test_skill_is_abstract(self) -> None: def test_inline_skill_is_skill(self) -> None: """InlineSkill is a subclass of Skill.""" - skill = InlineSkill(name="my-skill", description="A skill.", instructions="Body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="my-skill", description="A skill."), instructions="Body") assert isinstance(skill, Skill) def test_file_skill_is_skill(self) -> None: """FileSkill is a subclass of Skill.""" - skill = FileSkill(name="my-skill", description="A skill.", content="Body", path="/tmp/skill") + skill = FileSkill( + frontmatter=SkillFrontmatter(name="my-skill", description="A skill."), content="Body", path="/tmp/skill" + ) assert isinstance(skill, Skill) def test_basic_construction(self) -> None: - skill = InlineSkill(name="my-skill", description="A test skill.", instructions="Instructions.") - assert skill.name == "my-skill" - assert skill.description == "A test skill." + skill = InlineSkill( + frontmatter=SkillFrontmatter(name="my-skill", description="A test skill."), instructions="Instructions." + ) + assert skill.frontmatter.name == "my-skill" + assert skill.frontmatter.description == "A test skill." assert skill.instructions == "Instructions." assert skill.resources == [] def test_construction_with_static_resources(self) -> None: skill = InlineSkill( - name="my-skill", - description="A test skill.", + frontmatter=SkillFrontmatter(name="my-skill", description="A test skill."), instructions="Instructions.", resources=[ InlineSkillResource(name="ref", content="Reference content"), @@ -971,34 +975,36 @@ def test_construction_with_static_resources(self) -> None: def test_empty_name_raises(self) -> None: with pytest.raises(ValueError, match="cannot be empty"): - InlineSkill(name="", description="A skill.", instructions="Body") + InlineSkill(frontmatter=SkillFrontmatter(name="", description="A skill."), instructions="Body") def test_invalid_name_raises(self) -> None: with pytest.raises(ValueError, match="Invalid skill name"): - InlineSkill(name="Invalid-Name", description="A skill.", instructions="Body") + InlineSkill(frontmatter=SkillFrontmatter(name="Invalid-Name", description="A skill."), instructions="Body") def test_name_starts_with_hyphen_raises(self) -> None: with pytest.raises(ValueError, match="Invalid skill name"): - InlineSkill(name="-bad-name", description="A skill.", instructions="Body") + InlineSkill(frontmatter=SkillFrontmatter(name="-bad-name", description="A skill."), instructions="Body") def test_name_with_consecutive_hyphens_raises(self) -> None: with pytest.raises(ValueError, match="Invalid skill name"): - InlineSkill(name="consecutive--hyphens", description="A skill.", instructions="Body") + InlineSkill( + frontmatter=SkillFrontmatter(name="consecutive--hyphens", description="A skill."), instructions="Body" + ) def test_name_too_long_raises(self) -> None: with pytest.raises(ValueError, match="Invalid skill name"): - InlineSkill(name="a" * 65, description="A skill.", instructions="Body") + InlineSkill(frontmatter=SkillFrontmatter(name="a" * 65, description="A skill."), instructions="Body") def test_empty_description_raises(self) -> None: with pytest.raises(ValueError, match="cannot be empty"): - InlineSkill(name="my-skill", description="", instructions="Body") + InlineSkill(frontmatter=SkillFrontmatter(name="my-skill", description=""), instructions="Body") def test_description_too_long_raises(self) -> None: with pytest.raises(ValueError, match="invalid description"): - InlineSkill(name="my-skill", description="a" * 1025, instructions="Body") + InlineSkill(frontmatter=SkillFrontmatter(name="my-skill", description="a" * 1025), instructions="Body") def test_resource_decorator_bare(self) -> None: - skill = InlineSkill(name="my-skill", description="A skill.", instructions="Body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="my-skill", description="A skill."), instructions="Body") @skill.resource def get_schema() -> Any: @@ -1012,7 +1018,7 @@ def get_schema() -> Any: assert skill.resources[0].function is get_schema def test_resource_decorator_with_args(self) -> None: - skill = InlineSkill(name="my-skill", description="A skill.", instructions="Body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="my-skill", description="A skill."), instructions="Body") @skill.resource(name="custom-name", description="Custom description") def my_resource() -> Any: @@ -1024,7 +1030,7 @@ def my_resource() -> Any: def test_resource_decorator_returns_function(self) -> None: """Decorator should return the original function unchanged.""" - skill = InlineSkill(name="my-skill", description="A skill.", instructions="Body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="my-skill", description="A skill."), instructions="Body") @skill.resource def get_data() -> Any: @@ -1034,7 +1040,7 @@ def get_data() -> Any: assert get_data() == "data" def test_multiple_resources(self) -> None: - skill = InlineSkill(name="my-skill", description="A skill.", instructions="Body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="my-skill", description="A skill."), instructions="Body") @skill.resource def resource_a() -> Any: @@ -1050,7 +1056,7 @@ def resource_b() -> Any: assert "resource_b" in names def test_resource_decorator_async(self) -> None: - skill = InlineSkill(name="my-skill", description="A skill.", instructions="Body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="my-skill", description="A skill."), instructions="Body") @skill.resource async def get_async_data() -> Any: @@ -1070,13 +1076,19 @@ class TestSkillsProviderCodeSkill: """Tests for SkillsProvider with code-defined skills.""" async def test_code_skill_only(self) -> None: - skill = InlineSkill(name="prog-skill", description="A code-defined skill.", instructions="Do the thing.") + skill = InlineSkill( + frontmatter=SkillFrontmatter(name="prog-skill", description="A code-defined skill."), + instructions="Do the thing.", + ) provider = SkillsProvider([skill]) await _init_provider(provider) assert "prog-skill" in _ctx(provider)[0] async def test_load_skill_returns_content(self) -> None: - skill = InlineSkill(name="prog-skill", description="A skill.", instructions="Code-defined instructions.") + skill = InlineSkill( + frontmatter=SkillFrontmatter(name="prog-skill", description="A skill."), + instructions="Code-defined instructions.", + ) provider = SkillsProvider([skill]) await _init_provider(provider) result = provider._load_skill(_raw_skills(provider), "prog-skill") @@ -1087,8 +1099,7 @@ async def test_load_skill_returns_content(self) -> None: async def test_load_skill_appends_resource_listing(self) -> None: skill = InlineSkill( - name="prog-skill", - description="A skill.", + frontmatter=SkillFrontmatter(name="prog-skill", description="A skill."), instructions="Do things.", resources=[ InlineSkillResource(name="ref-a", content="a", description="First resource"), @@ -1106,7 +1117,9 @@ async def test_load_skill_appends_resource_listing(self) -> None: assert '' in result async def test_load_skill_no_resources_no_listing(self) -> None: - skill = InlineSkill(name="prog-skill", description="A skill.", instructions="Body only.") + skill = InlineSkill( + frontmatter=SkillFrontmatter(name="prog-skill", description="A skill."), instructions="Body only." + ) provider = SkillsProvider([skill]) await _init_provider(provider) result = provider._load_skill(_raw_skills(provider), "prog-skill") @@ -1115,8 +1128,7 @@ async def test_load_skill_no_resources_no_listing(self) -> None: async def test_read_static_resource(self) -> None: skill = InlineSkill( - name="prog-skill", - description="A skill.", + frontmatter=SkillFrontmatter(name="prog-skill", description="A skill."), instructions="Body", resources=[InlineSkillResource(name="ref", content="static content")], ) @@ -1126,7 +1138,9 @@ async def test_read_static_resource(self) -> None: assert result == "static content" async def test_read_callable_resource_sync(self) -> None: - skill = InlineSkill(name="prog-skill", description="A skill.", instructions="Body") + skill = InlineSkill( + frontmatter=SkillFrontmatter(name="prog-skill", description="A skill."), instructions="Body" + ) @skill.resource def get_schema() -> Any: @@ -1138,7 +1152,9 @@ def get_schema() -> Any: assert result == "CREATE TABLE users" async def test_read_callable_resource_async(self) -> None: - skill = InlineSkill(name="prog-skill", description="A skill.", instructions="Body") + skill = InlineSkill( + frontmatter=SkillFrontmatter(name="prog-skill", description="A skill."), instructions="Body" + ) @skill.resource async def get_data() -> Any: @@ -1151,8 +1167,7 @@ async def get_data() -> Any: async def test_read_resource_case_insensitive(self) -> None: skill = InlineSkill( - name="prog-skill", - description="A skill.", + frontmatter=SkillFrontmatter(name="prog-skill", description="A skill."), instructions="Body", resources=[InlineSkillResource(name="MyRef", content="content")], ) @@ -1162,14 +1177,18 @@ async def test_read_resource_case_insensitive(self) -> None: assert result == "content" async def test_read_unknown_resource_returns_error(self) -> None: - skill = InlineSkill(name="prog-skill", description="A skill.", instructions="Body") + skill = InlineSkill( + frontmatter=SkillFrontmatter(name="prog-skill", description="A skill."), instructions="Body" + ) provider = SkillsProvider([skill]) await _init_provider(provider) result = await provider._read_skill_resource(_raw_skills(provider), "prog-skill", "nonexistent") assert result.startswith("Error:") async def test_read_callable_resource_sync_with_kwargs(self) -> None: - skill = InlineSkill(name="prog-skill", description="A skill.", instructions="Body") + skill = InlineSkill( + frontmatter=SkillFrontmatter(name="prog-skill", description="A skill."), instructions="Body" + ) @skill.resource def get_user_config(**kwargs: Any) -> Any: @@ -1184,7 +1203,9 @@ def get_user_config(**kwargs: Any) -> Any: assert result == "config for user_123" async def test_read_callable_resource_async_with_kwargs(self) -> None: - skill = InlineSkill(name="prog-skill", description="A skill.", instructions="Body") + skill = InlineSkill( + frontmatter=SkillFrontmatter(name="prog-skill", description="A skill."), instructions="Body" + ) @skill.resource async def get_user_data(**kwargs: Any) -> Any: @@ -1200,7 +1221,9 @@ async def get_user_data(**kwargs: Any) -> Any: async def test_read_callable_resource_without_kwargs_ignores_extra_args(self) -> None: """Resource functions without **kwargs should still work when kwargs are passed.""" - skill = InlineSkill(name="prog-skill", description="A skill.", instructions="Body") + skill = InlineSkill( + frontmatter=SkillFrontmatter(name="prog-skill", description="A skill."), instructions="Body" + ) @skill.resource def static_resource() -> Any: @@ -1215,7 +1238,9 @@ def static_resource() -> Any: async def test_read_callable_resource_returns_dict(self) -> None: """Resource functions may return non-string types, passed through as-is.""" - skill = InlineSkill(name="prog-skill", description="A skill.", instructions="Body") + skill = InlineSkill( + frontmatter=SkillFrontmatter(name="prog-skill", description="A skill."), instructions="Body" + ) @skill.resource def get_config() -> Any: @@ -1228,7 +1253,9 @@ def get_config() -> Any: async def test_read_callable_resource_returns_list(self) -> None: """Resource functions may return lists, passed through as-is.""" - skill = InlineSkill(name="prog-skill", description="A skill.", instructions="Body") + skill = InlineSkill( + frontmatter=SkillFrontmatter(name="prog-skill", description="A skill."), instructions="Body" + ) @skill.resource def get_items() -> Any: @@ -1241,7 +1268,9 @@ def get_items() -> Any: async def test_read_callable_resource_returns_none(self) -> None: """Resource functions may return None.""" - skill = InlineSkill(name="prog-skill", description="A skill.", instructions="Body") + skill = InlineSkill( + frontmatter=SkillFrontmatter(name="prog-skill", description="A skill."), instructions="Body" + ) @skill.resource def get_nothing() -> Any: @@ -1253,7 +1282,9 @@ def get_nothing() -> Any: assert result is None async def test_before_run_injects_code_skills(self) -> None: - skill = InlineSkill(name="prog-skill", description="A code-defined skill.", instructions="Body") + skill = InlineSkill( + frontmatter=SkillFrontmatter(name="prog-skill", description="A code-defined skill."), instructions="Body" + ) provider = SkillsProvider([skill]) context = SessionContext(input_messages=[]) @@ -1274,7 +1305,9 @@ async def test_before_run_empty_provider(self) -> None: async def test_combined_file_and_code_skill(self, tmp_path: Path) -> None: _write_skill(tmp_path, "file-skill") - prog_skill = InlineSkill(name="prog-skill", description="Code-defined.", instructions="Body") + prog_skill = InlineSkill( + frontmatter=SkillFrontmatter(name="prog-skill", description="Code-defined."), instructions="Body" + ) provider = SkillsProvider( DeduplicatingSkillsSource( AggregatingSkillsSource([ @@ -1289,7 +1322,9 @@ async def test_combined_file_and_code_skill(self, tmp_path: Path) -> None: async def test_duplicate_name_file_wins(self, tmp_path: Path) -> None: _write_skill(tmp_path, "my-skill", body="File version") - prog_skill = InlineSkill(name="my-skill", description="Code-defined.", instructions="Prog version") + prog_skill = InlineSkill( + frontmatter=SkillFrontmatter(name="my-skill", description="Code-defined."), instructions="Prog version" + ) provider = SkillsProvider( DeduplicatingSkillsSource( AggregatingSkillsSource([ @@ -1304,7 +1339,9 @@ async def test_duplicate_name_file_wins(self, tmp_path: Path) -> None: async def test_combined_prompt_includes_both(self, tmp_path: Path) -> None: _write_skill(tmp_path, "file-skill") - prog_skill = InlineSkill(name="prog-skill", description="A code-defined skill.", instructions="Body") + prog_skill = InlineSkill( + frontmatter=SkillFrontmatter(name="prog-skill", description="A code-defined skill."), instructions="Body" + ) provider = SkillsProvider( DeduplicatingSkillsSource( AggregatingSkillsSource([ @@ -1361,8 +1398,8 @@ def test_content_contains_full_raw_file(self, tmp_path: Path) -> None: def test_name_and_description_from_frontmatter(self, tmp_path: Path) -> None: _write_skill(tmp_path, "my-skill", description="Skill desc.") skill = _read_and_parse_skill_file_for_test(tmp_path / "my-skill") - assert skill.name == "my-skill" - assert skill.description == "Skill desc." + assert skill.frontmatter.name == "my-skill" + assert skill.frontmatter.description == "Skill desc." def test_path_set(self, tmp_path: Path) -> None: _write_skill(tmp_path, "my-skill") @@ -1397,7 +1434,9 @@ async def test_file_skill_returns_raw_content(self, tmp_path: Path) -> None: async def test_code_skill_wraps_in_xml(self) -> None: """Code-defined skills are wrapped with name, description, and instructions tags.""" - skill = InlineSkill(name="prog-skill", description="A skill.", instructions="Do stuff.") + skill = InlineSkill( + frontmatter=SkillFrontmatter(name="prog-skill", description="A skill."), instructions="Do stuff." + ) provider = SkillsProvider([skill]) await _init_provider(provider) result = provider._load_skill(_raw_skills(provider), "prog-skill") @@ -1408,8 +1447,7 @@ async def test_code_skill_wraps_in_xml(self) -> None: async def test_code_skill_single_resource_no_description(self) -> None: """Resource without description omits the description attribute.""" skill = InlineSkill( - name="prog-skill", - description="A skill.", + frontmatter=SkillFrontmatter(name="prog-skill", description="A skill."), instructions="Body.", resources=[InlineSkillResource(name="data", content="val")], ) @@ -1642,9 +1680,9 @@ def test_valid_file(self, tmp_path: Path) -> None: (skill_dir / "SKILL.md").write_text("---\nname: my-skill\ndescription: A skill.\n---\nBody.", encoding="utf-8") result = FileSkillsSource._read_and_parse_skill_file(str(skill_dir)) assert result is not None - name, desc, content = result - assert name == "my-skill" - assert desc == "A skill." + frontmatter, content = result + assert frontmatter.name == "my-skill" + assert frontmatter.description == "A skill." assert "Body." in content def test_missing_skill_md_returns_none(self, tmp_path: Path) -> None: @@ -1838,14 +1876,282 @@ def test_name_exactly_max_length(self) -> None: content = f"---\nname: {name}\ndescription: A skill.\n---\nBody." result = FileSkillsSource._extract_frontmatter(content, "test.md") assert result is not None - assert result[0] == name + assert result.name == name def test_description_exactly_max_length(self) -> None: desc = "a" * 1024 content = f"---\nname: test-skill\ndescription: {desc}\n---\nBody." result = FileSkillsSource._extract_frontmatter(content, "test.md") assert result is not None - assert result[1] == desc + assert result.description == desc + + +# --------------------------------------------------------------------------- +# Tests: Skill spec fields (via SkillFrontmatter) +# --------------------------------------------------------------------------- + + +class TestSkillSpecFields: + """Tests for agentskills.io spec fields on SkillFrontmatter exposed via Skill.frontmatter.""" + + def test_basic_construction_defaults(self) -> None: + skill = InlineSkill( + frontmatter=SkillFrontmatter(name="my-skill", description="A description."), instructions="Do it." + ) + assert skill.frontmatter.name == "my-skill" + assert skill.frontmatter.description == "A description." + assert skill.frontmatter.license is None + assert skill.frontmatter.compatibility is None + assert skill.frontmatter.allowed_tools is None + assert skill.frontmatter.metadata is None + + def test_all_fields_on_inline_skill(self) -> None: + skill = InlineSkill( + frontmatter=SkillFrontmatter( + name="my-skill", + description="A description.", + license="MIT", + compatibility="Works with GPT-4", + allowed_tools="tool1 tool2", + metadata={"author": "test", "version": "1.0"}, + ), + instructions="Do it.", + ) + assert skill.frontmatter.license == "MIT" + assert skill.frontmatter.compatibility == "Works with GPT-4" + assert skill.frontmatter.allowed_tools == "tool1 tool2" + assert skill.frontmatter.metadata == {"author": "test", "version": "1.0"} + + def test_compatibility_too_long_raises(self) -> None: + with pytest.raises(ValueError): + InlineSkill( + frontmatter=SkillFrontmatter(name="my-skill", description="A description.", compatibility="a" * 501), + instructions="Do it.", + ) + + def test_compatibility_exactly_max_length(self) -> None: + skill = InlineSkill( + frontmatter=SkillFrontmatter(name="my-skill", description="A description.", compatibility="a" * 500), + instructions="Do it.", + ) + assert skill.frontmatter.compatibility == "a" * 500 + + def test_file_skill_spec_fields(self) -> None: + skill = FileSkill( + frontmatter=SkillFrontmatter( + name="my-skill", + description="Test.", + license="MIT", + compatibility="compat info", + allowed_tools="tool1", + metadata={"key": "val"}, + ), + content="---\nname: my-skill\n---", + path="/skills/my-skill", + ) + assert skill.frontmatter.license == "MIT" + assert skill.frontmatter.compatibility == "compat info" + assert skill.frontmatter.allowed_tools == "tool1" + assert skill.frontmatter.metadata == {"key": "val"} + + +# --------------------------------------------------------------------------- +# Tests: SkillFrontmatter class and two-form constructors +# --------------------------------------------------------------------------- + + +class TestSkillFrontmatter: + """Tests for the :class:`SkillFrontmatter` class.""" + + def test_basic_construction(self) -> None: + fm = SkillFrontmatter(name="my-skill", description="A test skill.") + assert fm.name == "my-skill" + assert fm.description == "A test skill." + assert fm.license is None + assert fm.compatibility is None + assert fm.allowed_tools is None + assert fm.metadata is None + + def test_all_fields(self) -> None: + fm = SkillFrontmatter( + name="my-skill", + description="Desc.", + license="MIT", + compatibility="GPT-4", + allowed_tools="tool1", + metadata={"key": "val"}, + ) + assert fm.license == "MIT" + assert fm.compatibility == "GPT-4" + assert fm.allowed_tools == "tool1" + assert fm.metadata == {"key": "val"} + + def test_invalid_name_raises(self) -> None: + with pytest.raises(ValueError): + SkillFrontmatter(name="Bad Name!", description="Desc.") + + def test_invalid_description_raises(self) -> None: + with pytest.raises(ValueError): + SkillFrontmatter(name="my-skill", description="") + + def test_invalid_compatibility_raises(self) -> None: + with pytest.raises(ValueError): + SkillFrontmatter(name="my-skill", description="Desc.", compatibility="a" * 501) + + def test_compatibility_can_be_reassigned(self) -> None: + fm = SkillFrontmatter(name="my-skill", description="Desc.") + fm.compatibility = "a" * 500 + assert fm.compatibility == "a" * 500 + # Plain attribute: post-construction assignment is not re-validated. + fm.compatibility = "a" * 501 + assert fm.compatibility == "a" * 501 + + def test_metadata_is_shallow_copied(self) -> None: + original = {"key": "val"} + fm = SkillFrontmatter(name="my-skill", description="Desc.", metadata=original) + original["key"] = "mutated" + assert fm.metadata == {"key": "val"} + + def test_name_is_mutable(self) -> None: + fm = SkillFrontmatter(name="my-skill", description="Desc.") + fm.name = "other-skill" + assert fm.name == "other-skill" + + def test_description_is_mutable(self) -> None: + fm = SkillFrontmatter(name="my-skill", description="Desc.") + fm.description = "Other description." + assert fm.description == "Other description." + + +class TestExtractFrontmatterSpecFields: + """Tests for _extract_frontmatter parsing all agentskills.io spec fields.""" + + def test_license_parsed(self) -> None: + content = "---\nname: test-skill\ndescription: A skill.\nlicense: MIT\n---\nBody." + result = FileSkillsSource._extract_frontmatter(content, "test.md") + assert result is not None + assert result.license == "MIT" + + def test_compatibility_parsed(self) -> None: + content = "---\nname: test-skill\ndescription: A skill.\ncompatibility: Works with GPT-4\n---\nBody." + result = FileSkillsSource._extract_frontmatter(content, "test.md") + assert result is not None + assert result.compatibility == "Works with GPT-4" + + def test_compatibility_too_long_returns_none(self) -> None: + long_compat = "a" * 501 + content = f"---\nname: test-skill\ndescription: A skill.\ncompatibility: {long_compat}\n---\nBody." + result = FileSkillsSource._extract_frontmatter(content, "test.md") + assert result is None + + def test_allowed_tools_parsed(self) -> None: + content = "---\nname: test-skill\ndescription: A skill.\nallowed-tools: tool1 tool2 tool3\n---\nBody." + result = FileSkillsSource._extract_frontmatter(content, "test.md") + assert result is not None + assert result.allowed_tools == "tool1 tool2 tool3" + + def test_metadata_block_parsed(self) -> None: + content = ( + "---\nname: test-skill\ndescription: A skill.\nmetadata:\n author: someone\n version: 1.0\n---\nBody." + ) + result = FileSkillsSource._extract_frontmatter(content, "test.md") + assert result is not None + assert result.metadata is not None + assert result.metadata["author"] == "someone" + assert result.metadata["version"] == "1.0" + + def test_metadata_with_quoted_values(self) -> None: + content = ( + "---\nname: test-skill\ndescription: A skill.\nmetadata:\n" + " author: 'John Doe'\n org: \"Contoso\"\n---\nBody." + ) + result = FileSkillsSource._extract_frontmatter(content, "test.md") + assert result is not None + assert result.metadata is not None + assert result.metadata["author"] == "John Doe" + assert result.metadata["org"] == "Contoso" + + def test_no_metadata_block(self) -> None: + content = "---\nname: test-skill\ndescription: A skill.\n---\nBody." + result = FileSkillsSource._extract_frontmatter(content, "test.md") + assert result is not None + assert result.metadata is None + + def test_all_spec_fields(self) -> None: + content = ( + "---\n" + "name: test-skill\n" + "description: A comprehensive skill.\n" + "license: Apache-2.0\n" + "compatibility: Works with GPT-4 and Claude\n" + "allowed-tools: read-file write-file\n" + "metadata:\n" + " author: test-author\n" + " version: 2.0\n" + "---\n" + "Body content." + ) + result = FileSkillsSource._extract_frontmatter(content, "test.md") + assert result is not None + assert result.name == "test-skill" + assert result.description == "A comprehensive skill." + assert result.license == "Apache-2.0" + assert result.compatibility == "Works with GPT-4 and Claude" + assert result.allowed_tools == "read-file write-file" + assert result.metadata == {"author": "test-author", "version": "2.0"} + + async def test_file_skill_fields_populated_from_discovery(self, tmp_path: Path) -> None: + """End-to-end: spec fields are populated on FileSkill via discovery.""" + skill_dir = tmp_path / "test-skill" + skill_dir.mkdir() + skill_md = skill_dir / "SKILL.md" + skill_md.write_text( + "---\n" + "name: test-skill\n" + "description: A test skill.\n" + "license: MIT\n" + "compatibility: GPT-4\n" + "allowed-tools: tool1\n" + "metadata:\n" + " key: value\n" + "---\n" + "Instructions.", + encoding="utf-8", + ) + source = FileSkillsSource(str(tmp_path)) + skills = await source.get_skills() + assert len(skills) == 1 + skill = skills[0] + assert isinstance(skill, FileSkill) + assert skill.frontmatter.license == "MIT" + assert skill.frontmatter.compatibility == "GPT-4" + assert skill.frontmatter.allowed_tools == "tool1" + assert skill.frontmatter.metadata == {"key": "value"} + + def test_metadata_children_do_not_override_top_level_fields(self) -> None: + """Indented keys inside a metadata: block must not overwrite top-level fields.""" + content = ( + "---\n" + "name: test-skill\n" + "description: The real description.\n" + "license: MIT\n" + "metadata:\n" + " description: should not override\n" + " license: should not override\n" + " name: should not override\n" + "---\n" + "Body." + ) + result = FileSkillsSource._extract_frontmatter(content, "test.md") + assert result is not None + assert result.name == "test-skill" + assert result.description == "The real description." + assert result.license == "MIT" + assert result.metadata == { + "description": "should not override", + "license": "should not override", + "name": "should not override", + } # --------------------------------------------------------------------------- @@ -1862,7 +2168,7 @@ def test_custom_template_with_empty_skills_returns_none(self) -> None: def test_custom_template_with_literal_braces(self) -> None: skills = [ - InlineSkill(name="my-skill", description="Skill.", instructions="Body"), + InlineSkill(frontmatter=SkillFrontmatter(name="my-skill", description="Skill."), instructions="Body"), ] template = "Header {{literal}} {skills} footer." result = SkillsProvider._create_instructions(template, skills) @@ -1872,9 +2178,9 @@ def test_custom_template_with_literal_braces(self) -> None: def test_multiple_skills_generates_sorted_xml(self) -> None: skills = [ - InlineSkill(name="charlie", description="C.", instructions="Body"), - InlineSkill(name="alpha", description="A.", instructions="Body"), - InlineSkill(name="bravo", description="B.", instructions="Body"), + InlineSkill(frontmatter=SkillFrontmatter(name="charlie", description="C."), instructions="Body"), + InlineSkill(frontmatter=SkillFrontmatter(name="alpha", description="A."), instructions="Body"), + InlineSkill(frontmatter=SkillFrontmatter(name="bravo", description="B."), instructions="Body"), ] result = SkillsProvider._create_instructions(None, skills) assert result is not None @@ -1886,7 +2192,7 @@ def test_multiple_skills_generates_sorted_xml(self) -> None: def test_custom_template_missing_runner_instructions_raises(self) -> None: """Custom template without {runner_instructions} raises when scripts are enabled.""" skills = [ - InlineSkill(name="my-skill", description="Skill.", instructions="Body"), + InlineSkill(frontmatter=SkillFrontmatter(name="my-skill", description="Skill."), instructions="Body"), ] template = "Skills: {skills}" with pytest.raises(ValueError, match="runner_instructions"): @@ -1895,7 +2201,7 @@ def test_custom_template_missing_runner_instructions_raises(self) -> None: def test_custom_template_missing_resource_instructions_raises(self) -> None: """Custom template without {resource_instructions} raises when resources exist.""" skills = [ - InlineSkill(name="my-skill", description="Skill.", instructions="Body"), + InlineSkill(frontmatter=SkillFrontmatter(name="my-skill", description="Skill."), instructions="Body"), ] template = "Skills: {skills}" with pytest.raises(ValueError, match="resource_instructions"): @@ -1904,7 +2210,7 @@ def test_custom_template_missing_resource_instructions_raises(self) -> None: def test_include_resource_instructions_true_adds_resource_text(self) -> None: """When include_resource_instructions is True, resource instructions appear in the prompt.""" skills = [ - InlineSkill(name="my-skill", description="Skill.", instructions="Body"), + InlineSkill(frontmatter=SkillFrontmatter(name="my-skill", description="Skill."), instructions="Body"), ] result = SkillsProvider._create_instructions(None, skills, include_resource_instructions=True) assert result is not None @@ -1913,7 +2219,7 @@ def test_include_resource_instructions_true_adds_resource_text(self) -> None: def test_include_resource_instructions_false_omits_resource_text(self) -> None: """When include_resource_instructions is False, resource instructions do not appear.""" skills = [ - InlineSkill(name="my-skill", description="Skill.", instructions="Body"), + InlineSkill(frontmatter=SkillFrontmatter(name="my-skill", description="Skill."), instructions="Body"), ] result = SkillsProvider._create_instructions(None, skills, include_resource_instructions=False) assert result is not None @@ -1922,7 +2228,7 @@ def test_include_resource_instructions_false_omits_resource_text(self) -> None: def test_custom_template_with_unknown_placeholder_raises(self) -> None: """Template with an unknown placeholder raises ValueError.""" skills = [ - InlineSkill(name="my-skill", description="Skill.", instructions="Body"), + InlineSkill(frontmatter=SkillFrontmatter(name="my-skill", description="Skill."), instructions="Body"), ] template = "Skills: {skills} {unknown_key}" with pytest.raises(ValueError, match="valid format string"): @@ -1952,7 +2258,7 @@ async def test_load_skill_whitespace_name_returns_error(self, tmp_path: Path) -> assert "empty" in result async def test_read_skill_resource_whitespace_skill_name_returns_error(self) -> None: - skill = InlineSkill(name="my-skill", description="A skill.", instructions="Body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="my-skill", description="A skill."), instructions="Body") provider = SkillsProvider([skill]) await _init_provider(provider) result = await provider._read_skill_resource(_raw_skills(provider), " ", "ref") @@ -1960,7 +2266,7 @@ async def test_read_skill_resource_whitespace_skill_name_returns_error(self) -> assert "empty" in result async def test_read_skill_resource_whitespace_resource_name_returns_error(self) -> None: - skill = InlineSkill(name="my-skill", description="A skill.", instructions="Body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="my-skill", description="A skill."), instructions="Body") provider = SkillsProvider([skill]) await _init_provider(provider) result = await provider._read_skill_resource(_raw_skills(provider), "my-skill", " ") @@ -1968,7 +2274,7 @@ async def test_read_skill_resource_whitespace_resource_name_returns_error(self) assert "empty" in result async def test_read_callable_resource_exception_returns_error(self) -> None: - skill = InlineSkill(name="my-skill", description="A skill.", instructions="Body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="my-skill", description="A skill."), instructions="Body") @skill.resource def exploding_resource() -> Any: @@ -1981,7 +2287,7 @@ def exploding_resource() -> Any: assert "Failed to read resource" in result async def test_read_async_callable_resource_exception_returns_error(self) -> None: - skill = InlineSkill(name="my-skill", description="A skill.", instructions="Body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="my-skill", description="A skill."), instructions="Body") @skill.resource async def async_exploding() -> Any: @@ -1993,7 +2299,9 @@ async def async_exploding() -> Any: assert result.startswith("Error:") async def test_load_code_skill_xml_escapes_metadata(self) -> None: - skill = InlineSkill(name="my-skill", description='Uses & "quotes"', instructions="Body") + skill = InlineSkill( + frontmatter=SkillFrontmatter(name="my-skill", description='Uses & "quotes"'), instructions="Body" + ) provider = SkillsProvider([skill]) await _init_provider(provider) result = provider._load_skill(_raw_skills(provider), "my-skill") @@ -2001,16 +2309,18 @@ async def test_load_code_skill_xml_escapes_metadata(self) -> None: assert "&" in result async def test_code_skill_deduplication(self) -> None: - skill1 = InlineSkill(name="my-skill", description="First.", instructions="Body 1") - skill2 = InlineSkill(name="my-skill", description="Second.", instructions="Body 2") + skill1 = InlineSkill(frontmatter=SkillFrontmatter(name="my-skill", description="First."), instructions="Body 1") + skill2 = InlineSkill( + frontmatter=SkillFrontmatter(name="my-skill", description="Second."), instructions="Body 2" + ) provider = SkillsProvider([skill1, skill2]) await _init_provider(provider) assert len(_ctx(provider)[0]) == 1 - assert "First." in _ctx(provider)[0]["my-skill"].description + assert "First." in _ctx(provider)[0]["my-skill"].frontmatter.description async def test_before_run_extends_tools_even_without_instructions(self) -> None: """If instructions are somehow None but skills exist, tools should still be added.""" - skill = InlineSkill(name="my-skill", description="A skill.", instructions="Body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="my-skill", description="A skill."), instructions="Body") provider = SkillsProvider([skill]) context = SessionContext(input_messages=[]) @@ -2122,7 +2432,7 @@ class TestSkillResourceDecoratorEdgeCases: """Additional edge-case tests for the @skill.resource decorator.""" def test_decorator_no_docstring_description_is_none(self) -> None: - skill = InlineSkill(name="my-skill", description="A skill.", instructions="Body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="my-skill", description="A skill."), instructions="Body") @skill.resource def no_docs() -> Any: @@ -2131,7 +2441,7 @@ def no_docs() -> Any: assert skill.resources[0].description is None def test_decorator_with_name_only(self) -> None: - skill = InlineSkill(name="my-skill", description="A skill.", instructions="Body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="my-skill", description="A skill."), instructions="Body") @skill.resource(name="custom-name") def get_data() -> Any: @@ -2143,7 +2453,7 @@ def get_data() -> Any: assert skill.resources[0].description is None def test_decorator_with_description_only(self) -> None: - skill = InlineSkill(name="my-skill", description="A skill.", instructions="Body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="my-skill", description="A skill."), instructions="Body") @skill.resource(description="Custom desc") def get_data() -> Any: @@ -2153,7 +2463,7 @@ def get_data() -> Any: assert skill.resources[0].description == "Custom desc" def test_decorator_preserves_original_function_identity(self) -> None: - skill = InlineSkill(name="my-skill", description="A skill.", instructions="Body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="my-skill", description="A skill."), instructions="Body") @skill.resource def original() -> Any: @@ -2230,7 +2540,7 @@ def greet(name: str = "world") -> str: return f"hello {name}" script = InlineSkillScript(name="greet", function=greet) - skill = InlineSkill(name="s", description="d", instructions="c") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="s", description="d"), instructions="c") result = await script.run(skill, args={"name": "Alice"}) assert result == "hello Alice" @@ -2239,7 +2549,7 @@ async def greet(name: str = "world") -> str: return f"async {name}" script = InlineSkillScript(name="greet", function=greet) - skill = InlineSkill(name="s", description="d", instructions="c") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="s", description="d"), instructions="c") result = await script.run(skill, args={"name": "Bob"}) assert result == "async Bob" @@ -2248,13 +2558,13 @@ def func(x: int = 0, **kwargs: Any) -> dict[str, Any]: return {"x": x, **kwargs} script = InlineSkillScript(name="f", function=func) - skill = InlineSkill(name="s", description="d", instructions="c") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="s", description="d"), instructions="c") result = await script.run(skill, args={"x": 1}, extra="val") assert result == {"x": 1, "extra": "val"} async def test_run_code_defined_no_args(self) -> None: script = InlineSkillScript(name="f", function=lambda: 42) - skill = InlineSkill(name="s", description="d", instructions="c") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="s", description="d"), instructions="c") result = await script.run(skill) assert result == 42 @@ -2262,13 +2572,15 @@ async def test_run_file_based_with_runner(self) -> None: captured: dict[str, Any] = {} def runner(skill: Skill, script: SkillScript, args: dict[str, Any] | None = None) -> str: - captured["skill"] = skill.name + captured["skill"] = skill.frontmatter.name captured["script"] = script.name captured["args"] = args return "runner_result" script = FileSkillScript(name="run.py", full_path=f"{_ABS}/test/run.py", runner=runner) - skill = FileSkill(name="my-skill", description="d", content="c", path=f"{_ABS}/test") + skill = FileSkill( + frontmatter=SkillFrontmatter(name="my-skill", description="d"), content="c", path=f"{_ABS}/test" + ) result = await script.run(skill, args={"key": "val"}) assert result == "runner_result" assert captured["skill"] == "my-skill" @@ -2280,19 +2592,19 @@ async def runner(skill: Skill, script: SkillScript, args: dict[str, Any] | None return "async_runner" script = FileSkillScript(name="run.py", full_path=f"{_ABS}/test/run.py", runner=runner) - skill = FileSkill(name="s", description="d", content="c", path=f"{_ABS}/test") + skill = FileSkill(frontmatter=SkillFrontmatter(name="s", description="d"), content="c", path=f"{_ABS}/test") result = await script.run(skill, args=None) assert result == "async_runner" async def test_run_file_based_without_runner_raises(self) -> None: script = FileSkillScript(name="run.py", full_path=f"{_ABS}/test/run.py") - skill = FileSkill(name="s", description="d", content="c", path=f"{_ABS}/test") + skill = FileSkill(frontmatter=SkillFrontmatter(name="s", description="d"), content="c", path=f"{_ABS}/test") with pytest.raises(ValueError, match="requires a runner"): await script.run(skill) async def test_run_file_based_with_non_file_skill_raises_type_error(self) -> None: script = FileSkillScript(name="run.py", full_path=f"{_ABS}/test/run.py", runner=_noop_script_runner) - skill = InlineSkill(name="s", description="d", instructions="c") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="s", description="d"), instructions="c") with pytest.raises(TypeError, match="requires a FileSkill"): await script.run(skill) @@ -2314,7 +2626,7 @@ class TestSkillScriptDecorator: """Tests for the @skill.script decorator.""" def test_bare_decorator(self) -> None: - skill = InlineSkill(name="my-skill", description="test", instructions="body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="my-skill", description="test"), instructions="body") @skill.script def analyze(query: str) -> str: @@ -2328,7 +2640,7 @@ def analyze(query: str) -> str: assert skill.scripts[0].function is analyze def test_parameterized_decorator(self) -> None: - skill = InlineSkill(name="my-skill", description="test", instructions="body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="my-skill", description="test"), instructions="body") @skill.script(name="custom-name", description="Custom desc") def my_func() -> str: @@ -2341,7 +2653,7 @@ def my_func() -> str: assert skill.scripts[0].function is my_func def test_multiple_scripts(self) -> None: - skill = InlineSkill(name="my-skill", description="test", instructions="body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="my-skill", description="test"), instructions="body") @skill.script def script_a() -> str: @@ -2356,7 +2668,7 @@ def script_b() -> str: assert skill.scripts[1].name == "script_b" def test_async_script(self) -> None: - skill = InlineSkill(name="my-skill", description="test", instructions="body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="my-skill", description="test"), instructions="body") @skill.script async def fetch_data() -> str: @@ -2369,7 +2681,7 @@ async def fetch_data() -> str: assert skill.scripts[0].function is fetch_data def test_decorator_returns_original_function(self) -> None: - skill = InlineSkill(name="my-skill", description="test", instructions="body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="my-skill", description="test"), instructions="body") @skill.script def original() -> str: @@ -2392,12 +2704,14 @@ class TestSkillWithScripts: """Tests for the Skill class with scripts attribute.""" def test_default_empty_scripts(self) -> None: - skill = InlineSkill(name="my-skill", description="test", instructions="body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="my-skill", description="test"), instructions="body") assert skill.scripts == [] def test_scripts_at_construction(self) -> None: scripts = [InlineSkillScript(name="s1", function=lambda: None)] - skill = InlineSkill(name="my-skill", description="test", instructions="body", scripts=scripts) + skill = InlineSkill( + frontmatter=SkillFrontmatter(name="my-skill", description="test"), instructions="body", scripts=scripts + ) assert len(skill.scripts) == 1 assert skill.scripts[0].name == "s1" @@ -2414,12 +2728,12 @@ async def test_async_callable_satisfies_protocol(self) -> None: results: list[tuple] = [] async def my_runner(skill, script, args=None): - results.append((skill.name, script.name, args)) + results.append((skill.frontmatter.name, script.name, args)) return "executed" assert isinstance(my_runner, SkillScriptRunner) - skill = InlineSkill(name="test-skill", description="test", instructions="body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="test-skill", description="test"), instructions="body") script = FileSkillScript(name="my-script", full_path=f"{_ABS}/test/scripts/run.py") skill.scripts.append(script) @@ -2437,7 +2751,7 @@ async def __call__(self, skill, script, args=None): runner = _CustomRunner() assert isinstance(runner, SkillScriptRunner) - skill = InlineSkill(name="test-skill", description="test", instructions="body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="test-skill", description="test"), instructions="body") script = InlineSkillScript(name="my-script", function=lambda: None) skill.scripts.append(script) @@ -2448,7 +2762,7 @@ async def test_runner_returns_none(self) -> None: async def noop_runner(skill, script, args=None): return None - skill = InlineSkill(name="test-skill", description="test", instructions="body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="test-skill", description="test"), instructions="body") script = InlineSkillScript(name="s1", function=lambda: None) result = await noop_runner(skill, script) @@ -2458,7 +2772,7 @@ async def test_runner_returns_object(self) -> None: async def dict_runner(skill, script, args=None): return {"exit_code": 0, "output": "ok"} - skill = InlineSkill(name="test-skill", description="test", instructions="body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="test-skill", description="test"), instructions="body") script = FileSkillScript(name="s1", full_path=f"{_ABS}/test/scripts/run.py") result = await dict_runner(skill, script) @@ -2468,12 +2782,12 @@ def test_sync_callable_satisfies_protocol(self) -> None: results: list[tuple] = [] def my_runner(skill, script, args=None): - results.append((skill.name, script.name, args)) + results.append((skill.frontmatter.name, script.name, args)) return "executed" assert isinstance(my_runner, SkillScriptRunner) - skill = InlineSkill(name="test-skill", description="test", instructions="body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="test-skill", description="test"), instructions="body") script = FileSkillScript(name="my-script", full_path=f"{_ABS}/test/scripts/run.py") skill.scripts.append(script) @@ -2491,7 +2805,7 @@ def __call__(self, skill, script, args=None): runner = _SyncRunner() assert isinstance(runner, SkillScriptRunner) - skill = InlineSkill(name="test-skill", description="test", instructions="body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="test-skill", description="test"), instructions="body") script = InlineSkillScript(name="my-script", function=lambda: None) skill.scripts.append(script) @@ -2502,7 +2816,7 @@ def test_sync_runner_returns_none(self) -> None: def noop_runner(skill, script, args=None): return None - skill = InlineSkill(name="test-skill", description="test", instructions="body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="test-skill", description="test"), instructions="body") script = InlineSkillScript(name="s1", function=lambda: None) result = noop_runner(skill, script) @@ -2512,7 +2826,7 @@ def test_sync_runner_returns_object(self) -> None: def dict_runner(skill, script, args=None): return {"exit_code": 0, "output": "ok"} - skill = InlineSkill(name="test-skill", description="test", instructions="body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="test-skill", description="test"), instructions="body") script = FileSkillScript(name="s1", full_path=f"{_ABS}/test/scripts/run.py") result = dict_runner(skill, script) @@ -2528,7 +2842,7 @@ class TestSkillsProviderFactories: """Tests for the SkillsProvider constructor auto-wiring behavior.""" async def test_code_skills_with_scripts_creates_provider(self) -> None: - skill = InlineSkill(name="my-skill", description="test", instructions="body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="my-skill", description="test"), instructions="body") skill.scripts.append(InlineSkillScript(name="s1", function=lambda: None)) provider = SkillsProvider([skill]) @@ -2538,7 +2852,7 @@ async def test_code_skills_with_scripts_creates_provider(self) -> None: assert any(hasattr(t, "name") and t.name == "run_skill_script" for t in _ctx(provider)[2]) async def test_code_skills_no_scripts(self) -> None: - skill = InlineSkill(name="my-skill", description="test", instructions="body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="my-skill", description="test"), instructions="body") provider = SkillsProvider([skill]) await _init_provider(provider) # No scripts with functions, no runner, no resources — only load_skill @@ -2549,7 +2863,7 @@ async def test_code_script_runs_directly(self) -> None: def my_function(key: str = "") -> str: return f"executed: {key}" - skill = InlineSkill(name="my-skill", description="test", instructions="body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="my-skill", description="test"), instructions="body") skill.scripts.append(InlineSkillScript(name="s1", function=my_function)) provider = SkillsProvider([skill]) @@ -2560,7 +2874,7 @@ def my_function(key: str = "") -> str: assert result == "executed: hello" async def test_no_scripts_no_tool(self) -> None: - skill = InlineSkill(name="my-skill", description="test", instructions="body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="my-skill", description="test"), instructions="body") # No scripts at all — no run_skill_script tool provider = SkillsProvider([skill]) await _init_provider(provider) @@ -2568,14 +2882,14 @@ async def test_no_scripts_no_tool(self) -> None: async def test_no_resources_no_read_skill_resource_tool(self) -> None: """When no skill has resources, read_skill_resource tool is not advertised.""" - skill = InlineSkill(name="my-skill", description="test", instructions="body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="my-skill", description="test"), instructions="body") provider = SkillsProvider([skill]) await _init_provider(provider) assert not any(hasattr(t, "name") and t.name == "read_skill_resource" for t in _ctx(provider)[2]) async def test_resources_present_includes_read_skill_resource_tool(self) -> None: """When a skill has resources, read_skill_resource tool is advertised.""" - skill = InlineSkill(name="my-skill", description="test", instructions="body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="my-skill", description="test"), instructions="body") skill.resources.append(InlineSkillResource(name="ref", content="reference data")) provider = SkillsProvider([skill]) await _init_provider(provider) @@ -2583,7 +2897,7 @@ async def test_resources_present_includes_read_skill_resource_tool(self) -> None async def test_resources_present_includes_resource_instructions(self) -> None: """When a skill has resources, instructions mention read_skill_resource.""" - skill = InlineSkill(name="my-skill", description="test", instructions="body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="my-skill", description="test"), instructions="body") skill.resources.append(InlineSkillResource(name="ref", content="reference data")) provider = SkillsProvider([skill]) await _init_provider(provider) @@ -2591,14 +2905,14 @@ async def test_resources_present_includes_resource_instructions(self) -> None: async def test_no_resources_excludes_resource_instructions(self) -> None: """When no skill has resources, instructions do not mention read_skill_resource.""" - skill = InlineSkill(name="my-skill", description="test", instructions="body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="my-skill", description="test"), instructions="body") provider = SkillsProvider([skill]) await _init_provider(provider) assert "read_skill_resource" not in (_ctx(provider)[1] or "") async def test_read_skill_resource_tool_returns_content(self) -> None: """The read_skill_resource tool returns resource content when invoked.""" - skill = InlineSkill(name="my-skill", description="test", instructions="body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="my-skill", description="test"), instructions="body") skill.resources.append(InlineSkillResource(name="ref", content="reference data")) provider = SkillsProvider([skill]) await _init_provider(provider) @@ -2695,7 +3009,9 @@ async def test_combined_skills(self, tmp_path: Path) -> None: encoding="utf-8", ) - code_skill = InlineSkill(name="code-skill", description="test", instructions="body") + code_skill = InlineSkill( + frontmatter=SkillFrontmatter(name="code-skill", description="test"), instructions="body" + ) code_skill.scripts.append(InlineSkillScript(name="s1", function=lambda: None)) provider = SkillsProvider( @@ -2725,7 +3041,7 @@ async def test_file_scripts_without_runner_no_error_at_init(self, tmp_path: Path async def test_file_script_error_without_runner(self) -> None: # A skill with both a code script and a file-based script - skill = InlineSkill(name="my-skill", description="test", instructions="body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="my-skill", description="test"), instructions="body") skill.scripts.append(InlineSkillScript(name="code-s", function=lambda: "ok")) skill.scripts.append(FileSkillScript(name="file-s", full_path=f"{_ABS}/test/scripts/s1.py")) @@ -2746,7 +3062,7 @@ async def test_async_code_script_runs_directly(self) -> None: async def async_func(x: int = 0) -> str: return f"async: {x}" - skill = InlineSkill(name="my-skill", description="test", instructions="body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="my-skill", description="test"), instructions="body") skill.scripts.append(InlineSkillScript(name="s1", function=async_func)) provider = SkillsProvider([skill]) @@ -2761,7 +3077,7 @@ async def test_code_script_returns_object(self) -> None: def returns_dict() -> dict: return {"status": "ok", "value": 42} - skill = InlineSkill(name="my-skill", description="test", instructions="body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="my-skill", description="test"), instructions="body") skill.scripts.append(InlineSkillScript(name="s1", function=returns_dict)) provider = SkillsProvider([skill]) @@ -2772,7 +3088,7 @@ def returns_dict() -> dict: async def test_code_script_returns_none(self) -> None: """Code-defined scripts returning None pass through as None.""" - skill = InlineSkill(name="my-skill", description="test", instructions="body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="my-skill", description="test"), instructions="body") skill.scripts.append(InlineSkillScript(name="s1", function=lambda: None)) provider = SkillsProvider([skill]) @@ -2783,7 +3099,7 @@ async def test_code_script_returns_none(self) -> None: async def test_script_with_path_errors_without_runner(self) -> None: """A file-based script without a runner should return an error.""" - skill = InlineSkill(name="my-skill", description="test", instructions="body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="my-skill", description="test"), instructions="body") skill.scripts.append(InlineSkillScript(name="code-s", function=lambda: "ok")) skill.scripts.append(FileSkillScript(name="path-s", full_path=f"{_ABS}/test/scripts/s1.py")) @@ -2801,7 +3117,7 @@ async def test_script_with_path_errors_without_runner(self) -> None: assert "script_runner" in result or "Failed to run" in result async def test_run_skill_script_error_on_missing_skill(self) -> None: - skill = InlineSkill(name="my-skill", description="test", instructions="body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="my-skill", description="test"), instructions="body") skill.scripts.append(InlineSkillScript(name="s1", function=lambda: None)) provider = SkillsProvider([skill]) @@ -2812,7 +3128,7 @@ async def test_run_skill_script_error_on_missing_skill(self) -> None: assert "nonexistent" in result async def test_run_skill_script_sync_with_kwargs(self) -> None: - skill = InlineSkill(name="my-skill", description="test", instructions="body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="my-skill", description="test"), instructions="body") @skill.script def greet(name: str, **kwargs: Any) -> str: @@ -2827,7 +3143,7 @@ def greet(name: str, **kwargs: Any) -> str: assert result == "Hello Alice (user=u42)" async def test_run_skill_script_async_with_kwargs(self) -> None: - skill = InlineSkill(name="my-skill", description="test", instructions="body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="my-skill", description="test"), instructions="body") @skill.script async def fetch(url: str, **kwargs: Any) -> str: @@ -2843,7 +3159,7 @@ async def fetch(url: str, **kwargs: Any) -> str: async def test_run_skill_script_without_kwargs_ignores_extra_args(self) -> None: """Script functions without **kwargs should still work when runtime kwargs are passed.""" - skill = InlineSkill(name="my-skill", description="test", instructions="body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="my-skill", description="test"), instructions="body") @skill.script def simple(query: str) -> str: @@ -2858,7 +3174,7 @@ def simple(query: str) -> str: async def test_run_skill_script_conflicting_args_and_kwargs_raises(self) -> None: """Conflicting keys in args and kwargs should raise TypeError.""" - skill = InlineSkill(name="my-skill", description="test", instructions="body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="my-skill", description="test"), instructions="body") @skill.script def process(**kwargs: Any) -> str: @@ -2872,7 +3188,7 @@ def process(**kwargs: Any) -> str: assert "Error" in result async def test_run_skill_script_error_on_missing_script(self) -> None: - skill = InlineSkill(name="my-skill", description="test", instructions="body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="my-skill", description="test"), instructions="body") skill.scripts.append(InlineSkillScript(name="s1", function=lambda: None)) provider = SkillsProvider([skill]) @@ -2883,7 +3199,7 @@ async def test_run_skill_script_error_on_missing_script(self) -> None: assert "nonexistent" in result async def test_run_skill_script_error_on_empty_names(self) -> None: - skill = InlineSkill(name="my-skill", description="test", instructions="body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="my-skill", description="test"), instructions="body") skill.scripts.append(InlineSkillScript(name="s1", function=lambda: None)) provider = SkillsProvider([skill]) @@ -2897,7 +3213,7 @@ async def test_run_skill_script_error_on_empty_names(self) -> None: assert "Error" in result async def test_instructions_include_script_runner_hints(self) -> None: - skill = InlineSkill(name="my-skill", description="test", instructions="body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="my-skill", description="test"), instructions="body") skill.scripts.append(InlineSkillScript(name="s1", function=lambda: None)) provider = SkillsProvider([skill]) @@ -2906,14 +3222,14 @@ async def test_instructions_include_script_runner_hints(self) -> None: assert "not as top-level tool parameters" in _ctx(provider)[1] async def test_no_scripts_no_runner_no_script_instructions(self) -> None: - skill = InlineSkill(name="my-skill", description="test", instructions="body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="my-skill", description="test"), instructions="body") provider = SkillsProvider([skill]) await _init_provider(provider) # No scripts and no runner — instructions should not mention run_skill_script assert "run_skill_script" not in (_ctx(provider)[1] or "") async def test_tool_schema_args_description_mentions_key_format(self) -> None: - skill = InlineSkill(name="my-skill", description="test", instructions="body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="my-skill", description="test"), instructions="body") skill.scripts.append(InlineSkillScript(name="s1", function=lambda: None)) provider = SkillsProvider([skill]) @@ -2925,7 +3241,7 @@ async def test_tool_schema_args_description_mentions_key_format(self) -> None: async def test_require_script_approval_sets_approval_mode(self) -> None: """When require_script_approval=True, the run_skill_script tool has approval_mode='always_require'.""" - skill = InlineSkill(name="my-skill", description="test", instructions="body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="my-skill", description="test"), instructions="body") skill.scripts.append(InlineSkillScript(name="s1", function=lambda: None)) provider = SkillsProvider([skill], require_script_approval=True) @@ -2935,7 +3251,7 @@ async def test_require_script_approval_sets_approval_mode(self) -> None: async def test_require_script_approval_false_by_default(self) -> None: """By default, the run_skill_script tool has approval_mode='never_require'.""" - skill = InlineSkill(name="my-skill", description="test", instructions="body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="my-skill", description="test"), instructions="body") skill.scripts.append(InlineSkillScript(name="s1", function=lambda: None)) provider = SkillsProvider([skill]) @@ -2945,7 +3261,7 @@ async def test_require_script_approval_false_by_default(self) -> None: async def test_require_script_approval_does_not_affect_other_tools(self) -> None: """The load_skill tool should never require approval.""" - skill = InlineSkill(name="my-skill", description="test", instructions="body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="my-skill", description="test"), instructions="body") skill.scripts.append(InlineSkillScript(name="s1", function=lambda: None)) provider = SkillsProvider([skill], require_script_approval=True) @@ -2961,7 +3277,7 @@ async def test_code_script_exception_returns_error(self) -> None: def failing_script() -> str: raise RuntimeError("Something went wrong") - skill = InlineSkill(name="my-skill", description="test", instructions="body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="my-skill", description="test"), instructions="body") skill.scripts.append(InlineSkillScript(name="boom", function=failing_script)) provider = SkillsProvider([skill]) @@ -2974,7 +3290,7 @@ def failing_script() -> str: async def test_custom_template_without_runner_placeholder_raises(self) -> None: """Provider with code scripts and custom template missing {runner_instructions} raises.""" - skill = InlineSkill(name="my-skill", description="test", instructions="body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="my-skill", description="test"), instructions="body") skill.scripts.append(InlineSkillScript(name="s1", function=lambda: None)) provider = SkillsProvider( @@ -3138,7 +3454,7 @@ class TestCreateInstructionsWithScripts: """Tests for script metadata in skill advertisement.""" def test_excludes_script_count(self) -> None: - skill = InlineSkill(name="my-skill", description="test", instructions="body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="my-skill", description="test"), instructions="body") skill.scripts.append(InlineSkillScript(name="s1", function=lambda: None)) result = SkillsProvider._create_instructions(None, [skill]) @@ -3146,7 +3462,7 @@ def test_excludes_script_count(self) -> None: assert "" not in result def test_no_scripts_element_when_empty(self) -> None: - skill = InlineSkill(name="my-skill", description="test", instructions="body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="my-skill", description="test"), instructions="body") result = SkillsProvider._create_instructions(None, [skill]) assert result is not None @@ -3162,7 +3478,7 @@ class TestLoadSkillWithScripts: """Tests for script metadata in load_skill output.""" async def test_code_skill_includes_scripts_element(self) -> None: - skill = InlineSkill(name="my-skill", description="test", instructions="body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="my-skill", description="test"), instructions="body") skill.scripts.append(InlineSkillScript(name="analyze", description="Run analysis", function=lambda: None)) provider = SkillsProvider([skill]) @@ -3174,7 +3490,7 @@ async def test_code_skill_includes_scripts_element(self) -> None: assert 'description="Run analysis"' in result async def test_code_skill_no_scripts_element(self) -> None: - skill = InlineSkill(name="my-skill", description="test", instructions="body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="my-skill", description="test"), instructions="body") provider = SkillsProvider([skill]) await _init_provider(provider) result = provider._load_skill(_raw_skills(provider), "my-skill") @@ -3190,7 +3506,7 @@ class _MinimalClassSkill(ClassSkill): """A minimal class-based skill with no resources or scripts.""" def __init__(self) -> None: - super().__init__(name="minimal-skill", description="A minimal skill.") + super().__init__(frontmatter=SkillFrontmatter(name="minimal-skill", description="A minimal skill.")) @property def instructions(self) -> str: @@ -3201,7 +3517,7 @@ class _FullClassSkill(ClassSkill): """A class-based skill with resources and scripts.""" def __init__(self) -> None: - super().__init__(name="full-skill", description="A full skill.") + super().__init__(frontmatter=SkillFrontmatter(name="full-skill", description="A full skill.")) self._resources: list[SkillResource] | None = None self._scripts: list[SkillScript] | None = None @@ -3318,7 +3634,7 @@ async def test_provider_with_class_skill(self) -> None: skills = _raw_skills(provider) assert len(skills) == 1 - assert skills[0].name == "full-skill" + assert skills[0].frontmatter.name == "full-skill" async def test_provider_loads_class_skill_content(self) -> None: skill = _FullClassSkill() @@ -3335,16 +3651,18 @@ async def test_in_memory_source_with_class_skill(self) -> None: source = InMemorySkillsSource([skill]) skills = await source.get_skills() assert len(skills) == 1 - assert skills[0].name == "minimal-skill" + assert skills[0].frontmatter.name == "minimal-skill" async def test_mixed_inline_and_class_skills(self) -> None: - inline = InlineSkill(name="inline-skill", description="Inline", instructions="inline body") + inline = InlineSkill( + frontmatter=SkillFrontmatter(name="inline-skill", description="Inline"), instructions="inline body" + ) class_skill = _MinimalClassSkill() provider = SkillsProvider([inline, class_skill]) await _init_provider(provider) skills = _raw_skills(provider) - names = {s.name for s in skills} + names = {s.frontmatter.name for s in skills} assert names == {"inline-skill", "minimal-skill"} async def test_class_skill_script_runs(self) -> None: @@ -3372,7 +3690,9 @@ class _DecoratorClassSkill(ClassSkill): """A class-based skill using @ClassSkill.resource and @ClassSkill.script decorators.""" def __init__(self) -> None: - super().__init__(name="decorator-skill", description="A decorator-discovered skill.") + super().__init__( + frontmatter=SkillFrontmatter(name="decorator-skill", description="A decorator-discovered skill.") + ) @property def instructions(self) -> str: @@ -3395,7 +3715,7 @@ class _BareDecoratorSkill(ClassSkill): """Skill using bare decorators (no arguments) — name/description from method.""" def __init__(self) -> None: - super().__init__(name="bare-skill", description="Bare decorator skill.") + super().__init__(frontmatter=SkillFrontmatter(name="bare-skill", description="Bare decorator skill.")) @property def instructions(self) -> str: @@ -3416,7 +3736,7 @@ class _DuplicateResourceSkill(ClassSkill): """Skill with duplicate resource names — should raise.""" def __init__(self) -> None: - super().__init__(name="dup-skill", description="Dup.") + super().__init__(frontmatter=SkillFrontmatter(name="dup-skill", description="Dup.")) @property def instructions(self) -> str: @@ -3435,7 +3755,7 @@ class _DuplicateScriptSkill(ClassSkill): """Skill with duplicate script names — should raise.""" def __init__(self) -> None: - super().__init__(name="dup-script-skill", description="Dup.") + super().__init__(frontmatter=SkillFrontmatter(name="dup-script-skill", description="Dup.")) @property def instructions(self) -> str: @@ -3454,7 +3774,7 @@ class _SelfAccessSkill(ClassSkill): """Skill where resource/script access instance state via self.""" def __init__(self, multiplier: int = 10) -> None: - super().__init__(name="self-access", description="Self access skill.") + super().__init__(frontmatter=SkillFrontmatter(name="self-access", description="Self access skill.")) self.multiplier = multiplier @property @@ -3581,7 +3901,7 @@ async def test_provider_with_decorator_skill(self) -> None: skills = _raw_skills(provider) assert len(skills) == 1 - assert skills[0].name == "decorator-skill" + assert skills[0].frontmatter.name == "decorator-skill" def test_manual_override_wins(self) -> None: """A subclass that overrides resources/scripts bypasses decorator discovery.""" @@ -3688,7 +4008,7 @@ def test_wrong_decorator_order_resource_raises(self) -> None: class _BadOrder(ClassSkill): def __init__(self) -> None: - super().__init__(name="bad", description="bad") + super().__init__(frontmatter=SkillFrontmatter(name="bad", description="bad")) @property def instructions(self) -> str: @@ -3705,7 +4025,7 @@ def test_wrong_decorator_order_script_raises(self) -> None: class _BadOrder(ClassSkill): def __init__(self) -> None: - super().__init__(name="bad", description="bad") + super().__init__(frontmatter=SkillFrontmatter(name="bad", description="bad")) @property def instructions(self) -> str: @@ -3722,7 +4042,7 @@ def test_invalid_explicit_resource_name_raises(self) -> None: class _BadName(ClassSkill): def __init__(self) -> None: - super().__init__(name="bad", description="bad") + super().__init__(frontmatter=SkillFrontmatter(name="bad", description="bad")) @property def instructions(self) -> str: @@ -3738,7 +4058,7 @@ def test_invalid_explicit_script_name_raises(self) -> None: class _BadName(ClassSkill): def __init__(self) -> None: - super().__init__(name="bad", description="bad") + super().__init__(frontmatter=SkillFrontmatter(name="bad", description="bad")) @property def instructions(self) -> str: @@ -3754,7 +4074,7 @@ def test_empty_explicit_name_raises(self) -> None: class _EmptyName(ClassSkill): def __init__(self) -> None: - super().__init__(name="bad", description="bad") + super().__init__(frontmatter=SkillFrontmatter(name="bad", description="bad")) @property def instructions(self) -> str: @@ -3798,7 +4118,7 @@ class _ExplicitDescriptionSkill(ClassSkill): """Skill with explicit descriptions on decorator.""" def __init__(self) -> None: - super().__init__(name="desc-skill", description="Explicit desc.") + super().__init__(frontmatter=SkillFrontmatter(name="desc-skill", description="Explicit desc.")) @property def instructions(self) -> str: @@ -3817,7 +4137,7 @@ class _PropertyCallCountSkill(ClassSkill): """Tracks how many times the property getter is called.""" def __init__(self) -> None: - super().__init__(name="callcount-skill", description="Tracks calls.") + super().__init__(frontmatter=SkillFrontmatter(name="callcount-skill", description="Tracks calls.")) self.getter_call_count = 0 @property @@ -3847,7 +4167,7 @@ class _ChildSkill(_ParentSkill): """Child inheriting parent resources and adding its own.""" def __init__(self) -> None: - super().__init__(name="child-skill", description="Child.") + super().__init__(frontmatter=SkillFrontmatter(name="child-skill", description="Child.")) @property def instructions(self) -> str: @@ -3862,7 +4182,7 @@ class _KwargsSkill(ClassSkill): """Skill that uses **kwargs from runtime.""" def __init__(self) -> None: - super().__init__(name="kwargs-skill", description="Kwargs.") + super().__init__(frontmatter=SkillFrontmatter(name="kwargs-skill", description="Kwargs.")) @property def instructions(self) -> str: @@ -3886,7 +4206,7 @@ class _ChildWithInheritedPropertySkill(_ParentWithPropertyResource): """Child that should discover inherited property resource.""" def __init__(self) -> None: - super().__init__(name="child-prop-skill", description="Child prop.") + super().__init__(frontmatter=SkillFrontmatter(name="child-prop-skill", description="Child prop.")) @property def instructions(self) -> str: @@ -3897,7 +4217,7 @@ class _PropertyResourceSkill(ClassSkill): """Skill with a property-based resource.""" def __init__(self) -> None: - super().__init__(name="prop-skill", description="Property skill.") + super().__init__(frontmatter=SkillFrontmatter(name="prop-skill", description="Property skill.")) @property def instructions(self) -> str: @@ -3914,7 +4234,7 @@ class _MixedPropertyMethodSkill(ClassSkill): """Skill with both property and method resources.""" def __init__(self) -> None: - super().__init__(name="mixed-prop", description="Mixed.") + super().__init__(frontmatter=SkillFrontmatter(name="mixed-prop", description="Mixed.")) @property def instructions(self) -> str: @@ -3937,7 +4257,7 @@ async def test_code_skill_scripts_element_contains_parameters(self) -> None: def analyze(query: str, limit: int = 10) -> str: return "result" - skill = InlineSkill(name="my-skill", description="test", instructions="body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="my-skill", description="test"), instructions="body") skill.scripts.append(InlineSkillScript(name="analyze", description="Run analysis", function=analyze)) provider = SkillsProvider([skill]) @@ -3954,7 +4274,7 @@ class TestReadSkillResourceWithScripts: """Tests for _read_skill_resource falling back to scripts.""" async def test_reads_script_with_static_content(self) -> None: - skill = InlineSkill(name="my-skill", description="test", instructions="body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="my-skill", description="test"), instructions="body") skill.scripts.append(InlineSkillScript(name="generate.py", function=lambda: "print('hello')")) provider = SkillsProvider([skill]) @@ -3964,7 +4284,7 @@ async def test_reads_script_with_static_content(self) -> None: assert "not found" in result async def test_script_not_accessible_via_read_resource(self) -> None: - skill = InlineSkill(name="my-skill", description="test", instructions="body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="my-skill", description="test"), instructions="body") skill.scripts.append(InlineSkillScript(name="run.py", function=lambda: "script output")) provider = SkillsProvider([skill]) @@ -3977,7 +4297,7 @@ async def test_async_script_not_accessible_via_read_resource(self) -> None: async def async_script() -> str: return "async output" - skill = InlineSkill(name="my-skill", description="test", instructions="body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="my-skill", description="test"), instructions="body") skill.scripts.append(InlineSkillScript(name="run.py", function=async_script)) provider = SkillsProvider([skill]) @@ -3986,7 +4306,7 @@ async def async_script() -> str: assert "not found" in result async def test_script_case_insensitive_not_in_resources(self) -> None: - skill = InlineSkill(name="my-skill", description="test", instructions="body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="my-skill", description="test"), instructions="body") skill.scripts.append(InlineSkillScript(name="Generate.py", function=lambda: "code")) provider = SkillsProvider([skill]) @@ -3995,7 +4315,7 @@ async def test_script_case_insensitive_not_in_resources(self) -> None: assert "not found" in result async def test_resource_takes_priority_over_script(self) -> None: - skill = InlineSkill(name="my-skill", description="test", instructions="body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="my-skill", description="test"), instructions="body") skill.resources.append(InlineSkillResource(name="data.py", content="resource content")) skill.scripts.append(InlineSkillScript(name="data.py", function=lambda: "script content")) @@ -4008,7 +4328,7 @@ async def test_script_function_error_not_exposed_via_resources(self) -> None: def failing_script() -> str: raise RuntimeError("boom") - skill = InlineSkill(name="my-skill", description="test", instructions="body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="my-skill", description="test"), instructions="body") skill.scripts.append(InlineSkillScript(name="bad.py", function=failing_script)) provider = SkillsProvider([skill]) @@ -4217,7 +4537,7 @@ class TestLoadSkillsMerging: def test_code_skill_with_invalid_name_raises(self) -> None: """Code skills with invalid metadata (e.g. uppercase name) raise at construction.""" with pytest.raises(ValueError, match="Invalid skill name"): - InlineSkill(name="INVALID_NAME", description="valid", instructions="body") + InlineSkill(frontmatter=SkillFrontmatter(name="INVALID_NAME", description="valid"), instructions="body") async def test_file_skill_takes_precedence_over_code_skill(self, tmp_path: Path) -> None: """When file-based and code-defined skills share a name, file-based wins.""" @@ -4235,7 +4555,9 @@ async def test_file_skill_takes_precedence_over_code_skill(self, tmp_path: Path) encoding="utf-8", ) - code_skill = InlineSkill(name="my-skill", description="Code skill.", instructions="Code body.") + code_skill = InlineSkill( + frontmatter=SkillFrontmatter(name="my-skill", description="Code skill."), instructions="Code body." + ) source = DeduplicatingSkillsSource( AggregatingSkillsSource([ @@ -4244,7 +4566,7 @@ async def test_file_skill_takes_precedence_over_code_skill(self, tmp_path: Path) ]) ) result = await source.get_skills() - skills_by_name = {s.name: s for s in result} + skills_by_name = {s.frontmatter.name: s for s in result} assert "my-skill" in skills_by_name assert skills_by_name["my-skill"].path is not None # file-based skill has path set @@ -4269,7 +4591,7 @@ async def test_file_skills_source_discovers_skills(self, tmp_path: Path) -> None source = FileSkillsSource(str(tmp_path)) skills = await source.get_skills() assert len(skills) == 1 - assert skills[0].name == "my-skill" + assert skills[0].frontmatter.name == "my-skill" assert skills[0].path is not None async def test_file_skills_source_with_extensions(self, tmp_path: Path) -> None: @@ -4295,67 +4617,67 @@ async def test_in_memory_skills_source_returns_all_skills(self) -> None: """InMemorySkillsSource returns all provided skills.""" from agent_framework import InMemorySkillsSource - s1 = InlineSkill(name="skill-a", description="A", instructions="body") - s2 = InlineSkill(name="skill-b", description="B", instructions="body") + s1 = InlineSkill(frontmatter=SkillFrontmatter(name="skill-a", description="A"), instructions="body") + s2 = InlineSkill(frontmatter=SkillFrontmatter(name="skill-b", description="B"), instructions="body") source = InMemorySkillsSource([s1, s2]) skills = await source.get_skills() assert len(skills) == 2 - assert skills[0].name == "skill-a" - assert skills[1].name == "skill-b" + assert skills[0].frontmatter.name == "skill-a" + assert skills[1].frontmatter.name == "skill-b" async def test_aggregating_source_combines_sources(self) -> None: """Aggregating source concatenates results from multiple sources.""" from agent_framework import AggregatingSkillsSource, InMemorySkillsSource - s1 = InlineSkill(name="skill-a", description="A", instructions="body") - s2 = InlineSkill(name="skill-b", description="B", instructions="body") + s1 = InlineSkill(frontmatter=SkillFrontmatter(name="skill-a", description="A"), instructions="body") + s2 = InlineSkill(frontmatter=SkillFrontmatter(name="skill-b", description="B"), instructions="body") source = AggregatingSkillsSource([ InMemorySkillsSource([s1]), InMemorySkillsSource([s2]), ]) skills = await source.get_skills() - names = [s.name for s in skills] + names = [s.frontmatter.name for s in skills] assert names == ["skill-a", "skill-b"] async def test_filtering_source_filters_by_predicate(self) -> None: """FilteringSkillsSource only returns skills matching the predicate.""" from agent_framework import FilteringSkillsSource, InMemorySkillsSource - s1 = InlineSkill(name="keep-me", description="keep", instructions="body") - s2 = InlineSkill(name="drop-me", description="drop", instructions="body") + s1 = InlineSkill(frontmatter=SkillFrontmatter(name="keep-me", description="keep"), instructions="body") + s2 = InlineSkill(frontmatter=SkillFrontmatter(name="drop-me", description="drop"), instructions="body") source = FilteringSkillsSource( InMemorySkillsSource([s1, s2]), - predicate=lambda s: s.name.startswith("keep"), + predicate=lambda s: s.frontmatter.name.startswith("keep"), ) skills = await source.get_skills() assert len(skills) == 1 - assert skills[0].name == "keep-me" + assert skills[0].frontmatter.name == "keep-me" async def test_deduplicating_source_removes_duplicates(self) -> None: """DeduplicatingSkillsSource keeps first skill with each name.""" from agent_framework import DeduplicatingSkillsSource, InMemorySkillsSource - s1 = InlineSkill(name="my-skill", description="first", instructions="body1") - s2 = InlineSkill(name="my-skill", description="second", instructions="body2") - s3 = InlineSkill(name="other", description="other", instructions="body3") + s1 = InlineSkill(frontmatter=SkillFrontmatter(name="my-skill", description="first"), instructions="body1") + s2 = InlineSkill(frontmatter=SkillFrontmatter(name="my-skill", description="second"), instructions="body2") + s3 = InlineSkill(frontmatter=SkillFrontmatter(name="other", description="other"), instructions="body3") source = DeduplicatingSkillsSource(InMemorySkillsSource([s1, s2, s3])) skills = await source.get_skills() assert len(skills) == 2 - names = {s.name for s in skills} + names = {s.frontmatter.name for s in skills} assert names == {"my-skill", "other"} # First one wins - my_skill = next(s for s in skills if s.name == "my-skill") - assert my_skill.description == "first" + my_skill = next(s for s in skills if s.frontmatter.name == "my-skill") + assert my_skill.frontmatter.description == "first" async def test_delegating_source_delegates(self) -> None: """DelegatingSkillsSource delegates to inner source by default.""" from agent_framework import DelegatingSkillsSource, InMemorySkillsSource - skill = InlineSkill(name="test-skill", description="test", instructions="body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="test-skill", description="test"), instructions="body") inner = InMemorySkillsSource([skill]) class PassthroughSource(DelegatingSkillsSource): @@ -4365,7 +4687,7 @@ class PassthroughSource(DelegatingSkillsSource): assert source.inner_source is inner skills = await source.get_skills() assert len(skills) == 1 - assert skills[0].name == "test-skill" + assert skills[0].frontmatter.name == "test-skill" async def test_provider_with_source_parameter(self, tmp_path: Path) -> None: """SkillsProvider works with the new source= parameter.""" @@ -4385,7 +4707,9 @@ async def test_provider_source_overrides_legacy_params(self, tmp_path: Path) -> """When source= is provided, skill_paths and skills are ignored.""" from agent_framework import InMemorySkillsSource - code_skill = InlineSkill(name="code-skill", description="test", instructions="body") + code_skill = InlineSkill( + frontmatter=SkillFrontmatter(name="code-skill", description="test"), instructions="body" + ) source = InMemorySkillsSource([code_skill]) # Pass skill_paths that would normally discover file skills — should be ignored @@ -4411,8 +4735,12 @@ async def test_composed_source_pipeline(self, tmp_path: Path) -> None: encoding="utf-8", ) - code_skill = InlineSkill(name="code-skill", description="Code.", instructions="Body.") - internal = InlineSkill(name="internal", description="Internal.", instructions="Body.") + code_skill = InlineSkill( + frontmatter=SkillFrontmatter(name="code-skill", description="Code."), instructions="Body." + ) + internal = InlineSkill( + frontmatter=SkillFrontmatter(name="internal", description="Internal."), instructions="Body." + ) source = FilteringSkillsSource( DeduplicatingSkillsSource( @@ -4421,11 +4749,11 @@ async def test_composed_source_pipeline(self, tmp_path: Path) -> None: InMemorySkillsSource([code_skill, internal]), ]) ), - predicate=lambda s: s.name != "internal", + predicate=lambda s: s.frontmatter.name != "internal", ) skills = await source.get_skills() - names = {s.name for s in skills} + names = {s.frontmatter.name for s in skills} assert names == {"file-skill", "code-skill"} assert "internal" not in names @@ -4453,15 +4781,15 @@ async def test_file_skills_source_with_provider(self, tmp_path: Path) -> None: async def test_code_skills_with_provider(self) -> None: """InMemorySkillsSource with code skills creates a working provider.""" - skill = InlineSkill(name="code-skill", description="test", instructions="body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="code-skill", description="test"), instructions="body") provider = SkillsProvider(DeduplicatingSkillsSource(InMemorySkillsSource([skill]))) await _init_provider(provider) assert "code-skill" in _ctx(provider)[0] async def test_multiple_code_skills(self) -> None: """InMemorySkillsSource with multiple skills registers them all.""" - s1 = InlineSkill(name="skill-a", description="A", instructions="body") - s2 = InlineSkill(name="skill-b", description="B", instructions="body") + s1 = InlineSkill(frontmatter=SkillFrontmatter(name="skill-a", description="A"), instructions="body") + s2 = InlineSkill(frontmatter=SkillFrontmatter(name="skill-b", description="B"), instructions="body") provider = SkillsProvider(DeduplicatingSkillsSource(InMemorySkillsSource([s1, s2]))) await _init_provider(provider) assert "skill-a" in _ctx(provider)[0] @@ -4469,7 +4797,7 @@ async def test_multiple_code_skills(self) -> None: async def test_custom_source_with_provider(self) -> None: """Custom source passed to SkillsProvider works.""" - skill = InlineSkill(name="custom", description="test", instructions="body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="custom", description="test"), instructions="body") source = InMemorySkillsSource([skill]) provider = SkillsProvider(DeduplicatingSkillsSource(source)) await _init_provider(provider) @@ -4479,13 +4807,13 @@ async def test_filtering_source_excludes_skills(self) -> None: """FilteringSkillsSource excludes matching skills.""" from agent_framework import FilteringSkillsSource - s1 = InlineSkill(name="keep-me", description="keep", instructions="body") - s2 = InlineSkill(name="drop-me", description="drop", instructions="body") + s1 = InlineSkill(frontmatter=SkillFrontmatter(name="keep-me", description="keep"), instructions="body") + s2 = InlineSkill(frontmatter=SkillFrontmatter(name="drop-me", description="drop"), instructions="body") source = DeduplicatingSkillsSource( FilteringSkillsSource( InMemorySkillsSource([s1, s2]), - predicate=lambda s: s.name.startswith("keep"), + predicate=lambda s: s.frontmatter.name.startswith("keep"), ) ) provider = SkillsProvider(source) @@ -4495,8 +4823,8 @@ async def test_filtering_source_excludes_skills(self) -> None: async def test_dedup_across_sources(self) -> None: """DeduplicatingSkillsSource deduplicates across aggregated sources.""" - s1 = InlineSkill(name="dup", description="first", instructions="body1") - s2 = InlineSkill(name="dup", description="second", instructions="body2") + s1 = InlineSkill(frontmatter=SkillFrontmatter(name="dup", description="first"), instructions="body1") + s2 = InlineSkill(frontmatter=SkillFrontmatter(name="dup", description="second"), instructions="body2") source = DeduplicatingSkillsSource( AggregatingSkillsSource([ @@ -4507,7 +4835,7 @@ async def test_dedup_across_sources(self) -> None: provider = SkillsProvider(source) await _init_provider(provider) assert len(_ctx(provider)[0]) == 1 - assert _ctx(provider)[0]["dup"].description == "first" + assert _ctx(provider)[0]["dup"].frontmatter.description == "first" async def test_file_source_with_script_runner(self, tmp_path: Path) -> None: """FileSkillsSource with script_runner enables script execution.""" @@ -4527,7 +4855,7 @@ async def test_file_source_with_script_runner(self, tmp_path: Path) -> None: async def test_script_approval_on_provider(self) -> None: """SkillsProvider with require_script_approval sets the approval mode.""" - skill = InlineSkill(name="my-skill", description="test", instructions="body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="my-skill", description="test"), instructions="body") skill.scripts.append(InlineSkillScript(name="s1", function=lambda: None)) provider = SkillsProvider( @@ -4616,13 +4944,13 @@ async def test_from_paths_with_resource_extensions(self, tmp_path: Path) -> None def test_init_with_skills_creates_provider(self) -> None: """Constructor with skill list returns a SkillsProvider instance.""" - skill = InlineSkill(name="test-skill", description="Test", instructions="Body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="test-skill", description="Test"), instructions="Body") provider = SkillsProvider([skill]) assert isinstance(provider, SkillsProvider) async def test_init_with_skills_registers_skills(self) -> None: """Constructor with skill list registers code-defined skills.""" - skill = InlineSkill(name="test-skill", description="Test", instructions="Body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="test-skill", description="Test"), instructions="Body") provider = SkillsProvider([skill]) await _init_provider(provider) assert "test-skill" in _ctx(provider)[0] @@ -4635,7 +4963,7 @@ async def test_init_with_empty_list(self) -> None: async def test_init_with_skills_and_options(self) -> None: """Constructor with skills passes through keyword options.""" - skill = InlineSkill(name="my-skill", description="Test", instructions="Body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="my-skill", description="Test"), instructions="Body") provider = SkillsProvider( [skill], require_script_approval=True, @@ -4648,7 +4976,7 @@ def test_init_with_source_creates_provider(self) -> None: """Constructor with SkillsSource returns a SkillsProvider instance.""" from agent_framework import InMemorySkillsSource - skill = InlineSkill(name="test-skill", description="Test", instructions="Body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="test-skill", description="Test"), instructions="Body") source = InMemorySkillsSource([skill]) provider = SkillsProvider(source) assert isinstance(provider, SkillsProvider) @@ -4657,7 +4985,7 @@ async def test_init_with_source_uses_provided_source(self) -> None: """Constructor with SkillsSource uses the exact source given.""" from agent_framework import InMemorySkillsSource - skill = InlineSkill(name="test-skill", description="Test", instructions="Body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="test-skill", description="Test"), instructions="Body") source = InMemorySkillsSource([skill]) provider = SkillsProvider(source) await _init_provider(provider) @@ -4674,7 +5002,7 @@ class TestDisableCaching: async def test_default_caching_enabled(self) -> None: """By default, _get_or_create_context only builds once.""" - skill = InlineSkill(name="test-skill", description="Test", instructions="Body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="test-skill", description="Test"), instructions="Body") provider = SkillsProvider([skill]) await _init_provider(provider) first_ctx = provider._cached_context # pyright: ignore[reportPrivateUsage] @@ -4686,7 +5014,7 @@ async def test_default_caching_enabled(self) -> None: async def test_disable_caching_rebuilds_on_every_call(self) -> None: """With disable_caching=True, _create_context rebuilds every time.""" - skill = InlineSkill(name="test-skill", description="Test", instructions="Body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="test-skill", description="Test"), instructions="Body") provider = SkillsProvider([skill], disable_caching=True) await _init_provider(provider) first_ctx = provider._cached_context # pyright: ignore[reportPrivateUsage] @@ -4700,20 +5028,20 @@ async def test_disable_caching_via_constructor(self) -> None: """disable_caching works via the primary constructor.""" from agent_framework import InMemorySkillsSource - skill = InlineSkill(name="test-skill", description="Test", instructions="Body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="test-skill", description="Test"), instructions="Body") source = InMemorySkillsSource([skill]) provider = SkillsProvider(source, disable_caching=True) assert provider._disable_caching is True async def test_caching_enabled_by_default(self) -> None: """SkillsProvider defaults to caching enabled.""" - skill = InlineSkill(name="test-skill", description="Test", instructions="Body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="test-skill", description="Test"), instructions="Body") provider = SkillsProvider([skill]) assert provider._disable_caching is False async def test_disable_caching_before_run_rebuilds(self) -> None: """before_run with disable_caching=True calls _create_context each time.""" - skill = InlineSkill(name="test-skill", description="Test", instructions="Body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="test-skill", description="Test"), instructions="Body") provider = SkillsProvider([skill], disable_caching=True) context = SessionContext(input_messages=[]) await provider.before_run(agent=AsyncMock(), session=AsyncMock(), context=context, state={}) @@ -4730,7 +5058,7 @@ class TestSkillsProviderConstructorEdgeCases: async def test_single_skill_accepted(self) -> None: """A single Skill (not a list) is accepted and wrapped.""" - skill = InlineSkill(name="test-skill", description="Test", instructions="Body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="test-skill", description="Test"), instructions="Body") provider = SkillsProvider(skill) await _init_provider(provider) skills = _ctx(provider)[0] @@ -4739,7 +5067,7 @@ async def test_single_skill_accepted(self) -> None: async def test_template_missing_skills_placeholder_raises(self) -> None: """Instruction template without {skills} raises ValueError.""" - skill = InlineSkill(name="test-skill", description="Test", instructions="Body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="test-skill", description="Test"), instructions="Body") provider = SkillsProvider([skill], instruction_template="No placeholder here.") with pytest.raises(ValueError, match="skills"): await _init_provider(provider) @@ -4765,7 +5093,7 @@ class TestInlineSkillContentCaching: def test_content_cached_after_first_access(self) -> None: """InlineSkill.content returns the same object on subsequent accesses.""" - skill = InlineSkill(name="test-skill", description="Test", instructions="Body") + skill = InlineSkill(frontmatter=SkillFrontmatter(name="test-skill", description="Test"), instructions="Body") first = skill.content second = skill.content assert first is second # Same object (cached) diff --git a/python/samples/02-agents/skills/code_defined_skill/code_defined_skill.py b/python/samples/02-agents/skills/code_defined_skill/code_defined_skill.py index 15388dd695..42fd0a38de 100644 --- a/python/samples/02-agents/skills/code_defined_skill/code_defined_skill.py +++ b/python/samples/02-agents/skills/code_defined_skill/code_defined_skill.py @@ -11,7 +11,7 @@ from textwrap import dedent from typing import Any -from agent_framework import Agent, InlineSkill, InlineSkillResource, SkillsProvider +from agent_framework import Agent, InlineSkill, InlineSkillResource, SkillFrontmatter, SkillsProvider from agent_framework.foundry import FoundryChatClient from azure.identity import AzureCliCredential from dotenv import load_dotenv @@ -47,8 +47,9 @@ # 1. Static Resources — inline content passed at construction time # --------------------------------------------------------------------------- unit_converter_skill = InlineSkill( - name="unit-converter", - description="Convert between common units using a conversion factor", + frontmatter=SkillFrontmatter( + name="unit-converter", description="Convert between common units using a conversion factor" + ), instructions=dedent("""\ Use this skill when the user asks to convert between units. diff --git a/python/samples/02-agents/skills/file_based_skill/skills/unit-converter/SKILL.md b/python/samples/02-agents/skills/file_based_skill/skills/unit-converter/SKILL.md index b6e6bef1a3..7660365328 100644 --- a/python/samples/02-agents/skills/file_based_skill/skills/unit-converter/SKILL.md +++ b/python/samples/02-agents/skills/file_based_skill/skills/unit-converter/SKILL.md @@ -1,6 +1,12 @@ --- name: unit-converter description: Convert between common units using a multiplication factor. Use when asked to convert miles, kilometers, pounds, or kilograms. +license: MIT +compatibility: Works with any model that supports tool use. +allowed-tools: convert +metadata: + author: agent-framework-samples + version: "1.0" --- ## Usage diff --git a/python/samples/02-agents/skills/mixed_skills/mixed_skills.py b/python/samples/02-agents/skills/mixed_skills/mixed_skills.py index 2b10fc0c2a..2f89074cbd 100644 --- a/python/samples/02-agents/skills/mixed_skills/mixed_skills.py +++ b/python/samples/02-agents/skills/mixed_skills/mixed_skills.py @@ -21,6 +21,7 @@ FileSkillsSource, InlineSkill, InMemorySkillsSource, + SkillFrontmatter, SkillsProvider, ) from agent_framework.foundry import FoundryChatClient @@ -73,8 +74,9 @@ # --------------------------------------------------------------------------- volume_converter_skill = InlineSkill( - name="volume-converter", - description="Convert between gallons and liters using a conversion factor", + frontmatter=SkillFrontmatter( + name="volume-converter", description="Convert between gallons and liters using a conversion factor" + ), instructions=dedent("""\ Use this skill when the user asks to convert between gallons and liters. @@ -118,6 +120,7 @@ def convert_volume(value: float, factor: float) -> str: # 2. Define a class-based skill for temperature conversion # --------------------------------------------------------------------------- + class TemperatureConverterSkill(ClassSkill): """A temperature-converter skill defined as a Python class. @@ -127,8 +130,10 @@ class TemperatureConverterSkill(ClassSkill): def __init__(self) -> None: super().__init__( - name="temperature-converter", - description="Convert between temperature scales (Fahrenheit, Celsius, Kelvin).", + frontmatter=SkillFrontmatter( + name="temperature-converter", + description="Convert between temperature scales (Fahrenheit, Celsius, Kelvin).", + ) ) @property @@ -178,6 +183,7 @@ def convert_temperature(self, value: float, factor: float, offset: float = 0) -> # 3. Wire everything together and run the agent # --------------------------------------------------------------------------- + async def main() -> None: """Run the combined skills demo.""" endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"] diff --git a/python/samples/02-agents/skills/mixed_skills/skills/unit-converter/SKILL.md b/python/samples/02-agents/skills/mixed_skills/skills/unit-converter/SKILL.md index b6e6bef1a3..7660365328 100644 --- a/python/samples/02-agents/skills/mixed_skills/skills/unit-converter/SKILL.md +++ b/python/samples/02-agents/skills/mixed_skills/skills/unit-converter/SKILL.md @@ -1,6 +1,12 @@ --- name: unit-converter description: Convert between common units using a multiplication factor. Use when asked to convert miles, kilometers, pounds, or kilograms. +license: MIT +compatibility: Works with any model that supports tool use. +allowed-tools: convert +metadata: + author: agent-framework-samples + version: "1.0" --- ## Usage diff --git a/python/samples/02-agents/skills/script_approval/script_approval.py b/python/samples/02-agents/skills/script_approval/script_approval.py index bd956dec61..8687bf6867 100644 --- a/python/samples/02-agents/skills/script_approval/script_approval.py +++ b/python/samples/02-agents/skills/script_approval/script_approval.py @@ -9,7 +9,7 @@ # warnings.filterwarnings("ignore", message=r"\[SKILLS\].*", category=FutureWarning) from textwrap import dedent -from agent_framework import Agent, InlineSkill, SkillsProvider +from agent_framework import Agent, InlineSkill, SkillFrontmatter, SkillsProvider from agent_framework.foundry import FoundryChatClient from azure.identity import AzureCliCredential from dotenv import load_dotenv @@ -43,8 +43,9 @@ # Define a code skill with a script that performs a sensitive operation deployment_skill = InlineSkill( - name="deployment", - description="Tools for deploying application versions to production", + frontmatter=SkillFrontmatter( + name="deployment", description="Tools for deploying application versions to production" + ), instructions=dedent("""\ Use this skill when the user asks to deploy an application. diff --git a/python/samples/02-agents/skills/skill_filtering/skill_filtering.py b/python/samples/02-agents/skills/skill_filtering/skill_filtering.py index 73dffb4c71..55eea099d6 100644 --- a/python/samples/02-agents/skills/skill_filtering/skill_filtering.py +++ b/python/samples/02-agents/skills/skill_filtering/skill_filtering.py @@ -75,7 +75,7 @@ async def main() -> None: FilteringSkillsSource( FileSkillsSource(str(skills_dir), script_runner=subprocess_script_runner), # Only keep the volume-converter skill - predicate=lambda s: s.name != "length-converter", + predicate=lambda s: s.frontmatter.name != "length-converter", ) ) diff --git a/python/samples/02-agents/skills/skill_filtering/skills/length-converter/SKILL.md b/python/samples/02-agents/skills/skill_filtering/skills/length-converter/SKILL.md index cbf506f683..c73c26ab7b 100644 --- a/python/samples/02-agents/skills/skill_filtering/skills/length-converter/SKILL.md +++ b/python/samples/02-agents/skills/skill_filtering/skills/length-converter/SKILL.md @@ -1,6 +1,12 @@ --- name: length-converter description: Convert between common length units (miles, km, feet, meters) using a multiplication factor. +license: MIT +compatibility: Works with any model that supports tool use. +allowed-tools: convert +metadata: + author: agent-framework-samples + version: "1.0" --- ## Usage diff --git a/python/samples/02-agents/skills/skill_filtering/skills/volume-converter/SKILL.md b/python/samples/02-agents/skills/skill_filtering/skills/volume-converter/SKILL.md index 6e10cb46b1..0c729f3e22 100644 --- a/python/samples/02-agents/skills/skill_filtering/skills/volume-converter/SKILL.md +++ b/python/samples/02-agents/skills/skill_filtering/skills/volume-converter/SKILL.md @@ -1,6 +1,12 @@ --- name: volume-converter description: Convert between gallons and liters using a conversion factor. +license: MIT +compatibility: Works with any model that supports tool use. +allowed-tools: convert +metadata: + author: agent-framework-samples + version: "1.0" --- ## Usage