[Python] [Breaking] Extract skill spec metadata into SkillFrontmatter (#5775)

* Fix Skill docstring consistency and spelling

- Add ClassSkill to Skill class docstring concrete implementations list
- Normalize 'defence' to 'defense' for American English consistency
- Remove extra blank line in InlineSkill docstring example

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Fix E501 line-too-long lint error in test_skills.py

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Fix stale test section header to reflect SkillFrontmatter API

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Fix metadata children overriding top-level frontmatter fields

Scope YAML_KV_RE to column-0 keys only so indented children
under metadata: are not mistakenly parsed as top-level fields.
Add regression test and spec fields to sample SKILL.md files.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

python/samples/02-agents/skills/code_defined_skill/code_defined_skill.py

@@ -11,7 +11,7 @@ import os
 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 @@ load_dotenv()
 # 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.
 

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

python/samples/02-agents/skills/mixed_skills/mixed_skills.py

@@ -21,6 +21,7 @@ from agent_framework import (
     FileSkillsSource,
     InlineSkill,
     InMemorySkillsSource,
+    SkillFrontmatter,
     SkillsProvider,
 )
 from agent_framework.foundry import FoundryChatClient
@@ -73,8 +74,9 @@ load_dotenv()
 # ---------------------------------------------------------------------------
 
 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 @@ class TemperatureConverterSkill(ClassSkill):
 # 3. Wire everything together and run the agent
 # ---------------------------------------------------------------------------
 
+
 async def main() -> None:
     """Run the combined skills demo."""
     endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]

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

python/samples/02-agents/skills/script_approval/script_approval.py

@@ -9,7 +9,7 @@ import os
 # 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 @@ load_dotenv()
 
 # 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.
 

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",
         )
     )
 

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

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