chore: import upstream snapshot with attribution

python/samples/02-agents/skills/file_based_skill/README.md

@@ -0,0 +1,69 @@
+# File-Based Agent Skills
+
+This sample demonstrates how to use **file-based Agent Skills** with a `SkillsProvider` in the Microsoft Agent Framework. File-based skills are discovered from `SKILL.md` files on disk and can include reference documents and executable scripts.
+
+## What are Agent Skills?
+
+Agent Skills are modular packages of instructions and resources that enable AI agents to perform specialized tasks. They follow the [Agent Skills specification](https://agentskills.io/) and implement progressive disclosure:
+
+1. **Advertise**: Skills are advertised with name + description (~100 tokens per skill)
+2. **Load**: Full instructions are loaded on-demand via `load_skill` tool
+3. **Resources**: References and other files loaded via `read_skill_resource` tool
+4. **Scripts**: Executable scripts run via `run_skill_script` tool
+
+## Skills Included
+
+### unit-converter
+Converts between common units (miles↔km, pounds↔kg) using a multiplication factor following [agentskills.io guidelines](https://agentskills.io/skill-creation/using-scripts).
+- `references/CONVERSION_TABLES.md` — Supported conversions and their factors
+- `scripts/convert.py` — Executable script with `--value` and `--factor` flags, JSON output, and `--help` support
+
+## Key Components
+
+- **`SkillsProvider`** — Discovers skills from `SKILL.md` files in a directory and registers tools for the agent
+- **`subprocess_script_runner`** — A `SkillScriptRunner` callback that runs scripts as local Python subprocesses, enabling the `run_skill_script` tool. Converts argument dicts to CLI flags (e.g. `{"value": 26.2, "factor": 1.60934}` → `--value 26.2 --factor 1.60934`). Shared across samples in [`../subprocess_script_runner.py`](../subprocess_script_runner.py).
+
+## Project Structure
+
+```
+file_based_skill/
+├── file_based_skill.py
+├── README.md
+└── skills/
+    └── unit-converter/
+        ├── SKILL.md
+        ├── references/
+        │   └── CONVERSION_TABLES.md
+        └── scripts/
+            └── convert.py
+```
+
+## Running the Sample
+
+### Prerequisites
+- An [Azure AI Foundry](https://ai.azure.com/) project with a deployed model (e.g. `gpt-4o-mini`)
+
+### Environment Variables
+
+Set the required environment variables in a `.env` file (see `python/.env.example`):
+
+- `FOUNDRY_PROJECT_ENDPOINT`: Your Azure AI Foundry project endpoint
+- `AZURE_OPENAI_MODEL`: The name of your model deployment (defaults to `gpt-4o-mini`)
+
+### Authentication
+
+This sample uses `AzureCliCredential` for authentication. Run `az login` in your terminal before running the sample.
+
+### Run
+
+```bash
+cd python
+uv run samples/02-agents/skills/file_based_skill/file_based_skill.py
+```
+
+## Learn More
+
+- [Agent Skills Specification](https://agentskills.io/)
+- [Code-Defined Skills Sample](../code_defined_skill/)
+- [Mixed Skills Sample](../mixed_skills/)
+- [Microsoft Agent Framework Documentation](../../../../../docs/)

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

@@ -0,0 +1,98 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import os
+import sys
+from pathlib import Path
+
+from agent_framework import Agent, SkillsProvider, ToolApprovalMiddleware
+from agent_framework.foundry import FoundryChatClient
+from azure.identity import AzureCliCredential
+from dotenv import load_dotenv
+
+# Add the skills folder root to sys.path so the shared subprocess_script_runner can be imported
+_SKILLS_ROOT = str(Path(__file__).resolve().parent.parent)
+if _SKILLS_ROOT not in sys.path:
+    sys.path.insert(0, _SKILLS_ROOT)
+
+from subprocess_script_runner import subprocess_script_runner  # pyrefly: ignore[missing-import]  # noqa: E402
+
+"""
+File-Based Agent Skills
+
+This sample demonstrates how to use file-based Agent Skills with a SkillsProvider.
+Agent Skills are modular packages of instructions and resources that extend an agent's
+capabilities. They follow progressive disclosure:
+
+1. Advertise — skill names and descriptions are injected into the system prompt
+2. Load — full instructions are loaded on-demand via the load_skill tool
+3. Read resources — supplementary files are read via the read_skill_resource tool
+4. Run scripts — skill scripts are run via the run_skill_script tool
+
+This sample includes the unit-converter skill which demonstrates all three
+file-based capabilities: instructions (SKILL.md), resources (CONVERSION_TABLES.md),
+and scripts (convert.py).
+"""
+
+# Load environment variables from .env file
+load_dotenv()
+
+
+async def main() -> None:
+    """Run the file-based skills demo."""
+    endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
+    deployment = os.environ.get("FOUNDRY_MODEL", "gpt-4o-mini")
+
+    # Create the chat client
+    client = FoundryChatClient(
+        project_endpoint=endpoint,
+        model=deployment,
+        credential=AzureCliCredential(),
+    )
+
+    # Create the skills provider
+    # Discovers skills from the 'skills' directory and configures the
+    # subprocess_script_runner to run file-based scripts.
+    skills_dir = Path(__file__).parent / "skills"
+    skills_provider = SkillsProvider.from_paths(
+        skill_paths=str(skills_dir),
+        script_runner=subprocess_script_runner,
+    )
+
+    # Create the agent with skills. All skill tools require approval by
+    # default; auto-approve them so the sample runs unattended. See the
+    # script_approval / skills_auto_approval samples for approval handling.
+    async with Agent(
+        client=client,
+        instructions="You are a helpful assistant.",
+        context_providers=[skills_provider],
+        middleware=[ToolApprovalMiddleware(auto_approval_rules=[SkillsProvider.all_tools_auto_approval_rule])],
+    ) as agent:
+        # The agent will: load the unit-converter skill, read the conversion
+        # tables resource, then execute the convert.py script.
+        print("Converting units")
+        print("-" * 60)
+        session = agent.create_session()
+        response = await agent.run(
+            "How many kilometers is a marathon (26.2 miles)? And how many pounds is 75 kilograms?",
+            session=session,
+        )
+        print(f"Agent: {response}\n")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+
+"""
+Sample output:
+
+Converting units
+------------------------------------------------------------
+Agent: Here are your conversions:
+
+1. **26.2 miles → 42.16 km** (a marathon distance)
+2. **75 kg → 165.35 lbs**
+
+I used the conversion factors from the reference table:
+miles × 1.60934 and kilograms × 2.20462.
+"""

python/samples/02-agents/skills/file_based_skill/skills/unit-converter/SKILL.md

@@ -0,0 +1,17 @@
+---
+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
+
+When the user requests a unit conversion:
+1. First, review `references/CONVERSION_TABLES.md` to find the correct factor
+2. Run the `scripts/convert.py` script with `--value <number> --factor <factor>` (e.g. `--value 26.2 --factor 1.60934`)
+3. Present the converted value clearly with both units

python/samples/02-agents/skills/file_based_skill/skills/unit-converter/references/CONVERSION_TABLES.md

@@ -0,0 +1,10 @@
+# Conversion Tables
+
+Formula: **result = value × factor**
+
+| From        | To          | Factor   |
+|-------------|-------------|----------|
+| miles       | kilometers  | 1.60934  |
+| kilometers  | miles       | 0.621371 |
+| pounds      | kilograms   | 0.453592 |
+| kilograms   | pounds      | 2.20462  |

python/samples/02-agents/skills/file_based_skill/skills/unit-converter/scripts/convert.py

@@ -0,0 +1,28 @@
+# Unit conversion script
+# Converts a value using a multiplication factor: result = value × factor
+#
+# Usage:
+#   python scripts/convert.py --value 26.2 --factor 1.60934
+#   python scripts/convert.py --value 75 --factor 2.20462
+
+import argparse
+import json
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Convert a value using a multiplication factor.",
+        epilog="Examples:\n"
+        "  python scripts/convert.py --value 26.2 --factor 1.60934\n"
+        "  python scripts/convert.py --value 75 --factor 2.20462",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument("--value", type=float, required=True, help="The numeric value to convert.")
+    parser.add_argument("--factor", type=float, required=True, help="The conversion factor from the table.")
+    args = parser.parse_args()
+    result = round(args.value * args.factor, 4)
+    print(json.dumps({"value": args.value, "factor": args.factor, "result": result}))
+
+
+if __name__ == "__main__":
+    main()