Add capability and non-hero references for Python skills

.github/plugins/azure-sdk-python/skills/agent-framework-azure-ai-py/SKILL.md

@@ -347,7 +347,7 @@ if __name__ == "__main__":
 
 ## Best Practices
 
-1. **This SDK is async-first** — use `async def` handlers and `async with` throughout.
+1. **This SDK is async-first — use `async def` handlers and `async with` throughout.**
 2. **Always use context managers for clients and async credentials.** Wrap every client in `with Client(...) as client:` (sync) or `async with Client(...) as client:` (async). For async `DefaultAzureCredential` from `azure.identity.aio`, also use `async with credential:` so tokens and transports are cleaned up.
 
 ## Reference Files

.github/plugins/azure-sdk-python/skills/azure-ai-contentsafety-py/SKILL.md

@@ -240,3 +240,10 @@ request = AnalyzeTextOptions(
 7. **Log analysis results** for audit and improvement
 8. **Consider 8-severity mode** for finer-grained control
 9. **Pre-moderate AI outputs** before showing to users
+
+## Reference Files
+
+| File | Contents |
+|------|----------|
+| [references/capabilities.md](references/capabilities.md) | Additional non-hero capabilities, operation-group coverage, and production checklists. |
+| [references/non-hero-scenarios.md](references/non-hero-scenarios.md) | Dedicated non-hero examples for secondary/advanced scenarios. |

.github/plugins/azure-sdk-python/skills/azure-ai-contentsafety-py/references/capabilities.md

@@ -0,0 +1,34 @@
+# azure-ai-contentsafety-py capability coverage
+
+**SDK/package**: `azure-ai-contentsafety`
+
+This index maps hero scenarios in `SKILL.md` and links non-hero scenarios documented in dedicated reference files.
+
+## Hero scenarios covered in SKILL.md
+
+- `Analyze Text`
+- `Analyze Image`
+- `Text Blocklist Management`
+- `Severity Levels`
+
+## Non-hero scenarios
+
+- `Harm Categories`: | Category | Description |  
+  See: [`non-hero-scenarios.md#harm-categories`](non-hero-scenarios.md#harm-categories)
+- `Severity Scale`: | Level | Text Range | Image Range | Meaning |  
+  See: [`non-hero-scenarios.md#severity-scale`](non-hero-scenarios.md#severity-scale)
+- `Client Types`: | Client | Purpose |  
+  See: [`non-hero-scenarios.md#client-types`](non-hero-scenarios.md#client-types)
+
+## Related deep-dive references
+
+- [`non-hero-scenarios.md`](non-hero-scenarios.md): Dedicated non-hero examples and implementation notes.
+
+## API breadth checklist
+
+- Verify client/auth mode for the environment before coding.
+- Confirm operation-group/method names against current Microsoft Learn API reference.
+- For Python SDKs with both sync and async clients, document both forms without a blanket preference.
+- Include cleanup/delete paths for created resources in examples.
+- Prefer idempotent create/update operations where available.
+- Validate paging/LRO/error-handling patterns for production paths.

.github/plugins/azure-sdk-python/skills/azure-ai-contentsafety-py/references/non-hero-scenarios.md

@@ -0,0 +1,29 @@
+# azure-ai-contentsafety-py non-hero scenarios
+
+These scenarios are intentionally separate from hero flows in `SKILL.md`.
+They cover secondary/advanced patterns typically used after the primary end-to-end path is working.
+
+## Harm Categories
+
+| Category | Description |
+|----------|-------------|
+| `Hate` | Attacks based on identity (race, religion, gender, etc.) |
+| `Sexual` | Sexual content, relationships, anatomy |
+| `Violence` | Physical harm, weapons, injury |
+| `SelfHarm` | Self-injury, suicide, eating disorders |
+
+## Severity Scale
+
+| Level | Text Range | Image Range | Meaning |
+|-------|------------|-------------|---------|
+| 0 | Safe | Safe | No harmful content |
+| 2 | Low | Low | Mild references |
+| 4 | Medium | Medium | Moderate content |
+| 6 | High | High | Severe content |
+
+## Client Types
+
+| Client | Purpose |
+|--------|---------|
+| `ContentSafetyClient` | Analyze text and images |
+| `BlocklistClient` | Manage custom blocklists |

.github/plugins/azure-sdk-python/skills/azure-ai-contentunderstanding-py/SKILL.md

@@ -292,3 +292,10 @@ from azure.ai.contentunderstanding.models import (
 7. **Use async client** for high-throughput scenarios with `azure.identity.aio` credentials
 8. **Handle long-running operations** — video/audio analysis can take minutes
 9. **Use URL sources** when possible to avoid upload overhead
+
+## Reference Files
+
+| File | Contents |
+|------|----------|
+| [references/capabilities.md](references/capabilities.md) | Additional non-hero capabilities, operation-group coverage, and production checklists. |
+| [references/non-hero-scenarios.md](references/non-hero-scenarios.md) | Dedicated non-hero examples for secondary/advanced scenarios. |

.github/plugins/azure-sdk-python/skills/azure-ai-contentunderstanding-py/references/capabilities.md

@@ -0,0 +1,46 @@
+# azure-ai-contentunderstanding-py capability coverage
+
+**SDK/package**: `azure-ai-contentunderstanding`
+
+This index maps hero scenarios in `SKILL.md` and links non-hero scenarios documented in dedicated reference files.
+
+## Hero scenarios covered in SKILL.md
+
+- `Core Workflow`
+- `Prebuilt Analyzers`
+- `Analyze Document`
+- `Access Document Content Details`
+
+## Non-hero scenarios
+
+- `Analyze Image`: Dedicated example and implementation notes.  
+  See: [`non-hero-scenarios.md#analyze-image`](non-hero-scenarios.md#analyze-image)
+- `Analyze Video`: Dedicated example and implementation notes.  
+  See: [`non-hero-scenarios.md#analyze-video`](non-hero-scenarios.md#analyze-video)
+- `Analyze Audio`: Dedicated example and implementation notes.  
+  See: [`non-hero-scenarios.md#analyze-audio`](non-hero-scenarios.md#analyze-audio)
+- `Custom Analyzers`: Create custom analyzers with field schemas for specialized extraction:  
+  See: [`non-hero-scenarios.md#custom-analyzers`](non-hero-scenarios.md#custom-analyzers)
+- `Analyzer Management`: Dedicated example and implementation notes.  
+  See: [`non-hero-scenarios.md#analyzer-management`](non-hero-scenarios.md#analyzer-management)
+- `Async Client`: Dedicated example and implementation notes.  
+  See: [`non-hero-scenarios.md#async-client`](non-hero-scenarios.md#async-client)
+- `Content Types`: | Class | For | Provides |  
+  See: [`non-hero-scenarios.md#content-types`](non-hero-scenarios.md#content-types)
+- `Model Imports`: Dedicated example and implementation notes.  
+  See: [`non-hero-scenarios.md#model-imports`](non-hero-scenarios.md#model-imports)
+- `Client Types`: | Client | Purpose |  
+  See: [`non-hero-scenarios.md#client-types`](non-hero-scenarios.md#client-types)
+
+## Related deep-dive references
+
+- [`non-hero-scenarios.md`](non-hero-scenarios.md): Dedicated non-hero examples and implementation notes.
+
+## API breadth checklist
+
+- Verify client/auth mode for the environment before coding.
+- Confirm operation-group/method names against current Microsoft Learn API reference.
+- For Python SDKs with both sync and async clients, document both forms without a blanket preference.
+- Include cleanup/delete paths for created resources in examples.
+- Prefer idempotent create/update operations where available.
+- Validate paging/LRO/error-handling patterns for production paths.

.github/plugins/azure-sdk-python/skills/azure-ai-contentunderstanding-py/references/non-hero-scenarios.md

@@ -0,0 +1,181 @@
+# azure-ai-contentunderstanding-py non-hero scenarios
+
+These scenarios are intentionally separate from hero flows in `SKILL.md`.
+They cover secondary/advanced patterns typically used after the primary end-to-end path is working.
+
+## Analyze Image
+
+```python
+from azure.ai.contentunderstanding.models import AnalyzeInput
+
+poller = client.begin_analyze(
+    analyzer_id="prebuilt-imageSearch",
+    inputs=[AnalyzeInput(url="https://example.com/image.jpg")]
+)
+result = poller.result()
+content = result.contents[0]
+print(content.markdown)
+```
+
+## Analyze Video
+
+```python
+from azure.ai.contentunderstanding.models import AnalyzeInput
+
+poller = client.begin_analyze(
+    analyzer_id="prebuilt-videoSearch",
+    inputs=[AnalyzeInput(url="https://example.com/video.mp4")]
+)
+
+result = poller.result()
+
+# Access video content (AudioVisualContent)
+content = result.contents[0]
+
+# Get transcript phrases with timing
+for phrase in content.transcript_phrases:
+    print(f"[{phrase.start_time} - {phrase.end_time}]: {phrase.text}")
+
+# Get key frames (for video)
+for frame in content.key_frames:
+    print(f"Frame at {frame.time}: {frame.description}")
+```
+
+## Analyze Audio
+
+```python
+from azure.ai.contentunderstanding.models import AnalyzeInput
+
+poller = client.begin_analyze(
+    analyzer_id="prebuilt-audioSearch",
+    inputs=[AnalyzeInput(url="https://example.com/audio.mp3")]
+)
+
+result = poller.result()
+
+# Access audio transcript
+content = result.contents[0]
+for phrase in content.transcript_phrases:
+    print(f"[{phrase.start_time}] {phrase.text}")
+```
+
+## Custom Analyzers
+
+Create custom analyzers with field schemas for specialized extraction:
+
+```python
+from azure.ai.contentunderstanding.models import (
+    AnalyzeInput,
+    ContentAnalyzer,
+    ContentFieldDefinition,
+    ContentFieldSchema,
+)
+
+# Create custom analyzer - returns an LRO poller; wait for provisioning to complete
+poller = client.begin_create_analyzer(
+    analyzer_id="my-invoice-analyzer",
+    resource=ContentAnalyzer(
+        description="Custom invoice analyzer",
+        base_analyzer_id="prebuilt-documentSearch",
+        field_schema=ContentFieldSchema(
+            fields={
+                "vendor_name": ContentFieldDefinition(type="string"),
+                "invoice_total": ContentFieldDefinition(type="number"),
+                "line_items": ContentFieldDefinition(
+                    type="array",
+                    item_definition=ContentFieldDefinition(
+                        type="object",
+                        properties={
+                            "description": ContentFieldDefinition(type="string"),
+                            "amount": ContentFieldDefinition(type="number"),
+                        },
+                    ),
+                ),
+            }
+        ),
+    ),
+)
+poller.result()  # wait until analyzer is ready
+
+# Use custom analyzer
+analyze_poller = client.begin_analyze(
+    analyzer_id="my-invoice-analyzer",
+    inputs=[AnalyzeInput(url="https://example.com/invoice.pdf")]
+)
+
+result = analyze_poller.result()
+
+# Access extracted fields from analyzed content
+content = result.contents[0]
+print(content.fields["vendor_name"].value_string)
+print(content.fields["invoice_total"].value_number)
+```
+
+## Analyzer Management
+
+```python
+# List all analyzers
+analyzers = client.list_analyzers()
+for analyzer in analyzers:
+    print(f"{analyzer.analyzer_id}: {analyzer.description}")
+
+# Get specific analyzer
+analyzer = client.get_analyzer("prebuilt-documentSearch")
+
+# Delete custom analyzer
+client.delete_analyzer("my-custom-analyzer")
+```
+
+## Async Client
+
+```python
+import asyncio
+import os
+from azure.ai.contentunderstanding.aio import ContentUnderstandingClient
+from azure.ai.contentunderstanding.models import AnalyzeInput
+from azure.identity.aio import DefaultAzureCredential
+
+async def analyze_document():
+    endpoint = os.environ["CONTENTUNDERSTANDING_ENDPOINT"]
+    async with DefaultAzureCredential() as credential:
+        async with ContentUnderstandingClient(
+            endpoint=endpoint,
+            credential=credential
+        ) as client:
+            poller = await client.begin_analyze(
+                analyzer_id="prebuilt-documentSearch",
+                inputs=[AnalyzeInput(url="https://example.com/doc.pdf")]
+            )
+            result = await poller.result()
+            content = result.contents[0]
+            return content.markdown
+
+asyncio.run(analyze_document())
+```
+
+## Content Types
+
+| Class | For | Provides |
+|-------|-----|----------|
+| `DocumentContent` | PDF, images, Office docs | Pages, tables, figures, paragraphs |
+| `AudioVisualContent` | Audio, video files | Transcript phrases, timing, key frames |
+
+Both derive from `AnalysisContent`, which provides basic information and a markdown representation.
+
+## Model Imports
+
+```python
+from azure.ai.contentunderstanding.models import (
+    AnalyzeInput,
+    AnalyzeResult,
+    DocumentContent,
+    AudioVisualContent,
+)
+```
+
+## Client Types
+
+| Client | Purpose |
+|--------|---------|
+| `ContentUnderstandingClient` | Sync client for all operations |
+| `ContentUnderstandingClient` (aio) | Async client for all operations |

.github/plugins/azure-sdk-python/skills/azure-ai-language-conversations-py/SKILL.md

@@ -96,4 +96,11 @@ with ConversationAnalysisClient(endpoint, credential) as client:
         }
     )
 
-    print(f"Top intent: {result['result']['prediction']['topIntent']}")
+    print(f"Top intent: {result['result']['prediction']['topIntent']}")
+
+## Reference Files
+
+| File | Contents |
+|------|----------|
+| [references/capabilities.md](references/capabilities.md) | Additional non-hero capabilities, operation-group coverage, and production checklists. |
+| [references/non-hero-scenarios.md](references/non-hero-scenarios.md) | Dedicated non-hero examples for secondary/advanced scenarios. |

.github/plugins/azure-sdk-python/skills/azure-ai-language-conversations-py/references/capabilities.md

@@ -0,0 +1,27 @@
+# azure-ai-language-conversations-py capability coverage
+
+**SDK/package**: `azure-ai-language-conversations`
+
+This index maps hero scenarios in `SKILL.md` and links non-hero scenarios documented in dedicated reference files.
+
+## Hero scenarios covered in SKILL.md
+
+- `Core workflow`
+
+## Non-hero scenarios
+
+- `Operational hardening`: Use this section for retries, timeouts, pagination, and cleanup patterns specific to this SDK.  
+  See: [`non-hero-scenarios.md#operational-hardening`](non-hero-scenarios.md#operational-hardening)
+
+## Related deep-dive references
+
+- [`non-hero-scenarios.md`](non-hero-scenarios.md): Dedicated non-hero examples and implementation notes.
+
+## API breadth checklist
+
+- Verify client/auth mode for the environment before coding.
+- Confirm operation-group/method names against current Microsoft Learn API reference.
+- For Python SDKs with both sync and async clients, document both forms without a blanket preference.
+- Include cleanup/delete paths for created resources in examples.
+- Prefer idempotent create/update operations where available.
+- Validate paging/LRO/error-handling patterns for production paths.