{"owner":"microsoft","repo":"agent-framework","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["python/.github/skills/python-development/SKILL.md"],"skills":{"python/.github/skills/python-development/SKILL.md":"---\nname: python-development\ndescription: >\n  Coding standards, conventions, and patterns for developing Python code in the\n  Agent Framework repository. Use this when writing or modifying Python source\n  files in the python/ directory.\n---\n\n# Python Development Standards\n\n## File Header\n\nEvery `.py` file must start with:\n\n```python\n# Copyright (c) Microsoft. All rights reserved.\n```\n\n## Type Annotations\n\n- Always specify return types and parameter types\n- Use `Type | None` instead of `Optional[Type]`\n- Use `from __future__ import annotations` to enable postponed evaluation\n- Use suffix `T` for TypeVar names: `ChatResponseT = TypeVar(\"ChatResponseT\", bound=ChatResponse)`\n- Use `Mapping` instead of `MutableMapping` for read-only input parameters\n- Prefer `# type: ignore[...]` over unnecessary casts, or `isinstance` checks, when these are internally called and executed methods\n    But make sure the ignore is specific for both mypy and pyright so that we don't miss other mistakes\n- Internal private helpers may be used across `agent_framework*` modules when intentional; use a targeted\n  `# pyright: ignore[reportPrivateUsage]` instead of making the helper public just to satisfy pyright.\n- Do not add trivial pass-through or one-line helper functions solely to appease typing. Prefer targeted ignores,\n  casts, or clearer annotations over adding runtime overhead without a design benefit.\n\n## Function Parameters\n\n- Positional parameters: up to 3 fully expected parameters\n- Use keyword-only arguments (after `*`) for optional parameters\n- Provide string-based overrides to avoid requiring extra imports:\n\n```python\ndef create_agent(name: str, tool_mode: Literal['auto', 'required', 'none'] | ChatToolMode) -> Agent:\n    if isinstance(tool_mode, str):\n        tool_mode = ChatToolMode(tool_mode)\n```\n\n- Avoid shadowing built-ins (use `next_handler` instead of `next`)\n- Avoid `**kwargs` unless needed for subclass extensibility; prefer named parameters\n\n## Docstrings\n\nUse Google-style docstrings for all public APIs:\n\n```python\ndef equal(arg1: str, arg2: str) -> bool:\n    \"\"\"Compares two strings and returns True if they are the same.\n\n    Args:\n        arg1: The first string to compare.\n        arg2: The second string to compare.\n\n    Returns:\n        True if the strings are the same, False otherwise.\n\n    Raises:\n        ValueError: If one of the strings is empty.\n    \"\"\"\n```\n\n- Always document Agent Framework specific exceptions\n- Explicitly use `Keyword Args` when applicable\n- Only document standard Python exceptions when the condition is non-obvious\n\n## Import Structure\n\n```python\n# Core\nfrom agent_framework import Agent, Message, tool\n\n# Components\nfrom agent_framework.observability import enable_sensitive_telemetry\n\n# Connectors (lazy-loaded)\nfrom agent_framework.openai import OpenAIChatClient\nfrom agent_framework.foundry import FoundryChatClient\n```\n\n## Public API and Exports\n\nIn `__init__.py` files that define package-level public APIs, use direct re-export imports plus an explicit\n`__all__`. Avoid identity aliases like `from ._agents import Agent as Agent`, and avoid\n`from module import *`.\n\nDo not define `__all__` in internal non-`__init__.py` modules. Exception: modules intentionally exposed as a\npublic import surface (for example, `agent_framework.observability`) should define `__all__`.\n\n```python\n__all__ = [\"Agent\", \"Message\", \"ChatResponse\"]\n\nfrom ._agents import Agent\nfrom ._types import Message, ChatResponse\n```\n\nSpecial case: the root `agent_framework/__init__.py` uses lazy runtime exports. For root public API changes:\n- Add the symbol to `_LAZY_MODULE_EXPORTS` and keep `_LAZY_EXPORTS` derived from it.\n- Keep the explicit runtime `__all__` synchronized; it is still required for `from agent_framework import *`.\n- Add the same public symbol to `agent_framework/__init__.pyi` so pyright, mypy, and editors see the typed surface.\n- Put runtime deprecation behavior in the owning module via that module's `__getattr__`; avoid root-level\n  special-case branches for individual deprecated exports.\n- Identity aliases are appropriate in `.pyi` stubs because they mark re-exported names for type checkers; avoid them\n  in runtime `.py` modules unless there is a specific compatibility reason.\n\n## Performance Guidelines\n\n- Cache expensive computations (e.g., JSON schema generation)\n- Prefer `match/case` on `.type` attribute over `isinstance()` in hot paths\n- Avoid redundant serialization — compute once, reuse\n\n## Style\n\n- Line length: 120 characters\n- Format only files you changed, not the entire codebase\n- Prefer attributes over inheritance when parameters are mostly the same\n- Async by default — assume everything is asynchronous\n\n## Naming Conventions for Connectors\n\n- `_prepare_<object>_for_<purpose>` for methods that prepare data for external services\n- `_parse_<object>_from_<source>` for methods that process data from external services\n"},"files":{"python/.github/skills/python-development/SKILL.md":"---\nname: python-development\ndescription: >\n  Coding standards, conventions, and patterns for developing Python code in the\n  Agent Framework repository. Use this when writing or modifying Python source\n  files in the python/ directory.\n---\n\n# Python Development Standards\n\n## File Header\n\nEvery `.py` file must start with:\n\n```python\n# Copyright (c) Microsoft. All rights reserved.\n```\n\n## Type Annotations\n\n- Always specify return types and parameter types\n- Use `Type | None` instead of `Optional[Type]`\n- Use `from __future__ import annotations` to enable postponed evaluation\n- Use suffix `T` for TypeVar names: `ChatResponseT = TypeVar(\"ChatResponseT\", bound=ChatResponse)`\n- Use `Mapping` instead of `MutableMapping` for read-only input parameters\n- Prefer `# type: ignore[...]` over unnecessary casts, or `isinstance` checks, when these are internally called and executed methods\n    But make sure the ignore is specific for both mypy and pyright so that we don't miss other mistakes\n- Internal private helpers may be used across `agent_framework*` modules when intentional; use a targeted\n  `# pyright: ignore[reportPrivateUsage]` instead of making the helper public just to satisfy pyright.\n- Do not add trivial pass-through or one-line helper functions solely to appease typing. Prefer targeted ignores,\n  casts, or clearer annotations over adding runtime overhead without a design benefit.\n\n## Function Parameters\n\n- Positional parameters: up to 3 fully expected parameters\n- Use keyword-only arguments (after `*`) for optional parameters\n- Provide string-based overrides to avoid requiring extra imports:\n\n```python\ndef create_agent(name: str, tool_mode: Literal['auto', 'required', 'none'] | ChatToolMode) -> Agent:\n    if isinstance(tool_mode, str):\n        tool_mode = ChatToolMode(tool_mode)\n```\n\n- Avoid shadowing built-ins (use `next_handler` instead of `next`)\n- Avoid `**kwargs` unless needed for subclass extensibility; prefer named parameters\n\n## Docstrings\n\nUse Google-style docstrings for all public APIs:\n\n```python\ndef equal(arg1: str, arg2: str) -> bool:\n    \"\"\"Compares two strings and returns True if they are the same.\n\n    Args:\n        arg1: The first string to compare.\n        arg2: The second string to compare.\n\n    Returns:\n        True if the strings are the same, False otherwise.\n\n    Raises:\n        ValueError: If one of the strings is empty.\n    \"\"\"\n```\n\n- Always document Agent Framework specific exceptions\n- Explicitly use `Keyword Args` when applicable\n- Only document standard Python exceptions when the condition is non-obvious\n\n## Import Structure\n\n```python\n# Core\nfrom agent_framework import Agent, Message, tool\n\n# Components\nfrom agent_framework.observability import enable_sensitive_telemetry\n\n# Connectors (lazy-loaded)\nfrom agent_framework.openai import OpenAIChatClient\nfrom agent_framework.foundry import FoundryChatClient\n```\n\n## Public API and Exports\n\nIn `__init__.py` files that define package-level public APIs, use direct re-export imports plus an explicit\n`__all__`. Avoid identity aliases like `from ._agents import Agent as Agent`, and avoid\n`from module import *`.\n\nDo not define `__all__` in internal non-`__init__.py` modules. Exception: modules intentionally exposed as a\npublic import surface (for example, `agent_framework.observability`) should define `__all__`.\n\n```python\n__all__ = [\"Agent\", \"Message\", \"ChatResponse\"]\n\nfrom ._agents import Agent\nfrom ._types import Message, ChatResponse\n```\n\nSpecial case: the root `agent_framework/__init__.py` uses lazy runtime exports. For root public API changes:\n- Add the symbol to `_LAZY_MODULE_EXPORTS` and keep `_LAZY_EXPORTS` derived from it.\n- Keep the explicit runtime `__all__` synchronized; it is still required for `from agent_framework import *`.\n- Add the same public symbol to `agent_framework/__init__.pyi` so pyright, mypy, and editors see the typed surface.\n- Put runtime deprecation behavior in the owning module via that module's `__getattr__`; avoid root-level\n  special-case branches for individual deprecated exports.\n- Identity aliases are appropriate in `.pyi` stubs because they mark re-exported names for type checkers; avoid them\n  in runtime `.py` modules unless there is a specific compatibility reason.\n\n## Performance Guidelines\n\n- Cache expensive computations (e.g., JSON schema generation)\n- Prefer `match/case` on `.type` attribute over `isinstance()` in hot paths\n- Avoid redundant serialization — compute once, reuse\n\n## Style\n\n- Line length: 120 characters\n- Format only files you changed, not the entire codebase\n- Prefer attributes over inheritance when parameters are mostly the same\n- Async by default — assume everything is asynchronous\n\n## Naming Conventions for Connectors\n\n- `_prepare_<object>_for_<purpose>` for methods that prepare data for external services\n- `_parse_<object>_from_<source>` for methods that process data from external services\n"},"items":[{"name":"SKILL.md","path":"python/.github/skills/python-development/SKILL.md","title":"python-development Skill","content":"---\nname: python-development\ndescription: >\n  Coding standards, conventions, and patterns for developing Python code in the\n  Agent Framework repository. Use this when writing or modifying Python source\n  files in the python/ directory.\n---\n\n# Python Development Standards\n\n## File Header\n\nEvery `.py` file must start with:\n\n```python\n# Copyright (c) Microsoft. All rights reserved.\n```\n\n## Type Annotations\n\n- Always specify return types and parameter types\n- Use `Type | None` instead of `Optional[Type]`\n- Use `from __future__ import annotations` to enable postponed evaluation\n- Use suffix `T` for TypeVar names: `ChatResponseT = TypeVar(\"ChatResponseT\", bound=ChatResponse)`\n- Use `Mapping` instead of `MutableMapping` for read-only input parameters\n- Prefer `# type: ignore[...]` over unnecessary casts, or `isinstance` checks, when these are internally called and executed methods\n    But make sure the ignore is specific for both mypy and pyright so that we don't miss other mistakes\n- Internal private helpers may be used across `agent_framework*` modules when intentional; use a targeted\n  `# pyright: ignore[reportPrivateUsage]` instead of making the helper public just to satisfy pyright.\n- Do not add trivial pass-through or one-line helper functions solely to appease typing. Prefer targeted ignores,\n  casts, or clearer annotations over adding runtime overhead without a design benefit.\n\n## Function Parameters\n\n- Positional parameters: up to 3 fully expected parameters\n- Use keyword-only arguments (after `*`) for optional parameters\n- Provide string-based overrides to avoid requiring extra imports:\n\n```python\ndef create_agent(name: str, tool_mode: Literal['auto', 'required', 'none'] | ChatToolMode) -> Agent:\n    if isinstance(tool_mode, str):\n        tool_mode = ChatToolMode(tool_mode)\n```\n\n- Avoid shadowing built-ins (use `next_handler` instead of `next`)\n- Avoid `**kwargs` unless needed for subclass extensibility; prefer named parameters\n\n## Docstrings\n\nUse Google-style docstrings for all public APIs:\n\n```python\ndef equal(arg1: str, arg2: str) -> bool:\n    \"\"\"Compares two strings and returns True if they are the same.\n\n    Args:\n        arg1: The first string to compare.\n        arg2: The second string to compare.\n\n    Returns:\n        True if the strings are the same, False otherwise.\n\n    Raises:\n        ValueError: If one of the strings is empty.\n    \"\"\"\n```\n\n- Always document Agent Framework specific exceptions\n- Explicitly use `Keyword Args` when applicable\n- Only document standard Python exceptions when the condition is non-obvious\n\n## Import Structure\n\n```python\n# Core\nfrom agent_framework import Agent, Message, tool\n\n# Components\nfrom agent_framework.observability import enable_sensitive_telemetry\n\n# Connectors (lazy-loaded)\nfrom agent_framework.openai import OpenAIChatClient\nfrom agent_framework.foundry import FoundryChatClient\n```\n\n## Public API and Exports\n\nIn `__init__.py` files that define package-level public APIs, use direct re-export imports plus an explicit\n`__all__`. Avoid identity aliases like `from ._agents import Agent as Agent`, and avoid\n`from module import *`.\n\nDo not define `__all__` in internal non-`__init__.py` modules. Exception: modules intentionally exposed as a\npublic import surface (for example, `agent_framework.observability`) should define `__all__`.\n\n```python\n__all__ = [\"Agent\", \"Message\", \"ChatResponse\"]\n\nfrom ._agents import Agent\nfrom ._types import Message, ChatResponse\n```\n\nSpecial case: the root `agent_framework/__init__.py` uses lazy runtime exports. For root public API changes:\n- Add the symbol to `_LAZY_MODULE_EXPORTS` and keep `_LAZY_EXPORTS` derived from it.\n- Keep the explicit runtime `__all__` synchronized; it is still required for `from agent_framework import *`.\n- Add the same public symbol to `agent_framework/__init__.pyi` so pyright, mypy, and editors see the typed surface.\n- Put runtime deprecation behavior in the owning module via that module's `__getattr__`; avoid root-level\n  special-case branches for individual deprecated exports.\n- Identity aliases are appropriate in `.pyi` stubs because they mark re-exported names for type checkers; avoid them\n  in runtime `.py` modules unless there is a specific compatibility reason.\n\n## Performance Guidelines\n\n- Cache expensive computations (e.g., JSON schema generation)\n- Prefer `match/case` on `.type` attribute over `isinstance()` in hot paths\n- Avoid redundant serialization — compute once, reuse\n\n## Style\n\n- Line length: 120 characters\n- Format only files you changed, not the entire codebase\n- Prefer attributes over inheritance when parameters are mostly the same\n- Async by default — assume everything is asynchronous\n\n## Naming Conventions for Connectors\n\n- `_prepare_<object>_for_<purpose>` for methods that prepare data for external services\n- `_parse_<object>_from_<source>` for methods that process data from external services\n","category":"python","tokens":1228}]}