Add Learn-compatible docstring rules to SDK dev SKILL files

Add 'Docstring Type Annotations (Microsoft Learn Compatibility)' section
to both SKILL.md copies with rules, correct/wrong examples to prevent
the ':class:\X\ of :class:\Y\' anti-pattern from being reintroduced.

Author: Saurabh Badenkal

.claude/skills/dataverse-sdk-dev/SKILL.md

@@ -54,3 +54,35 @@ Navigation property names are case-sensitive and must match the entity's `$metad
 9. **Document public APIs** - Add Sphinx-style docstrings with examples for public methods
 10. **Define __all__ in module files** - Each module declares its own exports via `__all__` (e.g., `errors.py` defines `__all__ = ["HttpError", ...]`). Package `__init__.py` files should not re-export or redefine another module's `__all__`; they use `__all__ = []` to indicate no star-import exports.
 11. **Run black before committing** - Always run `python -m black <changed files>` before committing. CI will reject unformatted code. Config is in `pyproject.toml` under `[tool.black]`.
+
+### Docstring Type Annotations (Microsoft Learn Compatibility)
+
+This SDK's API reference is published on Microsoft Learn. The Learn doc pipeline parses `:type:` and `:rtype:` directives differently from standard Sphinx -- every word between `:class:` references is treated as a separate cross-reference (`<xref:word>`). Using Sphinx-style `:class:\`list\` of :class:\`str\`` produces broken `<xref:of>` links on Learn.
+
+**Rules for `:type:` and `:rtype:` directives:**
+
+- Use Python bracket notation for generic types: `list[str]`, `dict[str, Any]`, `list[dict]`
+- Use `or` (without `:class:`) for union types: `str or None`, `dict or list[dict]`
+- Use bracket nesting for complex types: `collections.abc.Iterable[list[dict]]`
+- Use `~` prefix for SDK types to show short name: `list[~PowerPlatform.Dataverse.models.record.Record]`
+- `:class:` is fine for single standalone types: `:class:\`str\``, `:class:\`bool\``
+
+**Never** use `:class:\`X\` of :class:\`Y\`` or `:class:\`X\` mapping :class:\`Y\` to :class:\`Z\`` -- the words `of`, `mapping`, `to` become broken `<xref:>` links.
+
+**Correct examples:**
+
+```rst
+:type data: dict or list[dict]
+:rtype: list[str]
+:rtype: collections.abc.Iterable[list[~PowerPlatform.Dataverse.models.record.Record]]
+:type select: list[str] or None
+:type columns: dict[str, typing.Any]
+```
+
+**Wrong examples (NEVER use):**
+
+```rst
+:type data: :class:`dict` or :class:`list` of :class:`dict`
+:rtype: :class:`list` of :class:`str`
+:type columns: :class:`dict` mapping :class:`str` to :class:`typing.Any`
+```

src/PowerPlatform/Dataverse/claude_skill/dataverse-sdk-dev/SKILL.md

@@ -28,3 +28,35 @@ This skill provides guidance for developers working on the PowerPlatform Dataver
 9. **Document public APIs** - Add Sphinx-style docstrings with examples for public methods
 10. **Define __all__ in module files** - Each module declares its own exports via `__all__` (e.g., `errors.py` defines `__all__ = ["HttpError", ...]`). Package `__init__.py` files should not re-export or redefine another module's `__all__`; they use `__all__ = []` to indicate no star-import exports.
 11. **Run black before committing** - Always run `python -m black <changed files>` before committing. CI will reject unformatted code. Config is in `pyproject.toml` under `[tool.black]`.
+
+### Docstring Type Annotations (Microsoft Learn Compatibility)
+
+This SDK's API reference is published on Microsoft Learn. The Learn doc pipeline parses `:type:` and `:rtype:` directives differently from standard Sphinx -- every word between `:class:` references is treated as a separate cross-reference (`<xref:word>`). Using Sphinx-style `:class:\`list\` of :class:\`str\`` produces broken `<xref:of>` links on Learn.
+
+**Rules for `:type:` and `:rtype:` directives:**
+
+- Use Python bracket notation for generic types: `list[str]`, `dict[str, Any]`, `list[dict]`
+- Use `or` (without `:class:`) for union types: `str or None`, `dict or list[dict]`
+- Use bracket nesting for complex types: `collections.abc.Iterable[list[dict]]`
+- Use `~` prefix for SDK types to show short name: `list[~PowerPlatform.Dataverse.models.record.Record]`
+- `:class:` is fine for single standalone types: `:class:\`str\``, `:class:\`bool\``
+
+**Never** use `:class:\`X\` of :class:\`Y\`` or `:class:\`X\` mapping :class:\`Y\` to :class:\`Z\`` -- the words `of`, `mapping`, `to` become broken `<xref:>` links.
+
+**Correct examples:**
+
+```rst
+:type data: dict or list[dict]
+:rtype: list[str]
+:rtype: collections.abc.Iterable[list[~PowerPlatform.Dataverse.models.record.Record]]
+:type select: list[str] or None
+:type columns: dict[str, typing.Any]
+```
+
+**Wrong examples (NEVER use):**
+
+```rst
+:type data: :class:`dict` or :class:`list` of :class:`dict`
+:rtype: :class:`list` of :class:`str`
+:type columns: :class:`dict` mapping :class:`str` to :class:`typing.Any`
+```