opencode-skills-collection 3.1.12 → 3.1.14

package/bundled-skills/aws-serverless-eda/SKILL.md

@@ -0,0 +1,394 @@
+---
+name: aws-serverless-eda
+description: AWS serverless and event-driven architecture expert based on Well-Architected Framework. Use when building serverless APIs, Lambda functions, REST APIs, microservices, or async workflows. Covers Lambda with TypeScript/Python, API Gateway (REST/HTTP), DynamoDB, Step Functions,...
+risk: unknown
+source: https://github.com/zxkane/aws-skills/tree/main/plugins/serverless-eda/skills/aws-serverless-eda
+source_repo: zxkane/aws-skills
+source_type: community
+date_added: 2026-07-01
+license: MIT
+license_source: https://github.com/zxkane/aws-skills/blob/main/LICENSE
+---
+
+# AWS Serverless & Event-Driven Architecture
+
+This skill provides comprehensive guidance for building serverless applications and event-driven architectures on AWS based on Well-Architected Framework principles.
+
+## AWS Documentation Requirement
+
+Always verify AWS facts using MCP tools (`mcp__aws-mcp__*` or `mcp__*awsdocs*__*`) before answering. The `aws-mcp-setup` dependency is auto-loaded — if MCP tools are unavailable, guide the user through that skill's setup flow.
+
+## Serverless MCP Servers
+
+This skill leverages the CDK MCP server (provided via `aws-cdk-development` dependency) and AWS Documentation MCP for serverless guidance.
+
+> **Note**: The following AWS MCP servers are available separately via the Full AWS MCP Server (see `aws-mcp-setup` skill) and are not bundled with this plugin:
+> - AWS Serverless MCP — SAM CLI lifecycle (init, deploy, local test)
+> - AWS Lambda Tool MCP — Direct Lambda invocation
+> - AWS Step Functions MCP — Workflow orchestration
+> - Amazon SNS/SQS MCP — Messaging and queue management
+
+## When to Use This Skill
+
+Use this skill when:
+- Building serverless applications with Lambda
+- Designing event-driven architectures
+- Implementing microservices patterns
+- Creating asynchronous processing workflows
+- Orchestrating multi-service transactions
+- Building real-time data processing pipelines
+- Implementing saga patterns for distributed transactions
+- Designing for scale and resilience
+
+## AWS Well-Architected Serverless Design Principles
+
+### 1. Speedy, Simple, Singular
+
+**Functions should be concise and single-purpose**
+
+```typescript
+// ✅ GOOD - Single purpose, focused function
+export const processOrder = async (event: OrderEvent) => {
+  // Only handles order processing
+  const order = await validateOrder(event);
+  await saveOrder(order);
+  await publishOrderCreatedEvent(order);
+  return { statusCode: 200, body: JSON.stringify({ orderId: order.id }) };
+};
+
+// ❌ BAD - Function does too much
+export const handleEverything = async (event: any) => {
+  // Handles orders, inventory, payments, shipping...
+  // Too many responsibilities
+};
+```
+
+**Keep functions environmentally efficient and cost-aware**:
+- Minimize cold start times
+- Optimize memory allocation
+- Use provisioned concurrency only when needed
+- Leverage connection reuse
+
+### 2. Think Concurrent Requests, Not Total Requests
+
+**Design for concurrency, not volume**
+
+Lambda scales horizontally - design considerations should focus on:
+- Concurrent execution limits
+- Downstream service throttling
+- Shared resource contention
+- Connection pool sizing
+
+```typescript
+// Consider concurrent Lambda executions accessing DynamoDB
+const table = new dynamodb.Table(this, 'Table', {
+  billingMode: dynamodb.BillingMode.PAY_PER_REQUEST, // Auto-scales with load
+});
+
+// Or with provisioned capacity + auto-scaling
+const table = new dynamodb.Table(this, 'Table', {
+  billingMode: dynamodb.BillingMode.PROVISIONED,
+  readCapacity: 5,
+  writeCapacity: 5,
+});
+
+// Enable auto-scaling for concurrent load
+table.autoScaleReadCapacity({ minCapacity: 5, maxCapacity: 100 });
+table.autoScaleWriteCapacity({ minCapacity: 5, maxCapacity: 100 });
+```
+
+### 3. Share Nothing
+
+**Function runtime environments are short-lived**
+
+```typescript
+// ❌ BAD - Relying on local file system
+export const handler = async (event: any) => {
+  fs.writeFileSync('/tmp/data.json', JSON.stringify(data)); // Lost after execution
+};
+
+// ✅ GOOD - Use persistent storage
+export const handler = async (event: any) => {
+  await s3.putObject({
+    Bucket: process.env.BUCKET_NAME,
+    Key: 'data.json',
+    Body: JSON.stringify(data),
+  });
+};
+```
+
+**State management**:
+- Use DynamoDB for persistent state
+- Use Step Functions for workflow state
+- Use ElastiCache for session state
+- Use S3 for file storage
+
+### 4. Assume No Hardware Affinity
+
+**Applications must be hardware-agnostic**
+
+Infrastructure can change without notice:
+- Lambda functions can run on different hardware
+- Container instances can be replaced
+- No assumption about underlying infrastructure
+
+**Design for portability**:
+- Use environment variables for configuration
+- Avoid hardware-specific optimizations
+- Test across different environments
+
+### 5. Orchestrate with State Machines, Not Function Chaining
+
+**Use Step Functions for orchestration**
+
+```typescript
+// ❌ BAD - Lambda function chaining
+export const handler1 = async (event: any) => {
+  const result = await processStep1(event);
+  await lambda.invoke({
+    FunctionName: 'handler2',
+    Payload: JSON.stringify(result),
+  });
+};
+
+// ✅ GOOD - Step Functions orchestration
+const stateMachine = new stepfunctions.StateMachine(this, 'OrderWorkflow', {
+  definition: stepfunctions.Chain
+    .start(validateOrder)
+    .next(processPayment)
+    .next(shipOrder)
+    .next(sendConfirmation),
+});
+```
+
+**Benefits of Step Functions**:
+- Visual workflow representation
+- Built-in error handling and retries
+- Execution history and debugging
+- Parallel and sequential execution
+- Service integrations without code
+
+### 6. Use Events to Trigger Transactions
+
+**Event-driven over synchronous request/response**
+
+```typescript
+// Pattern: Event-driven processing
+const bucket = new s3.Bucket(this, 'DataBucket');
+
+bucket.addEventNotification(
+  s3.EventType.OBJECT_CREATED,
+  new s3n.LambdaDestination(processFunction),
+  { prefix: 'uploads/' }
+);
+
+// Pattern: EventBridge integration
+const rule = new events.Rule(this, 'OrderRule', {
+  eventPattern: {
+    source: ['orders'],
+    detailType: ['OrderPlaced'],
+  },
+});
+
+rule.addTarget(new targets.LambdaFunction(processOrderFunction));
+```
+
+**Benefits**:
+- Loose coupling between services
+- Asynchronous processing
+- Better fault tolerance
+- Independent scaling
+
+### 7. Design for Failures and Duplicates
+
+**Operations must be idempotent**
+
+```typescript
+// ✅ GOOD - Idempotent operation
+export const handler = async (event: SQSEvent) => {
+  for (const record of event.Records) {
+    const orderId = JSON.parse(record.body).orderId;
+
+    // Check if already processed (idempotency)
+    const existing = await dynamodb.getItem({
+      TableName: process.env.TABLE_NAME,
+      Key: { orderId },
+    });
+
+    if (existing.Item) {
+      console.log('Order already processed:', orderId);
+      continue; // Skip duplicate
+    }
+
+    // Process order
+    await processOrder(orderId);
+
+    // Mark as processed
+    await dynamodb.putItem({
+      TableName: process.env.TABLE_NAME,
+      Item: { orderId, processedAt: Date.now() },
+    });
+  }
+};
+```
+
+**Implement retry logic with exponential backoff**:
+```typescript
+async function withRetry<T>(fn: () => Promise<T>, maxRetries = 3): Promise<T> {
+  for (let i = 0; i < maxRetries; i++) {
+    try {
+      return await fn();
+    } catch (error) {
+      if (i === maxRetries - 1) throw error;
+      await new Promise(resolve => setTimeout(resolve, Math.pow(2, i) * 1000));
+    }
+  }
+  throw new Error('Max retries exceeded');
+}
+```
+
+## Architecture Patterns
+
+For detailed implementation patterns with full code examples, see the reference documentation:
+
+### Event-Driven Architecture Patterns
+**File**: `references/eda-patterns.md`
+- Event Router with EventBridge (custom event bus, schema registry, rule-based routing)
+- Queue-Based Processing with SQS (standard/FIFO, DLQ, Lambda consumers)
+- Pub/Sub Fan-Out with SNS + SQS (multi-consumer, filtering)
+- Saga Pattern with Step Functions (distributed transactions, compensating actions)
+- Event Sourcing with DynamoDB Streams (append-only event store, projections)
+
+### Serverless Architecture Patterns
+**File**: `references/serverless-patterns.md`
+- API-Driven Microservices (REST API + Lambda backend)
+- Stream Processing with Kinesis (real-time, batch windowing, bisect on error)
+- Async Task Processing with SQS (background jobs, concurrency control)
+- Scheduled Jobs with EventBridge (cron/rate schedules)
+- Webhook Processing (signature validation, async queue forwarding)
+
+> **Important**: When using CDK code examples from references, avoid hardcoding resource names (e.g., `restApiName`, `eventBusName`). Let CDK generate unique names automatically to enable reusability and parallel deployments. See `aws-cdk-development` skill for details.
+
+## Best Practices
+
+### Error Handling
+
+**Implement comprehensive error handling**:
+
+```typescript
+export const handler = async (event: SQSEvent) => {
+  const failures: SQSBatchItemFailure[] = [];
+
+  for (const record of event.Records) {
+    try {
+      await processRecord(record);
+    } catch (error) {
+      console.error('Failed to process record:', record.messageId, error);
+      failures.push({ itemIdentifier: record.messageId });
+    }
+  }
+
+  // Return partial batch failures for retry
+  return { batchItemFailures: failures };
+};
+```
+
+### Dead Letter Queues
+
+**Always configure DLQs for error handling**:
+
+```typescript
+const dlq = new sqs.Queue(this, 'DLQ', {
+  retentionPeriod: Duration.days(14),
+});
+
+const queue = new sqs.Queue(this, 'Queue', {
+  deadLetterQueue: {
+    queue: dlq,
+    maxReceiveCount: 3,
+  },
+});
+
+// Monitor DLQ depth
+new cloudwatch.Alarm(this, 'DLQAlarm', {
+  metric: dlq.metricApproximateNumberOfMessagesVisible(),
+  threshold: 1,
+  evaluationPeriods: 1,
+  alarmDescription: 'Messages in DLQ require attention',
+});
+```
+
+### Observability
+
+**Enable tracing and monitoring**:
+
+```typescript
+new NodejsFunction(this, 'Function', {
+  entry: 'src/handler.ts',
+  tracing: lambda.Tracing.ACTIVE, // X-Ray tracing
+  environment: {
+    POWERTOOLS_SERVICE_NAME: 'order-service',
+    POWERTOOLS_METRICS_NAMESPACE: 'MyApp',
+    LOG_LEVEL: 'INFO',
+  },
+});
+```
+
+## Using MCP Servers Effectively
+
+Use the CDK MCP server (via `aws-cdk-development` dependency) for construct recommendations and CDK-specific guidance when building serverless infrastructure.
+
+Use AWS Documentation MCP to verify service features, regional availability, and API specifications before implementing.
+
+## Additional Resources
+
+This skill includes comprehensive reference documentation based on AWS best practices:
+
+- **Serverless Patterns**: `references/serverless-patterns.md`
+  - Core serverless architectures and API patterns
+  - Data processing and integration patterns
+  - Orchestration with Step Functions
+  - Anti-patterns to avoid
+
+- **Event-Driven Architecture Patterns**: `references/eda-patterns.md`
+  - Event routing and processing patterns
+  - Event sourcing and saga patterns
+  - Idempotency and error handling
+  - Message ordering and deduplication
+
+- **Security Best Practices**: `references/security-best-practices.md`
+  - Shared responsibility model
+  - IAM least privilege patterns
+  - Data protection and encryption
+  - Network security with VPC
+
+- **Observability Best Practices**: `references/observability-best-practices.md`
+  - Three pillars: metrics, logs, traces
+  - Structured logging with Lambda Powertools
+  - X-Ray distributed tracing
+  - CloudWatch alarms and dashboards
+
+- **Performance Optimization**: `references/performance-optimization.md`
+  - Cold start optimization techniques
+  - Memory and CPU optimization
+  - Package size reduction
+  - Provisioned concurrency patterns
+
+- **Deployment Best Practices**: `references/deployment-best-practices.md`
+  - CI/CD pipeline design
+  - Testing strategies (unit, integration, load)
+  - Deployment strategies (canary, blue/green)
+  - Rollback and safety mechanisms
+
+**External Resources**:
+- **AWS Well-Architected Serverless Lens**: https://docs.aws.amazon.com/wellarchitected/latest/serverless-applications-lens/
+- **ServerlessLand.com**: Pre-built serverless patterns
+- **AWS Serverless Workshops**: https://serverlessland.com/learn?type=Workshops
+
+For detailed implementation patterns, anti-patterns, and code examples, refer to the comprehensive references in the skill directory.
+
+## Limitations
+
+- Use this skill only when the task clearly matches its upstream source and local project context.
+- Verify commands, generated code, dependencies, credentials, and external service behavior before applying changes.
+- Do not treat examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions.

package/bundled-skills/aws-sst-development/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: aws-sst-development
+description: SST v4 (Ion) expert for managing AWS resources as code with the Pulumi-backed framework. Use when writing or editing sst.config.ts, building infra/ modules (sst.aws.Function/Bucket/Dynamo/Cron/Service/Router, sst.Secret, sst.Linkable, raw aws.* Pulumi resources), wiring resource links,...
+risk: unknown
+source: https://github.com/zxkane/aws-skills/tree/main/plugins/aws-iac/skills/aws-sst-development
+source_repo: zxkane/aws-skills
+source_type: community
+date_added: 2026-07-01
+license: MIT
+license_source: https://github.com/zxkane/aws-skills/blob/main/LICENSE
+---
+
+# SST v4 for AWS
+## When to Use
+
+Use this skill when you need sST v4 (Ion) expert for managing AWS resources as code with the Pulumi-backed framework. Use when writing or editing sst.config.ts, building infra/ modules (sst.aws.Function/Bucket/Dynamo/Cron/Service/Router, sst.Secret, sst.Linkable, raw aws.* Pulumi resources), wiring resource links,...
+
+
+SST v4 (the "Ion" engine) is a Pulumi-backed IaC framework: you describe AWS
+resources in TypeScript and SST/Pulumi reconciles them into your account. It
+gives you high-level `sst.aws.*` components (Function, Bucket, Dynamo, Cron,
+Service, …) that expand into many underlying resources, plus an escape hatch to
+*any* raw Pulumi `aws.*` resource for the long tail. This skill encodes a
+production-proven way to author, link, test, deploy, and troubleshoot SST
+stacks on AWS — distilled from real multi-stack projects that have paid for
+each lesson with a prod incident.
+
+**SST and Pulumi are third-party — verify current syntax with Context7**
+(`resolve-library-id` → `query-docs` for `sst` or `pulumi-aws`) when you're
+unsure about a component's options. Verify AWS-side facts (service limits,
+model IDs, IAM action names, region availability) with the AWS docs MCP, never
+from memory. The patterns here are the *how*; the docs are the *what*.
+
+## When you're invoked
+
+Figure out which mode you're in and jump to the right reference:
+
+| Situation | Go to |
+|-----------|-------|
+| New project, or adding a resource/module to an existing SST app | **Author** → `references/authoring.md` |
+| Wiring one module's output into another (links, SSM, IAM scope) | **Author** → `references/authoring.md` § Sharing |
+| Writing tests for infra so changes don't silently break | **Test** → `references/testing.md` |
+| Running a deploy, or a deploy just failed | **Deploy/Operate** → `references/deploy-and-troubleshoot.md` |
+| Migrating a resource between Pulumi types, renaming a physical name | **Deploy/Operate** → `references/deploy-and-troubleshoot.md` § Migrations |
+
+Always read the relevant reference before editing — they carry the *why* behind
+each rule, which matters more than the rule itself.
+
+## Orientation: read the repo before you touch it
+
+SST projects are conventional but not identical. Before editing, build a quick
+map so your change matches the house style instead of fighting it:
+
+1. **`sst.config.ts`** — the app name, `home`, providers/region, `defaultTags`,
+   any global `$transform` (Node runtime pin, bundle fixups), and the order in
+   which `run()` imports `infra/` modules. The import order *is* the dependency
+   order; respect it.
+2. **`infra/`** — one file per domain (storage, functions, api, observability…).
+   This is where resources are declared. Check for an `infra/CLAUDE.md` — these
+   projects keep IaC-specific rules there, and it's the single most valuable
+   file to read first.
+3. **`infra/tests/`** — source-level Vitest assertions that pin resource
+   invariants. If they exist, your change must keep them green and probably
+   needs a new assertion.
+4. **`package.json` / `.nvmrc`** — package manager (npm vs pnpm), Node version,
+   and the `sst`/`pulumi` versions actually installed.
+
+Run `npx sst version` to confirm you're on v4/Ion (the `$config` + `.sst/platform/`
+signature). v2/v3 ("SST Classic", CDK-based) is a different framework — these
+patterns don't apply there.
+
+## The conventions, and which are universal vs tunable
+
+The projects this skill is built from share a deliberate house style. Some of it
+is **universal** (true for any SST v4 + AWS project — apply it everywhere); some
+is **project-specific** (a sensible default these projects chose — adopt it for
+consistency, but recognize a project may differ).
+
+**Universal — these principles hold for any SST v4 + AWS project:**
+
+- **Control the Node runtime deliberately, in one place.** Don't leave it to
+  whatever the installed SST happens to default to. The idiom is a single global
+  `$transform(sst.aws.Function, (args) => { args.runtime ??= "nodejs24.x" })` in
+  `run()` — `??=` is correct here (the transform runs before the component
+  applies its own default, so it fills in only when the user didn't set one).
+  Recent SST already defaults to a current Node runtime, so check the installed
+  default first (Context7); the transform is then version-independence insurance
+  so a future SST downgrade can't silently move your fleet. See
+  `references/authoring.md`.
+- **Never interpolate a Pulumi `Output<T>` into a plain JS template literal.**
+  Use `$interpolate` (or `pulumi.interpolate`). A bare top-level
+  `` `${bucket.arn}/*` `` stringifies the `Output` to a `[Output<T>]` placeholder
+  and produces a broken ARN that only fails at deploy time (it type-checks and
+  `sst dev` runs fine). The fix is `$interpolate`​`` `${bucket.arn}/*` ``. This
+  has caused prod deploy outages. See `references/authoring.md` § Outputs.
+- **Migrating a resource between Pulumi *types* should default to two PRs** —
+  Pulumi creates-before-destroys, so for a uniqueness-constrained AWS name
+  (bucket, IAM role, gateway) the old resource still owns it and the create
+  fails with `ConflictException`. Two sequential deploys (teardown, then
+  recreate) is the conservative default; `aliases:` / `pulumi import` / state
+  surgery can bridge identity in some cases but only with a reviewed plan. See
+  `references/deploy-and-troubleshoot.md` § Migrations.
+- **Prefer typed `sst.aws.*` / `aws.*` resources over the
+  `aws.cloudcontrol.Resource` escape hatch.** CloudControl outputs are
+  stringly-typed and `oneOf` fields don't patch cleanly. Use it only when no
+  typed resource exists yet, and migrate off it when one ships.
+
+**Project-specific defaults — adopt for consistency, but confirm per repo:**
+
+- **Region `ap-northeast-1`**, `home: "aws"`, and `defaultTags` carrying
+  `Project` / `Stage` / `ManagedBy: "sst"`.
+- **Stage-gated lifecycle**: `removal: stage === "prod" ? "retain" : "remove"`
+  and `protect: stage === "prod"` so prod resources survive a stack tear-down
+  and non-prod previews clean up.
+- **SSM Parameter Store as the out-of-graph contract** under a
+  `/{app}/{stage}/{domain}/...` prefix — for consumers that aren't in the
+  Pulumi graph (CI scripts, sibling apps, operators). For *same-app* Lambdas,
+  prefer SST `link:` (it wires a real dependency edge and grants IAM); don't
+  route same-app sharing through SSM. See `references/authoring.md` § Sharing.
+- **Lazy `await import("./infra/<module>")` inside `run()`** so `sst dev`
+  hot-reload stays light. (For testing, a module export still runs its top-level
+  `new sst.aws.*` unless it's wrapped in a factory function — see
+  `references/testing.md` for how to test infra.)
+- **Source-level Vitest tests** on every infra module — a lightweight,
+  house-style regression net asserting on the *source text* (resource names,
+  index shapes, IAM scopes). It's a deliberate choice, not an SST limit: Pulumi
+  *does* support runtime mocks (`@pulumi/pulumi/runtime`) for behavioral graph
+  tests when a module has real logic. Source assertions don't replace a
+  preview-deploy + smoke test. See `references/testing.md`.
+- **An observability gate**: every new Lambda/queue/schedule gets an alarm and
+  structured logging before merge. Whether you enforce this depends on the
+  project, but it's cheap insurance. See `references/deploy-and-troubleshoot.md`
+  § Observability.
+
+When you introduce a convention, say which bucket it's in ("this is universal"
+vs "matching this repo's house style") so the user can override the
+project-specific ones deliberately.
+
+## Working rhythm
+
+1. **Orient** (above) — map config, modules, tests, tooling.
+2. **Verify syntax** with Context7 / AWS docs MCP if anything is non-obvious.
+   Don't guess at a component's option name.
+3. **Author** the resource/module following `references/authoring.md`. Match the
+   surrounding file's commenting density and naming — these projects comment the
+   *why* heavily, and a terse one-liner in a heavily-annotated file reads as a
+   regression.
+4. **Test** — add or update source-level assertions (`references/testing.md`) and
+   run `npx vitest` (or the repo's `test` script). Run `npx sst diff` and/or
+   `tsc --noEmit` to catch type and plan errors before deploying.
+5. **Deploy/operate** per `references/deploy-and-troubleshoot.md`. Confirm the
+   target account with `aws sts get-caller-identity` before any `sst deploy`.
+6. **Clean up** any exported state files — they contain account IDs and ARNs and
+   must not linger in `/tmp` or chat history.
+
+## What good looks like
+
+- The change is the smallest diff that satisfies the requirement, in the right
+  `infra/` module, wired into `run()` in dependency order.
+- Every Lambda gets the right runtime via the global transform (you didn't
+  hand-set `runtime` unless intentionally diverging — e.g. a Python function).
+- Cross-resource references use `link:` (in-graph) and/or `$interpolate`-scoped
+  IAM; outputs other tools consume are published to SSM under the stage prefix.
+- New infra has a matching source-level test, and the existing suite stays green.
+- You confirmed AWS-side facts via the docs MCP and SST/Pulumi syntax via
+  Context7 rather than relying on recall.
+- Anything irreversible (deploy, `sst remove`, a resource-type migration) was
+  flagged to the user with the account it targets, and migrations were planned
+  as two PRs, not one.
+
+## Limitations
+
+- Use this skill only when the task clearly matches its upstream source and local project context.
+- Verify commands, generated code, dependencies, credentials, and external service behavior before applying changes.
+- Do not treat examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions.

package/bundled-skills/azure-ai-language-conversations-py/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: azure-ai-language-conversations-py
+description: Implement Conversational Language Understanding (CLU) using the azure-ai-language-conversations Python SDK. Use when working with ConversationAnalysisClient to analyze conversation intent and entities, building NLP features, or integrating language understanding into applications.
+risk: unknown
+source: https://github.com/microsoft/skills/tree/main/.github/plugins/azure-sdk-python/skills/azure-ai-language-conversations-py
+source_repo: microsoft/skills
+source_type: official
+date_added: 2026-07-01
+license: MIT
+license_source: https://github.com/microsoft/skills/blob/main/LICENSE
+---
+
+# Azure AI Language Conversations for Python
+## When to Use
+
+Use this skill when you need implement Conversational Language Understanding (CLU) using the azure-ai-language-conversations Python SDK. Use when working with ConversationAnalysisClient to analyze conversation intent and entities, building NLP features, or integrating language understanding into applications.
+
+
+## System Prompt
+You are an expert Python developer specializing in Azure AI Services and Natural Language Processing.
+Your task is to help users implement Conversational Language Understanding (CLU) using the `azure-ai-language-conversations` SDK.
+
+When responding to requests about Azure AI Language Conversations:
+1. Always use the latest version of the `azure-ai-language-conversations` SDK.
+2. Emphasize the use of `ConversationAnalysisClient` with `DefaultAzureCredential`.
+3. Provide clear code examples demonstrating how to structure the conversation payload.
+4. Handle exceptions properly.
+
+## Authentication & Lifecycle
+
+> **🔑 Two rules apply to every code sample below:**
+>
+> 1. **Prefer `DefaultAzureCredential`.** It works locally (Azure CLI / VS Code / Developer CLI) and in Azure (managed identity, workload identity) with no code change. Avoid connection strings, account/API keys — they bypass Entra audit and rotation.
+>    - Local dev: `DefaultAzureCredential` works as-is.
+>    - Production: set `AZURE_TOKEN_CREDENTIALS=prod` (or `AZURE_TOKEN_CREDENTIALS=<specific_credential>`) to constrain the credential chain to production-safe credentials.
+> 2. **Wrap every client in a context manager** so HTTP transports, sockets, and token caches are released deterministically:
+>    - Sync: `with <Client>(...) as client:`
+>    - Async: `async with <Client>(...) as client:` **and** `async with DefaultAzureCredential() as credential:` (from `azure.identity.aio`)
+>
+> Snippets may abbreviate this setup, but production code should always follow both rules.
+
+`ConversationAnalysisClient` accepts a `TokenCredential` such as `DefaultAzureCredential`. Use the token credential — it works locally (Azure CLI / VS Code / Developer CLI) and in Azure (managed identity, workload identity) with no code change.
+
+### Legacy: API Key (existing keyed deployments)
+
+New code should use `DefaultAzureCredential`. Use `AzureKeyCredential` only if you have an existing keyed deployment that hasn't been migrated to Entra ID yet — for example, regulated environments still completing their Entra rollout.
+
+```python
+import os
+from azure.core.credentials import AzureKeyCredential
+from azure.ai.language.conversations import ConversationAnalysisClient
+
+endpoint = os.environ["AZURE_CONVERSATIONS_ENDPOINT"]
+key = os.environ["AZURE_CONVERSATIONS_KEY"]
+
+with ConversationAnalysisClient(endpoint, AzureKeyCredential(key)) as client:
+    # See "Basic Conversation Analysis" below for the analyze_conversation payload
+    ...
+```
+
+## Best Practices
+- **Pick sync OR async and stay consistent.** Do not mix `azure.ai.language.conversations` sync clients with `azure.ai.language.conversations.aio` async clients in the same call path. Choose one mode per module.
+- **Always use context managers for clients and async credentials.** Wrap every client in `with ConversationAnalysisClient(...) as client:` (sync) or `async with ConversationAnalysisClient(...) as client:` (async). For async `DefaultAzureCredential` from `azure.identity.aio`, also use `async with credential:` so tokens and transports are cleaned up.
+- **Use `DefaultAzureCredential`** for portable auth across local dev and Azure (avoid API keys; they bypass Entra audit and rotation).
+- Use environment variables for the endpoint, project name, and deployment name.
+- Clearly map the `participantId` and `id` in the `conversationItem` payload.
+
+## Examples
+
+### Basic Conversation Analysis
+```python
+import os
+from azure.identity import DefaultAzureCredential
+from azure.ai.language.conversations import ConversationAnalysisClient
+
+endpoint = os.environ["AZURE_CONVERSATIONS_ENDPOINT"]
+project_name = os.environ["AZURE_CONVERSATIONS_PROJECT"]
+deployment_name = os.environ["AZURE_CONVERSATIONS_DEPLOYMENT"]
+
+# DefaultAzureCredential works locally and in Azure with no code change.
+credential = DefaultAzureCredential()
+
+with ConversationAnalysisClient(endpoint, credential) as client:
+    query = "Send an email to Carol about the tomorrow's meeting"
+    result = client.analyze_conversation(
+        task={
+            "kind": "Conversation",
+            "analysisInput": {
+                "conversationItem": {
+                    "participantId": "1",
+                    "id": "1",
+                    "modality": "text",
+                    "language": "en",
+                    "text": query
+                },
+                "isLoggingEnabled": False
+            },
+            "parameters": {
+                "projectName": project_name,
+                "deploymentName": deployment_name,
+                "verbose": True
+            }
+        }
+    )
+
+    print(f"Top intent: {result['result']['prediction']['topIntent']}")
+
+## Limitations
+
+- Use this skill only when the task clearly matches its upstream source and local project context.
+- Verify commands, generated code, dependencies, credentials, and external service behavior before applying changes.
+- Do not treat examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions.