Python: Add Python feature lifecycle decorators for released APIs

[eavanvalkenburg]

Motivation and Context

This change adds a reusable way to mark APIs in released Python packages as experimental or release candidate without relying on hand-written docstring notes. It implements the lifecycle guidance requested in #904 and uses the Skills APIs in agent_framework._skills as the first migrated feature surface.

Closes #904

Description

• add shared experimental(...) and release_candidate(...) decorators in agent_framework._feature_stage
• inject standardized docstring blocks and attach optional stage metadata to decorated APIs
• emit experimental warnings on first use, once per feature by default, including the concrete API name in the warning message
• migrate the Skills APIs to the shared decorators and add focused tests for docstrings, metadata, warnings, and warning callsites
• add lifecycle guidance plus a feature-stage introspection sample and update the Skills samples with warning-filter comments

Contribution Checklist

• The code builds clean without any errors or warnings
• The PR follows the Contribution Guidelines
• All unit tests pass, and I have added new tests where possible
• Is this a breaking change? If yes, add "[BREAKING]" prefix to the title of the PR.

[Copilot]

Pull request overview

This PR introduces a standardized Python “feature lifecycle” mechanism for marking released APIs as experimental or release candidate, including docstring injection, optional introspection metadata, and (for experimental features) runtime warnings. It migrates the existing Skills surface to the new decorators and updates samples/tests accordingly, aligning with the lifecycle guidance requested in #904.

Changes:

• Add agent_framework._feature_stage with @experimental(...) / @release_candidate(...), plus stage enums, docstring block injection, metadata, and experimental runtime warnings.
• Migrate Skills APIs in agent_framework._skills to use @experimental(feature_id=ExperimentalFeature.SKILLS) and add/adjust tests around docstrings/metadata/warnings.
• Update Python samples and documentation to reflect the new warning behavior and provide a feature-stage introspection sample.

Reviewed changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
python/packages/core/agent_framework/_feature_stage.py	Adds lifecycle decorators, warning behavior, and stage metadata/enums.
python/packages/core/agent_framework/_skills.py	Migrates Skills APIs to the shared @experimental(...) decorator.
python/packages/core/agent_framework/_docstrings.py	Adds insert_docstring_block() to inject lifecycle blocks into docstrings.
python/packages/core/agent_framework/init.py	Re-exports ExperimentalFeature / ReleaseCandidateFeature from the root module.
python/packages/core/tests/core/test_feature_stage.py	Adds focused tests for metadata/docstrings/warnings behavior.
python/packages/core/tests/core/test_skills.py	Adds Skills experimental-stage assertions; adjusts imports and warning filtering.
python/packages/core/tests/core/test_docstrings.py	Adds tests for insert_docstring_block() placement behavior.
python/packages/core/tests/core/conftest.py	Globally filters Skills experimental warnings in core tests.
python/samples/02-agents/feature_stage_introspection.py	Adds a sample showing how to introspect __feature_stage__ / __feature_id__.
python/samples/02-agents/skills/*	Adds commented warning-filter snippets; updates one sample callsite for new kwargs forwarding.
python/samples/02-agents/skills/README.md	Documents how to suppress the experimental warning in the Skills samples.
python/AGENTS.md	Links the new python-feature-lifecycle guidance skill doc.
python/.github/skills/python-feature-lifecycle/SKILL.md	Adds repository guidance for package vs feature lifecycle and promotion.

[markwallace-microsoft]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/core/agent_framework
_docstrings.py	64	3	95%	43–44, 54
_feature_stage.py	112	15	86%	94, 149, 151, 158, 160–162, 169, 171, 176, 183, 201–202, 204, 230
_skills.py	412	15	96%	176, 888, 890–892, 946, 985–986, 1059, 1064, 1113, 1118, 1270–1271, 1519
TOTAL	28101	3370	88%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
5546	20 💤	0 ❌	0 🔥	1m 28s ⏱️