# caira

Adopt this skill: https://proskills.md/skills/other/microsoft-caira-skills-caira

Page: https://proskills.md/skills/other/microsoft-caira-skills-caira
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/caira/SKILL.md
size: 4854
sha: 95d1c7c2c1ced059a1a434453df2ce367e92a4d9
upstream: https://github.com/microsoft/caira/blob/main/skills/caira/SKILL.md

```text
---
name: caira
description: Primary entrypoint for coding agents using CAIRA as reference material to design and build generative AI solutions with Azure AI Foundry, Azure OpenAI-compatible endpoints, agent frameworks, APIs, and frontends tailored to a user's scenario.
compatibility: Needs access to the github.com/microsoft/caira repository.
metadata:
  author: Microsoft
  version: "0.4.3"
---

# CAIRA

Use this skill when a user wants to build or extend a generative AI solution. CAIRA is a reference library, not an application generator: inspect the repository, select the smallest relevant reference components, and adapt them into the user's workspace.

## Intake before generating changes

Ask only what is needed to choose components:

1. What outcome is the user trying to build?
1. Do they already have Foundry/OpenAI endpoints, hosting, identity, observability, or frontend/API code?
1. What kind of networking isolation or security boundaries are needed?
1. Which programming languages or frameworks does the user prefer? If the user prefers something that's not directly in the CAIRA references, try to follow the same architectural patterns and design principles shown in the CAIRA reference components, but adapt them to the user's preferred languages or frameworks.
1. Which components are needed now: Foundry, Container Apps, API, frontend, or only app code? If the answer shows the user only needs one component, use only that component.

## Core rules

- Use the `reference-architectures` directory in the `github.com/microsoft/caira/` repository as the canonical source of truth. Inspect it either with the GitHub MCP server if available, through GitHub raw URLs, or clone the repository temporarily to inspect `reference-architectures/` locally.
- When reviewing the reference architectures, read the full code of the desired component. Do not limit the investigation to the README or docs. The source of truth is the code.
- Prefer small component references over full-stack copying.
- For scenarios that need OpenAI-compatible endpoints, prefer the Foundry IaC reference unless the user already has endpoints or asks for a different approach.
- Determine what the user already has before proposing new infrastructure.
- Always use managed identities or other passwordless identity patterns. NEVER USE API keys, static credentials, or secrets, unless the user explicitly asks for an API-key- or secret-based approach.
- When implementing IaC for Foundry, use the Azure Verified Module, as shown in the reference architectures. Don't use standalone Terraform resources related to Foundry unless explicitly requested.
- If an API that communicates with Foundry needs to be implemented, ALWAYS prefer using Foundry resources instead of Azure OpenAI resources, unless the user explicitly asks for Azure OpenAI. Even with the OpenAI Agents SDK.
- Before proposing repository security scans, check whether the target repository already uses or has configured Gitleaks, Trivy, or similar tools for secret, dependency, container, or IaC scanning. If similar scanning is missing, ask whether the user wants to add Gitleaks and/or Trivy scans before implementing them.
- Keep recommendations focused on the current reference components listed below.
- Explain which CAIRA paths influenced the recommendation or generated files.
- Always ask follow-up questions to narrow down the user's needs and avoid unnecessary copying of reference code.
- Before start implementing, confirm the user's scenario, needs, and which CAIRA reference components, configuration, networking, and security boundaries will be used.

## Current reference components

| Need | CAIRA reference path |
|------|----------------------|
| Foundry foundation | `reference-architectures/iac/foundry/` |
| Container Apps hosting for API + frontend | `reference-architectures/iac/container-apps/` |
| TypeScript API using OpenAI Agents SDK | `reference-architectures/app/api/typescript/openai-agents-sdk/` |
| TypeScript API using Foundry Agent Service | `reference-architectures/app/api/typescript/foundry-agent-service/` |
| C# API using Microsoft Agent Framework | `reference-architectures/app/api/csharp/microsoft-agent-framework/` |
| React frontend | `reference-architectures/app/frontend/typescript/react/` |
| Frontend/API contract | `reference-architectures/app/API_CONTRACT.md` |

## How to use CAIRA references

1. Inspect the relevant component source files.
1. Copy or adapt only the files needed for the user's stack.
1. Remove sample text, model names, env vars, or Terraform variables that do not apply to the user's scenario.
1. Preserve the component's validation style: npm scripts for TypeScript, .NET build for C#, Terraform validation for IaC, Docker builds for containers.
1. Mention the exact CAIRA paths used and what was intentionally left out.
```

## File: README.md
upstream: https://github.com/microsoft/caira/blob/main/README.md

````text
# CAIRA

CAIRA (Composable AI Reference Architectures) is a small reference library for agents building Azure AI solutions. The primary entrypoint is the CAIRA skill: install the skill, let your coding agent inspect this repository, and have it copy or adapt only the reference pieces that fit your scenario.

Each directory under `reference-architectures/` is an independent reference component that should be easy to read, validate, copy, and modify.

## Quickstart

Install the skill from your project directory:

```bash
bunx skills add github.com/microsoft/CAIRA/skills
```

or:

```bash
npx skills add github.com/microsoft/CAIRA/skills
```

Then ask your agent to use CAIRA for your scenario, for example:

```text
Create an agentic monitoring system to detect security-related issues in a configured GitHub repository using Foundry, an API, and a React frontend with a dashboard.
```

## Reference components

| Path | Purpose |
|------|---------|
| `reference-architectures/iac/foundry/` | Terraform for a Foundry account, project, and model deployment. |
| `reference-architectures/iac/container-apps/` | Terraform for Azure Container Apps hosting exactly two apps: API and frontend. |
| `reference-architectures/app/api/typescript/openai-agents-sdk/` | Agentic API reference for Typescript using the OpenAI Agents SDK. |
| `reference-architectures/app/api/typescript/foundry-agent-service/` | Agentic API reference for Typescript using Foundry Agent Service. |
| `reference-architectures/app/api/csharp/microsoft-agent-framework/` | Agentic API reference for C# and Microsoft Agent Framework. |
| `reference-architectures/app/frontend/typescript/react/` | Minimal React frontend with a small BFF proxy to the API. |

## Contributor workflow

Install dependencies and validate all reference components:

```bash
task bootstrap
task validate
```

Validation is intentionally component-local: TypeScript components use npm scripts, C# uses .NET build, Terraform uses `fmt/init/validate`, and each app container has a Dockerfile that can be built independently. You can also run pieces independently with `task security`, `task validate:code`, and `task validate:containers`. Dependency audits and Trivy scans are available separately with `task validate:audit`, `task security:trivy`, and `task validate:containers:trivy`.

The CAIRA skill test can be run locally with `task test:skill`. It installs the skill into a fresh empty workspace, runs the README example prompt through GitHub Copilot CLI in unattended mode, then asks Copilot to verify the generated result.

For the weekly GitHub Actions run, the workflow signs in to Azure with OIDC, gets a short-lived Azure AI Foundry token from the Azure CLI, and configures Copilot CLI BYOK provider environment variables (`COPILOT_PROVIDER_BASE_URL`, `COPILOT_PROVIDER_MODEL_ID`, and optionally `COPILOT_PROVIDER_WIRE_API`) for an OpenAI-compatible Foundry endpoint. The OIDC service principal should have the least-privilege **Cognitive Services OpenAI User** role at the Azure AI Foundry / Azure OpenAI resource that hosts the configured deployment.

## Developing CAIRA

For information related to developing CAIRA, start with the documentation in [`docs/`](docs/). It includes contributor guidance, local environment setup, troubleshooting notes, and the repository security posture.
````