Python: Support skill scripts execution

[SergeyMenshykh]

Summary

Adds support for executing agent skill scripts — both file-based scripts (delegated to a SkillScriptExecutor) and code-defined scripts (registered via the @skill.script decorator and executed in-process).

Changes

Core (packages/core/agent_framework/_skills.py)

• Added SkillScript model with optional function (code-based) and path (file-based) fields
• Added SkillScriptExecutor abstract base class for file-based script execution strategies
• Added CallbackSkillScriptExecutor for user-provided execution callbacks
• Added execute_skill_script tool with optional user-approval gate (require_script_approval)
• Script-execution instructions injected into the system prompt when scripts are present
• Updated Skill model with mutable scripts list
• Added @skill.script decorator for registering code-defined scripts

Exports (__init__.py)

• Exported new public types: SkillScript, SkillScriptExecutor, CallbackSkillScriptExecutor

Tests (tests/core/test_skills.py)

• Comprehensive test coverage for script execution scenarios (file-based, code-defined, approval, error handling)

Samples

• Restructured skill samples with clearer naming (file_based_skill, code_defined_skill, mixed_skills, script_approval)
• Added shared subprocess_script_runner.py utility for file-based script execution via subprocess
• Each sample has a dedicated README

Design Decisions

• File-based scripts require an explicit SkillScriptExecutor — the framework does not assume a specific execution strategy (subprocess, sandbox, hosted interpreter, etc.)
• Code-defined scripts execute in-process and bypass the executor entirely
• Script execution is opt-in: skills without scripts work exactly as before
• The execute_skill_script tool supports an optional approval gate for safety

Closes: #4349

[markwallace-microsoft]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/core/agent_framework
_skills.py	409	13	96%	969–971, 1028, 1067–1068, 1141, 1146, 1195, 1200, 1352–1353, 1601
TOTAL	22801	2567	88%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
5035	20 💤	0 ❌	0 🔥	1m 19s ⏱️

[Copilot]

Pull request overview

Adds first-class support for executing skill scripts in the Python agent framework, covering both file-based scripts (delegated to a configurable executor) and code-defined scripts (registered via a decorator and executed in-process). This extends the existing SkillsProvider progressive-disclosure model to include script execution and introduces new samples demonstrating file skills, mixed skills, and human approval gating.

Changes:

• Core: add SkillScript, @skill.script, script discovery, and an execute_skill_script tool with optional approval gating.
• Public API: export new script-related types from agent_framework.__init__.
• Ecosystem: add/refresh samples for file skills, code-defined skills, mixed skills, and script approval; expand test coverage for script behavior.

Reviewed changes

Copilot reviewed 27 out of 27 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
python/packages/core/agent_framework/_skills.py	Adds script model/executor APIs, script discovery, prompt/tool wiring, and runtime execution path.
python/packages/core/agent_framework/init.py	Exports new public script-related types.
python/packages/core/tests/core/test_skills.py	Adds extensive tests for script discovery/execution, approval mode, and edge cases.
python/packages/core/AGENTS.md	Updates package layout docs to include the skills module.
python/samples/02-agents/skills/subprocess_script_runner.py	Adds a shared subprocess-based file-script runner callback for samples.
python/samples/02-agents/skills/README.md	Adds a top-level index README for the skills learning path and concepts.
python/samples/02-agents/skills/file_based_skill/file_based_skill.py	New file-based skill sample demonstrating script execution via callback executor.
python/samples/02-agents/skills/file_based_skill/README.md	Documentation for running and understanding the file-based skill sample.
python/samples/02-agents/skills/file_based_skill/skills/password-generator/SKILL.md	Adds a file-based skill definition that references a script.
python/samples/02-agents/skills/file_based_skill/skills/password-generator/references/PASSWORD_GUIDELINES.md	Adds reference guidelines for the password-generator file skill.
python/samples/02-agents/skills/file_based_skill/skills/password-generator/scripts/generate.py	Adds the executable password generator script used by the file-based sample.
python/samples/02-agents/skills/mixed_skills/mixed_skills.py	New mixed sample combining code-defined scripts/resources with a file-based scripted skill.
python/samples/02-agents/skills/mixed_skills/README.md	Documentation for the mixed skills sample and how it wires both skill types.
python/samples/02-agents/skills/mixed_skills/skills/password-generator/SKILL.md	Adds a file-based password-generator skill used by the mixed sample.
python/samples/02-agents/skills/mixed_skills/skills/password-generator/references/PASSWORD_GUIDELINES.md	Adds reference guidelines for the mixed-sample password-generator skill.
python/samples/02-agents/skills/mixed_skills/skills/password-generator/scripts/generate.py	Adds the password generator script used by the mixed sample.
python/samples/02-agents/skills/script_approval/script_approval.py	New sample showing how to require human approval before executing scripts.
python/samples/02-agents/skills/script_approval/README.md	Documentation for the script approval workflow sample.
python/samples/02-agents/skills/code_skill/code_skill.py	Removes/renames the older code skill sample in favor of the new code-defined-skill sample.
python/samples/02-agents/skills/code_skill/README.md	Removes the older code skill sample README.
python/samples/02-agents/skills/code_defined_skill/code_defined_skill.py	Adds the updated code-defined skill sample including @skill.script.
python/samples/02-agents/skills/code_defined_skill/README.md	Documentation for the code-defined skill sample.
python/samples/02-agents/skills/basic_skill/basic_skill.py	Removes the older “basic_skill” sample.
python/samples/02-agents/skills/basic_skill/README.md	Removes the older “basic_skill” README.
python/samples/02-agents/skills/basic_skill/skills/expense-report/SKILL.md	Removes the older expense-report file skill.
python/samples/02-agents/skills/basic_skill/skills/expense-report/references/POLICY_FAQ.md	Removes the older expense-report FAQ resource.
python/samples/02-agents/skills/basic_skill/skills/expense-report/assets/expense-report-template.md	Removes the older expense-report template asset.

[eavanvalkenburg]

for me this is not what I think about with the term callback, I would say something like executor or runner would be more applicable, and we might be able to reuse some of the concept from the ShellTool, @dmytrostruk could you have a look as well?

[eavanvalkenburg]

how many custom subclasses of this do we realistically expects? in python we can always subclass the below concrete class so might not be necessary...

[SergeyMenshykh]

I don't expect many executors to be shipped as part of the core package. For now, we'll definitely include CallbackSkillScriptExecutor (subject to renaming) because it's versatile. Later, we may add executors for various Azure offerings that run scripts in a sandboxed environment. Users may also want to create their own executors. I'm open to dropping the abstract base class; however, in that case, CallbackSkillScriptExecutor would need to accept an optional callback, allowing subclasses to override the execute method without providing one.

[TaoChenOSU]

Should it allow both file based and function based?

[TaoChenOSU]

The name executor may be confused with the executor concept in workflows. Have we considered Runner or Dispatcher?

[TaoChenOSU]

Will kwargs get advertised to the agent? What happens if the agent overrides the runtime arguments?