===============
LIBRARY RULES
===============
From library maintainers:
- Load skills selectively - only those relevant to current task to avoid context rot
- Always use DefaultAzureCredential for Azure SDK authentication
- Search microsoft-docs MCP before implementing Azure SDK code
- Skills use progressive disclosure: metadata at startup, full instructions on activation

# Agent Skills

Agent Skills is a repository of 126 domain-specific skills, prompts, and MCP configurations designed for AI coding agents working with Azure SDKs and Microsoft AI Foundry services. Skills are folders containing instructions, scripts, and resources that agents can discover and use to perform tasks more accurately and efficiently. The repository provides knowledge packages for Python, .NET, TypeScript, and Java development with Azure services.

The project implements the Agent Skills open format with progressive disclosure: agents load only skill metadata (name, description) at startup, then read full instructions when a skill is activated. This keeps context efficient while providing deep domain expertise on demand. The repository includes a test harness for evaluating AI-generated code against acceptance criteria, using iterative improvement patterns (Ralph Loop) to achieve quality thresholds.

## Installing Skills

Install skills into your AI agent's configuration directory using the skills CLI.

```bash
# Interactive installation wizard
npx skills add microsoft/agent-skills

# Install specific skill via Context7
npx ctx7 skills install /microsoft/agent-skills azure-ai-projects-py

# Manual installation via git
git clone https://github.com/microsoft/agent-skills.git
cp -r agent-skills/.github/skills/azure-cosmos-db-py your-project/.github/skills/

# Symlink for multi-project setups
ln -s /path/to/agent-skills/.github/skills/mcp-builder /path/to/your-project/.github/skills/mcp-builder
```

## SKILL.md Format

Every skill requires a `SKILL.md` file with YAML frontmatter and Markdown instructions. The metadata triggers skill loading while the body is read on activation.

```markdown
---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF documents.
license: Apache-2.0
metadata:
  author: example-org
  version: "1.0"
---

# PDF Processing

## When to use this skill
Use this skill when the user needs to work with PDF files...

## How to extract text
1. Use pdfplumber for text extraction...
```

## Azure AI Projects Client Creation

Create an AIProjectClient with DefaultAzureCredential for production authentication patterns.

```python
import os
from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential

project_client = AIProjectClient(
    endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
    credential=DefaultAzureCredential(),
)

with project_client:
    # Use project_client for all operations
    connections = project_client.connections.list()
    for conn in connections:
        print(f"Connection: {conn.name}")
```

## Creating Versioned Agents

Create versioned agents using `create_version()` with PromptAgentDefinition for deployment management.

```python
import os
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import PromptAgentDefinition
from azure.identity import DefaultAzureCredential

project_client = AIProjectClient(
    endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
    credential=DefaultAzureCredential(),
)

with project_client:
    agent = project_client.agents.create_version(
        agent_name="customer-support-agent",
        definition=PromptAgentDefinition(
            model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
            instructions="You are a customer support specialist.",
            tools=[],
        ),
        version_label="v1.0",
        description="Initial version",
    )
    print(f"Agent: id={agent.id}, name={agent.name}, version={agent.version}")

    # Clean up
    project_client.agents.delete_agent(agent.id)
```

## Agent with Code Interpreter Tool

Create agents with CodeInterpreterTool for executing Python code with file uploads.

```python
import os
from azure.ai.projects import AIProjectClient
from azure.ai.agents.models import CodeInterpreterTool, FilePurpose
from azure.identity import DefaultAzureCredential

project_client = AIProjectClient(
    endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
    credential=DefaultAzureCredential(),
)

with project_client:
    # Upload file for code interpreter
    file = project_client.agents.files.upload_and_poll(
        file_path="data.csv",
        purpose=FilePurpose.AGENTS,
    )

    code_interpreter = CodeInterpreterTool()

    agent = project_client.agents.create_agent(
        model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
        name="data-analyst",
        instructions="Analyze data and create visualizations.",
        tools=code_interpreter.definitions,
        tool_resources={"code_interpreter": {"file_ids": [file.id]}},
    )

    print(f"Created agent with code interpreter: {agent.id}")
    project_client.agents.delete_agent(agent.id)
```

## Agent with File Search and Vector Store

Create RAG-enabled agents using FileSearchTool with vector stores for document retrieval.

```python
import os
from azure.ai.projects import AIProjectClient
from azure.ai.agents.models import FileSearchTool, FilePurpose
from azure.identity import DefaultAzureCredential

project_client = AIProjectClient(
    endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
    credential=DefaultAzureCredential(),
)

with project_client:
    # Upload document
    file = project_client.agents.files.upload_and_poll(
        file_path="./data/product_info.md",
        purpose=FilePurpose.AGENTS,
    )

    # Create vector store
    vector_store = project_client.agents.vector_stores.create_and_poll(
        file_ids=[file.id],
        name="product-docs",
    )

    # Create file search tool
    file_search = FileSearchTool(vector_store_ids=[vector_store.id])

    agent = project_client.agents.create_agent(
        model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
        name="search-agent",
        instructions="Search uploaded files to answer questions.",
        tools=file_search.definitions,
        tool_resources=file_search.resources,
    )

    print(f"Created RAG agent: {agent.id}")
    project_client.agents.delete_agent(agent.id)
```

## Thread/Message/Run Conversation Flow

Complete conversation workflow: create thread, add messages, run agent, retrieve responses.

```python
import os
from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential

project_client = AIProjectClient(
    endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
    credential=DefaultAzureCredential(),
)

with project_client:
    # Create agent
    agent = project_client.agents.create_agent(
        model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
        name="conversation-agent",
        instructions="You are a helpful assistant.",
    )

    # Create thread
    thread = project_client.agents.threads.create()
    print(f"Created thread: {thread.id}")

    # Add user message
    message = project_client.agents.messages.create(
        thread_id=thread.id,
        role="user",
        content="What is the capital of Japan?",
    )

    # Run agent
    run = project_client.agents.runs.create_and_process(
        thread_id=thread.id,
        agent_id=agent.id,
    )
    print(f"Run finished with status: {run.status}")

    # Get response
    if run.status == "completed":
        messages = project_client.agents.messages.list(thread_id=thread.id)
        for msg in messages:
            if msg.role == "assistant":
                for content in msg.content:
                    if hasattr(content, 'text'):
                        print(f"Assistant: {content.text.value}")
    elif run.status == "failed":
        print(f"Run failed: {run.last_error}")

    project_client.agents.delete_agent(agent.id)
```

## Streaming with AgentEventHandler

Implement streaming responses using AgentEventHandler for real-time text output.

```python
import os
from azure.ai.projects import AIProjectClient
from azure.ai.agents.models import AgentEventHandler
from azure.identity import DefaultAzureCredential

class MyHandler(AgentEventHandler):
    def on_message_delta(self, delta):
        if delta.text:
            print(delta.text.value, end="", flush=True)

    def on_error(self, data):
        print(f"Error: {data}")

project_client = AIProjectClient(
    endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
    credential=DefaultAzureCredential(),
)

with project_client:
    agent = project_client.agents.create_agent(
        model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
        name="streaming-agent",
        instructions="You are a helpful assistant.",
    )

    thread = project_client.agents.threads.create()

    project_client.agents.messages.create(
        thread_id=thread.id,
        role="user",
        content="Tell me a story.",
    )

    with project_client.agents.runs.stream(
        thread_id=thread.id,
        agent_id=agent.id,
        event_handler=MyHandler(),
    ) as stream:
        stream.until_done()

    project_client.agents.delete_agent(agent.id)
```

## Async Operations Pattern

Use async clients for concurrent Azure AI operations with proper context management.

```python
import os
import asyncio
from azure.ai.projects.aio import AIProjectClient
from azure.ai.agents.aio import AsyncAgentEventHandler
from azure.identity.aio import DefaultAzureCredential

class AsyncHandler(AsyncAgentEventHandler):
    async def on_message_delta(self, delta):
        if delta.text:
            print(delta.text.value, end="", flush=True)

    async def on_error(self, data):
        print(f"Error: {data}")

async def main():
    async with (
        DefaultAzureCredential() as credential,
        AIProjectClient(
            endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
            credential=credential,
        ) as client,
    ):
        # Create agent
        agent = await client.agents.create_agent(
            model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
            name="async-agent",
            instructions="You are a helpful assistant.",
        )

        # Create thread
        thread = await client.agents.threads.create()

        # Add message
        await client.agents.messages.create(
            thread_id=thread.id,
            role="user",
            content="Tell me a short story.",
        )

        # Stream response
        async with client.agents.runs.stream(
            thread_id=thread.id,
            agent_id=agent.id,
            event_handler=AsyncHandler(),
        ) as stream:
            await stream.until_done()

        await client.agents.delete_agent(agent.id)

asyncio.run(main())
```

## Running the Test Harness

The test harness validates AI-generated code against acceptance criteria using the GitHub Copilot SDK.

```bash
# Install test dependencies
cd tests
pnpm install

# List available skills with test coverage
pnpm harness --list

# Run tests for a specific skill (mock mode for CI)
pnpm harness azure-ai-projects-py --mock --verbose

# Run with Ralph Loop (iterative improvement)
pnpm harness azure-ai-projects-py --ralph --mock --max-iterations 5 --threshold 85

# Run all skills
pnpm harness --all --mock --output json --output-file results.json

# Run unit tests
pnpm test
```

## SkillEvaluationRunner API

The runner coordinates loading scenarios, generating code via Copilot, and evaluating against acceptance criteria.

```typescript
import { SkillEvaluationRunner } from "./harness/index.js";

// Create runner with options
const runner = new SkillEvaluationRunner({
  basePath: "/path/to/repo",
  useMock: true,  // Use mock responses instead of real Copilot SDK
  verbose: true,
});

// List available skills
const skills = runner.listAvailableSkills();
console.log(`Available skills: ${skills.join(", ")}`);

// Run evaluation for a single skill
const summary = await runner.run("azure-ai-projects-py", "basic");
console.log(`Passed: ${summary.passed}/${summary.totalScenarios}`);
console.log(`Average Score: ${summary.avgScore}`);

// Run with Ralph Loop for iterative improvement
const ralphSummary = await runner.runWithLoop("azure-ai-projects-py", undefined, {
  maxIterations: 5,
  qualityThreshold: 85,
});
console.log(`Converged: ${ralphSummary.scenariosConverged}/${ralphSummary.scenariosRun}`);
console.log(`Final Score: ${ralphSummary.avgFinalScore}`);
```

## RalphLoopController API

The Ralph Loop iteratively improves code generation until quality thresholds are met.

```typescript
import {
  RalphLoopController,
  createRalphConfig,
  CodeEvaluator,
  AcceptanceCriteriaLoader,
  SkillCopilotClient,
} from "./harness/index.js";

// Load acceptance criteria for a skill
const criteriaLoader = new AcceptanceCriteriaLoader("/path/to/repo");
const criteria = criteriaLoader.load("azure-ai-projects-py");

// Create evaluator and client
const evaluator = new CodeEvaluator(criteria);
const client = new SkillCopilotClient("/path/to/repo", true); // mock mode

// Configure Ralph Loop
const config = createRalphConfig({
  maxIterations: 5,
  qualityThreshold: 80,
  improvementThreshold: 5,
  earlyStopOnPerfect: true,
  includeFeedback: true,
});

// Create controller and run
const controller = new RalphLoopController(criteria, evaluator, client, config);
const result = await controller.run(
  "Create an AIProjectClient with DefaultAzureCredential",
  "client_creation"
);

console.log(`Final Score: ${result.finalScore}`);
console.log(`Converged: ${result.converged}`);
console.log(`Stop Reason: ${result.stopReason}`);
console.log(`Iterations: ${result.iterations.length}`);
console.log(`Improvement: ${result.improvement} points`);
```

## Test Scenario Configuration

Define test scenarios in YAML for skill evaluation with expected/forbidden patterns.

```yaml
# tests/scenarios/azure-ai-projects-py/scenarios.yaml
config:
  model: gpt-4
  max_tokens: 2000
  temperature: 0.3

scenarios:
  - name: client_creation
    prompt: |
      Create an AIProjectClient with proper authentication using DefaultAzureCredential.
      Use environment variables for the endpoint and include a context manager pattern.
    expected_patterns:
      - "from azure.ai.projects import AIProjectClient"
      - "from azure.identity import DefaultAzureCredential"
      - "DefaultAzureCredential()"
      - "endpoint="
      - "credential="
      - "with project_client:"
    forbidden_patterns:
      - "from azure.ai.projects.models import AIProjectClient"  # Wrong location
      - "url="  # Wrong parameter name
    tags:
      - basic
      - authentication
      - client
    mock_response: |
      import os
      from azure.ai.projects import AIProjectClient
      from azure.identity import DefaultAzureCredential

      project_client = AIProjectClient(
          endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
          credential=DefaultAzureCredential(),
      )

      with project_client:
          connections = project_client.connections.list()
```

## MCP Server Configuration

Configure Model Context Protocol servers in `.vscode/mcp.json` for enhanced agent capabilities.

```json
{
  "servers": {
    "microsoft-docs": {
      "url": "https://learn.microsoft.com/api/mcp",
      "type": "http"
    },
    "context7": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp@latest"]
    },
    "github": {
      "url": "https://api.githubcopilot.com/mcp/",
      "type": "http"
    },
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"],
      "type": "stdio"
    },
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"],
      "env": {
        "MEMORY_FILE_PATH": "${input:memory_file_path}"
      },
      "type": "stdio"
    }
  }
}
```

## Scaffold Foundry Application

Use the scaffold-foundry-app prompt to generate full-stack Azure AI Foundry applications.

```bash
# Use with GitHub Copilot Chat
@workspace /scaffold-foundry-app Create a chat application with Azure OpenAI

# The scaffolder creates:
# - Frontend: Vite + React + TypeScript + Fluent UI v9 dark theme + Framer Motion
# - Backend: FastAPI + Pydantic v2 + pytest + Ruff
# - Infrastructure: azd + Bicep for Azure Container Apps with remoteBuild
```

Generated project structure:
```
my-foundry-app/
├── azure.yaml                    # azd config with remoteBuild: true
├── .env.example                  # Foundry setup instructions
├── infra/
│   ├── main.bicep
│   └── modules/
│       ├── container-apps-environment.bicep
│       └── container-app.bicep
├── src/
│   ├── frontend/
│   │   ├── package.json
│   │   ├── vite.config.ts
│   │   └── src/
│   │       ├── App.tsx
│   │       └── theme/dark-theme.ts
│   └── backend/
│       ├── pyproject.toml
│       ├── app/main.py
│       └── tests/test_health.py
└── .github/workflows/ci.yaml
```

## Summary

Agent Skills provides a comprehensive system for extending AI coding agents with domain-specific knowledge about Azure SDKs and Microsoft AI Foundry. The primary use cases include: building agents with tools (code interpreter, file search, Bing grounding, Azure AI Search), managing versioned agent deployments, implementing streaming conversations, and scaffolding full-stack Azure applications. The test harness enables quality assurance through acceptance criteria validation and iterative improvement loops.

Integration patterns follow progressive disclosure: skills are discovered at agent startup via metadata, activated when tasks match descriptions, and executed with full instructions and bundled resources. The repository supports multiple AI agents (GitHub Copilot, Claude Code, Cursor, OpenCode) through the open Agent Skills format. Skills use selective loading to avoid context rot, and MCP servers provide additional capabilities like documentation search, browser automation, and persistent memory across sessions.