Python: Add SkillFrontmatter class#5730
Conversation
github-actions
Bot
changed the title
| def description(self) -> str: | ||
| """Human-readable description, delegated from :attr:`frontmatter`.""" | ||
| return self.frontmatter.description | ||
|
|
There was a problem hiding this comment.
I exposed these properties for compatibility, not sure if they are needed though.
| YAML_KV_RE = re.compile( | ||
| r"^\s*(\w+)\s*:\s*(?:[\"'](.+?)[\"']|(.+?))\s*$", | ||
| re.MULTILINE, | ||
| ) |
There was a problem hiding this comment.
I'm using yaml, this is not needed.
There was a problem hiding this comment.
Naive question, I realzied that pyyaml is not a core dependency, however, I've seen pyyaml in other subpackages, should we parse the yaml manually here or add pyyaml as dependencies in core?
There was a problem hiding this comment.
Pull request overview
This PR implements an experimental SkillFrontmatter model for Python skills, aligning the Python Skill metadata surface area with the agentskills.io spec (and the existing .NET implementation). It updates skill discovery/parsing to return validated frontmatter instead of a (name, description) tuple, and refactors Skill/InlineSkill/FileSkill/ClassSkill to store and expose that frontmatter.
Changes:
- Introduces
SkillFrontmatterwith validation (name/description/compatibility) and optional spec fields (license/allowed_tools/metadata). - Updates
FileSkillsSourceparsing to use YAML parsing for frontmatter and returns(frontmatter, content). - Refactors skill constructors and updates the test suite and public exports accordingly.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| python/packages/core/agent_framework/_skills.py | Adds SkillFrontmatter, refactors Skill to store frontmatter, switches file frontmatter parsing to YAML. |
| python/packages/core/agent_framework/init.py | Exports SkillFrontmatter from the package API. |
| python/packages/core/tests/core/test_skills.py | Updates tests for the new frontmatter-based APIs and adds SkillFrontmatter validation tests. |
Comments suppressed due to low confidence (1)
python/packages/core/agent_framework/_skills.py:2550
_extract_frontmatternow returnsSkillFrontmatter | None, but the docstring still says it returns a(name, description)tuple. Please update the Returns section to match the new return type (and include any behavior changes, e.g., optional fields parsing).
"""Extract and validate YAML frontmatter from a SKILL.md file.
Parses the ``---``-delimited frontmatter block for ``name`` and
``description`` fields.
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
frontmatter is missing, malformed, or fails validation.
"""
| import yaml | ||
|
|
There was a problem hiding this comment.
I see, I will parse without this library.
| skill = InlineSkill( | ||
| name="db-skill", | ||
| description="Database operations", | ||
| SkillFrontmatter(name="db-skill", description="Database operations") |
| # Normalize! | ||
| parsed = {k.lower(): v for k, v in raw_data.items()} | ||
|
|
||
| name: str | None = parsed.get("name") | ||
| description: str | None = parsed.get("description") | ||
| compatibility: str | None = parsed.get("compatibility") | ||
| allowed_tools_raw: str | None = parsed.get("allowed_tools") | ||
| allowed_tools = [t for t in allowed_tools_raw.split() if t] if allowed_tools_raw else [] | ||
|
|
| ) | ||
|
|
||
| return None | ||
|
|
There was a problem hiding this comment.
This validation happens in the SkillFrontmatter class added
Motivation and Context
This PR supports #5710
Description
Creates the class
SkillFrontmatterand use it in theSkillabstract class (and its child). I took as reference the dotnet implementation (SkillFrontmatter). I'm also usingyamlto parse correctly the frontmatter section.Contribution Checklist