Agent Skills

https://github.com/microsoft/skills
Admin
130 skills for AI coding agents working with Azure SDKs and Microsoft AI Foundry. Python, .NET,...
Tokens:64,826
Snippets:551
Trust Score:10
License:MIT
Update:6 days ago
Show doc for...
Tokens:
Raw
================
LIBRARY RULES
================
- 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

================
CODE SNIPPETS
================
### Verify Setup Commands

Source: https://github.com/microsoft/skills/blob/main/.github/agents/scaffolder.agent.md

Commands to install dependencies and start the frontend and backend dev servers, then verify the health endpoint. Frontend should start on :5173, backend on :8000.

```bash
# Frontend
cd src/frontend
pnpm install
pnpm dev        # Should start on :5173

# Backend
cd src/backend
uv sync
uv run fastapi dev app/main.py  # Should start on :8000

# Verify health endpoint
curl http://localhost:8000/api/health
```

--------------------------------

### Preview Wiki Locally

Source: https://github.com/microsoft/skills/blob/main/.github/plugins/deep-wiki/commands/crisp.md

Optional command to install dependencies and start the local development server for the wiki.

```bash
cd wiki && npm install && npm run dev
```

--------------------------------

### Local Development Startup

Source: https://github.com/microsoft/skills/blob/main/.github/prompts/scaffold-foundry-app.prompt.md

Commands to start the backend and frontend services for local development.

```bash
# Backend
cd src/backend
uv sync
uv run fastapi dev app/main.py

# Frontend (new terminal)
cd src/frontend
pnpm install
pnpm dev
```

--------------------------------

### Manual Skill Installation

Source: https://github.com/microsoft/skills/blob/main/.github/docs/agent-integration.md

Commands for manually copying or symlinking skills into a project.

```bash
# Copy specific skills
cp -r agent-skills/.github/skills/azure-cosmos-db-py your-project/.github/skills/

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

--------------------------------

### Install Skills via npx

Source: https://github.com/microsoft/skills/blob/main/.github/docs/agent-integration.md

Recommended command to add skills using the interactive wizard.

```bash
npx skills add microsoft/agent-skills
# Select skills from interactive wizard
```

--------------------------------

### Copilot Instructions Configuration

Source: https://github.com/microsoft/skills/blob/main/.github/docs/agent-integration.md

Example of referencing available skills within the .github/copilot-instructions.md file.

```markdown
## Available Skills

For Azure Cosmos DB work, load the `azure-cosmos-db-py` skill.
For FastAPI endpoints, load the `fastapi-router-py` skill.
```

--------------------------------

### Build the Wiki

Source: https://github.com/microsoft/skills/blob/main/.github/plugins/deep-wiki/commands/build.md

Commands to install dependencies and build the wiki project. The output is generated in the wiki/.vitepress/dist/ directory.

```bash
cd wiki && npm install && npm run build
```

--------------------------------

### Update workflow to use npm install

Source: https://github.com/microsoft/skills/blob/main/.github/plugins/deep-wiki/commands/crisp.md

Configure the GitHub Actions workflow to use npm install instead of npm ci for crisp wiki deployments.

```yaml
      - name: Install dependencies
        run: npm install
        working-directory: wiki
```

--------------------------------

### Selective Skill Loading Workflow

Source: https://github.com/microsoft/skills/blob/main/.github/docs/agent-integration.md

Example of the recommended workflow for agents to selectively load skills based on the user request domain.

```text
User request: "Add a blob storage endpoint"

Agent should:
1. Identify task domain: Azure Storage + API endpoint
2. Load ONLY: azure-storage-blob-py, fastapi-router-py
3. Ignore: azure-cosmos-db-py, react-flow-node-ts, etc.
```

--------------------------------

### SKILL.md file format

Source: https://github.com/microsoft/skills/blob/main/.github/docs/skills.md

An example of the SKILL.md file, which requires YAML frontmatter for name and description followed by Markdown instructions.

```mdx
---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents.
---

# 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...

## How to fill forms
...
```

--------------------------------

### Development Commands

Source: https://github.com/microsoft/skills/blob/main/.github/agents/frontend.agent.md

Lists the pnpm commands for the frontend: starting the dev server, linting with max-warnings 0, building for production with type check, and running Vitest tests.

```bash
cd src/frontend
pnpm dev      # Start dev server
pnpm lint     # Lint (max-warnings 0)
pnpm build    # Production build + type check
pnpm test     # Run Vitest tests
```

--------------------------------

### Skill Metadata YAML Frontmatter

Source: https://github.com/microsoft/skills/blob/main/.github/docs/agent-integration.md

Example of the YAML frontmatter parsed by agents for each discovered skill.

```yaml
---
name: azure-cosmos-db-py
description: Build Azure Cosmos DB NoSQL services with Python/FastAPI following production-grade patterns.
---
```

--------------------------------

### Tool-Based Agent Skill Loading

Source: https://github.com/microsoft/skills/blob/main/.github/docs/agent-integration.md

Example of how agents without direct filesystem access load skills using dedicated tools.

```python
# Agent calls a skill-loading tool
result = load_skill("azure-cosmos-db-py")
```

--------------------------------

### Check MCP server version

Source: https://github.com/microsoft/skills/blob/main/.github/docs/mcp-usage.md

Verify that the @anthropic/microsoft-docs-mcp package is installed by checking its version.

```bash
npx -y @anthropic/microsoft-docs-mcp --version
```

--------------------------------

### Filesystem-based Agent Skill Loading

Source: https://github.com/microsoft/skills/blob/main/.github/docs/agent-integration.md

Example of how filesystem-based agents like Claude Code or Copilot CLI load skills via shell commands.

```bash
cat /path/to/skills/azure-cosmos-db-py/SKILL.md
```

--------------------------------

### Repository Source Resolution Commands

Source: https://github.com/microsoft/skills/blob/main/.github/plugins/deep-wiki/commands/catalogue.md

Commands to identify the repository origin and branch before starting the analysis.

```bash
git remote get-url origin
```

```bash
git rev-parse --abbrev-ref HEAD
```

--------------------------------

### Usage in Components

Source: https://github.com/microsoft/skills/blob/main/.github/prompts/create-store.prompt.md

Example of how to consume the store within a React component using selectors to prevent unnecessary re-renders.

```typescript
import { use${STORE_NAME.charAt(0).toUpperCase() + STORE_NAME.slice(1)}Store } from '@/store';

function MyComponent() {
  // Select specific state (prevents unnecessary re-renders)
  const value = use${STORE_NAME.charAt(0).toUpperCase() + STORE_NAME.slice(1)}Store((state) => state.value);
  const action = use${STORE_NAME.charAt(0).toUpperCase() + STORE_NAME.slice(1)}Store((state) => state.action);
  
  // Or use multiple selectors
  const { value, action } = use${STORE_NAME.charAt(0).toUpperCase() + STORE_NAME.slice(1)}Store((state) => ({
    value: state.value,
    action: state.action,
  }));
  
  return <button onClick={() => action(newValue)}>Update</button>;
}
```

--------------------------------

### Implement custom Mermaid diagram zoom overlay

Source: https://github.com/microsoft/skills/blob/main/.github/plugins/deep-wiki/commands/build.md

A complete setup for VitePress theme index.ts that handles both standard image zoom and a custom modal overlay for Mermaid SVGs. This implementation includes polling for async-rendered diagrams and manual zoom controls.

```typescript
// In setup() within enhanceApp or theme index.ts
import { onMounted, watch, nextTick } from 'vue'
import { useRoute } from 'vitepress'
import DefaultTheme from 'vitepress/theme'
import mediumZoom from 'medium-zoom'
import './custom.css'

export default {
  extends: DefaultTheme,
  setup() {
    const route = useRoute()

    const initZoom = () => {
      // Image zoom
      mediumZoom('.vp-doc img:not(.no-zoom)', {
        background: 'rgba(0, 0, 0, 0.92)',
      })

      // Mermaid diagram zoom — poll for async-rendered SVGs
      const attachMermaidZoom = (retries = 0) => {
        const diagrams = document.querySelectorAll('.mermaid')
        if (diagrams.length === 0 && retries < 20) {
          setTimeout(() => attachMermaidZoom(retries + 1), 500)
          return
        }

        diagrams.forEach((container) => {
          // Skip if already has zoom handler
          if (container.getAttribute('data-zoom-attached')) return
          container.setAttribute('data-zoom-attached', 'true')
          container.style.cursor = 'pointer'

          container.addEventListener('click', () => {
            const svg = container.querySelector('svg')
            if (!svg) return
            openDiagramModal(svg)
          })
        })
      }
      attachMermaidZoom()
    }

    const openDiagramModal = (svg: SVGSVGElement) => {
      // Create overlay
      const overlay = document.createElement('div')
      overlay.className = 'diagram-zoom-overlay'

      // Create container with controls
      const wrapper = document.createElement('div')
      wrapper.className = 'diagram-zoom-wrapper'

      // Controls bar
      const controls = document.createElement('div')
      controls.className = 'diagram-zoom-controls'
      controls.innerHTML = `
        <button class="zoom-btn" data-action="zoom-in" title="Zoom in (+)">+</button>
        <button class="zoom-btn" data-action="zoom-out" title="Zoom out (-)">−</button>
        <button class="zoom-btn" data-action="zoom-reset" title="Reset (0)">Reset</button>
        <button class="zoom-btn zoom-close" data-action="close" title="Close (Esc)">✕</button>
      `

      // Clone SVG into scrollable content area
      const content = document.createElement('div')
      content.className = 'diagram-zoom-content'
      const cloned = svg.cloneNode(true) as SVGSVGElement

      // Fix viewBox if missing
      if (!cloned.getAttribute('viewBox')) {
        const bbox = svg.getBBox()
        cloned.setAttribute('viewBox', `${bbox.x} ${bbox.y} ${bbox.width} ${bbox.height}`)
      }
      cloned.style.width = '100%'
      cloned.style.height = 'auto'
      cloned.style.maxHeight = 'none'

      content.appendChild(cloned)
      wrapper.appendChild(controls)
      wrapper.appendChild(content)
      overlay.appendChild(wrapper)
      document.body.appendChild(overlay)
      document.body.style.overflow = 'hidden'

      // Zoom state
      let scale = 1
      let translateX = 0
      let translateY = 0
      const applyTransform = () => {
        content.style.transform = `translate(${translateX}px, ${translateY}px) scale(${scale})`
      }

      // Control buttons
      controls.addEventListener('click', (e) => {
        const action = (e.target as HTMLElement).closest('[data-action]')?.getAttribute('data-action')
        if (action === 'zoom-in') { scale = Math.min(scale * 1.3, 5); applyTransform() }
        if (action === 'zoom-out') { scale = Math.max(scale / 1.3, 0.2); applyTransform() }
        if (action === 'zoom-reset') { scale = 1; translateX = 0; translateY = 0; applyTransform() }
        if (action === 'close') closeOverlay()
      })

      // Scroll wheel zoom
      overlay.addEventListener('wheel', (e) => {
        e.preventDefault()
        const delta = e.deltaY > 0 ? 0.9 : 1.1
        scale = Math.min(Math.max(scale * delta, 0.2), 5)
        applyTransform()
      }, { passive: false })
```

--------------------------------

### Parameterized Database Queries

Source: https://github.com/microsoft/skills/blob/main/.github/docs/pattern-enforcement.md

Always use parameterized queries to prevent SQL injection risks. The example shows the correct approach using parameters versus the incorrect approach using f-strings.

```python
# CORRECT
query = "SELECT * FROM c WHERE c.id = @id"
params = [{"name": "@id", "value": user_id}]

# WRONG - SQL injection risk
query = f"SELECT * FROM c WHERE c.id = '{user_id}'"
```

--------------------------------

### Project Lifecycle and Deployment Commands

Source: https://github.com/microsoft/skills/blob/main/.github/agents/scaffolder.agent.md

Commands for initializing a project, setting up frontend and backend environments, running tests, and deploying to Azure.

```bash
# Initialize new project
mkdir ${PROJECT_NAME} && cd ${PROJECT_NAME}

# Frontend setup
cd src/frontend
pnpm install
pnpm dev

# Backend setup
cd src/backend
uv sync
uv run fastapi dev app/main.py

# Run tests
uv run pytest

# Azure deployment
azd auth login
azd up

# Deploy changes only
azd deploy
```

--------------------------------

### Initialize FastAPI main.py

Source: https://github.com/microsoft/skills/blob/main/.github/prompts/scaffold-foundry-app.prompt.md

Sets up the FastAPI application instance with CORS middleware and lifespan management.

```python
from contextlib import asynccontextmanager

from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

from app.config import settings
from app.routers import health


@asynccontextmanager
async def lifespan(app: FastAPI):
    # Startup
    yield
    # Shutdown


app = FastAPI(
    title="${PROJECT_NAME}",
    description="${PROJECT_DESCRIPTION}",
    version="0.1.0",
    lifespan=lifespan,
)

app.add_middleware(
    CORSMiddleware,
    allow_origins=[settings.frontend_url],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

app.include_router(health.router)
```

--------------------------------

### Enforce DefaultAzureCredential in Python

Source: https://github.com/microsoft/skills/blob/main/.github/docs/pattern-enforcement.md

Example of using DefaultAzureCredential with the CosmosClient to avoid hardcoded credentials.

```python
from azure.identity import DefaultAzureCredential
from azure.cosmos import CosmosClient

credential = DefaultAzureCredential()
client = CosmosClient(url=endpoint, credential=credential)
```

--------------------------------

### Environment Configuration

Source: https://github.com/microsoft/skills/blob/main/.github/prompts/scaffold-foundry-app.prompt.md

Commands to initialize the environment configuration file.

```bash
# Copy environment template
cp .env.example .env

# Edit .env with your Foundry project endpoint
# Get this from https://ai.azure.com > Project Settings
```

--------------------------------

### Environment Variable Template (.env.example)

Source: https://github.com/microsoft/skills/blob/main/.github/prompts/scaffold-foundry-app.prompt.md

Template for required Azure AI Foundry project configuration and local development settings.

```bash
# ===========================================
# Azure AI Foundry Configuration
# ===========================================
# Get these values from https://ai.azure.com
#
# 1. Go to ai.azure.com and sign in
# 2. Create or select a project
# 3. Go to Project Settings > Overview
# 4. Copy the endpoint URL
# ===========================================

# Required: Your Foundry project endpoint
# Format: https://<resource>.services.ai.azure.com/api/projects/<project>
AZURE_AI_PROJECT_ENDPOINT=

# Required: Model deployment name (e.g., gpt-4o-mini, gpt-4o)
AZURE_AI_MODEL_DEPLOYMENT_NAME=gpt-4o-mini

# ===========================================
# Local Development
# ===========================================
ENVIRONMENT=development
PORT=8000

# Frontend URL (for CORS)
FRONTEND_URL=http://localhost:5173
```

--------------------------------

### Cosmos DB Document Structure

Source: https://github.com/microsoft/skills/blob/main/.github/agents/infrastructure.agent.md

Example JSON structure for documents stored in Cosmos DB.

```json
{
  "id": "unique-id",
  "doc_type": "project",  // Partition key filter
  "workspaceId": "ws-123",
  // ... entity fields
}
```

--------------------------------

### Computed Values Pattern

Source: https://github.com/microsoft/skills/blob/main/.github/prompts/create-store.prompt.md

Pattern for deriving values from the current state using the get() function.

```typescript
// Use get() to access current state
getFilteredItems: () => {
  const { items, filter } = get();
  return items.filter(item => item.matches(filter));
},
```

--------------------------------

### Application Entry Point (main.tsx)

Source: https://github.com/microsoft/skills/blob/main/.github/prompts/scaffold-foundry-app.prompt.md

Initializes the React application with the Fluent UI provider and custom dark theme.

```tsx
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import { FluentProvider } from "@fluentui/react-components";
import { darkTheme } from "./theme/dark-theme";
import App from "./App";
import "./index.css";

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <FluentProvider theme={darkTheme}>
      <App />
    </FluentProvider>
  </StrictMode>
);
```

--------------------------------

### Frontend Development Tasks

Source: https://github.com/microsoft/skills/blob/main/.github/prompts/scaffold-foundry-app.prompt.md

Common commands for linting and building the frontend code.

```bash
cd src/frontend
pnpm lint                        # Lint
pnpm build                       # Build
```

--------------------------------

### Define API Response Format Pattern

Source: https://github.com/microsoft/skills/blob/main/.github/docs/pattern-enforcement.md

Example of a custom team convention enforcing a specific API response structure.

```python
{
    "data": <result>,
    "meta": {
        "request_id": str,
        "timestamp": str
    }
}
```

--------------------------------

### Troubleshooting Deployment Commands

Source: https://github.com/microsoft/skills/blob/main/.github/agents/infrastructure.agent.md

CLI commands for viewing container logs, checking Cosmos DB status, and monitoring deployment progress.

```bash
# View Container App logs
az containerapp logs show -n <app-name> -g <resource-group>

# Check Cosmos DB
az cosmosdb show -n <account-name> -g <resource-group>

# View deployment status
azd status
```

--------------------------------

### HTML entry point in src/frontend/index.html

Source: https://github.com/microsoft/skills/blob/main/.github/prompts/scaffold-foundry-app.prompt.md

The main HTML file for the application, including meta tags for SEO and mobile configuration.

```html
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
    
    <!-- Favicons -->
    <link rel="icon" href="/favicon.ico" sizes="32x32" />
    <link rel="icon" href="/favicon.svg" type="image/svg+xml" />
    <link rel="apple-touch-icon" href="/apple-touch-icon.png" />
    <link rel="manifest" href="/site.webmanifest" />
    
    <!-- Theme color for mobile browser chrome -->
    <meta name="theme-color" content="#0a0a0a" />
    
    <!-- Open Graph -->
    <meta property="og:type" content="website" />
    <meta property="og:title" content="${PROJECT_NAME}" />
    <meta property="og:description" content="${PROJECT_DESCRIPTION}" />
    
    <!-- Twitter Card -->
    <meta name="twitter:card" content="summary_large_image" />
    
    <title>${PROJECT_NAME}</title>
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="/src/main.tsx"></script>
  </body>
</html>
```

--------------------------------

### Backend Development Tasks

Source: https://github.com/microsoft/skills/blob/main/.github/prompts/scaffold-foundry-app.prompt.md

Common commands for testing, linting, and formatting the backend code.

```bash
cd src/backend
uv run pytest                    # Run tests
uv run ruff check . --fix        # Lint
uv run ruff format .             # Format
```

--------------------------------

### Backend development commands

Source: https://github.com/microsoft/skills/blob/main/.github/agents/backend.agent.md

Common commands for managing dependencies, running the development server, type checking, and executing tests.

```bash
cd src/backend
uv sync                              # Install dependencies
uv run fastapi dev app/main.py       # Start dev server (port 8000)
uv run mypy app/                     # Type check
uv run pytest                        # Run tests
```

--------------------------------

### Azure Deployment Management

Source: https://github.com/microsoft/skills/blob/main/.github/prompts/scaffold-foundry-app.prompt.md

Commands for managing the deployment lifecycle on Azure.

```bash
azd up        # Full deployment
azd deploy    # Deploy app changes only
azd down      # Tear down resources
```

--------------------------------

### Inject available skills XML into system prompt

Source: https://github.com/microsoft/skills/blob/main/.github/docs/skills.md

XML format recommended for Claude models to include skill metadata in the system prompt. For filesystem-based agents, include the location field with the absolute path to the SKILL.md file; for tool-based agents, the location can be omitted. Each skill should add roughly 50-100 tokens to the context.

```xml
<available_skills>
  <skill>
    <name>pdf-processing</name>
    <description>Extracts text and tables from PDF files, fills forms, merges documents.</description>
    <location>/path/to/skills/pdf-processing/SKILL.md</location>
  </skill>
  <skill>
    <name>data-analysis</name>
    <description>Analyzes datasets, generates charts, and creates summary reports.</description>
    <location>/path/to/skills/data-analysis/SKILL.md</location>
  </skill>
</available_skills>
```

--------------------------------

### MCP and Skills Integration Workflow

Source: https://github.com/microsoft/skills/blob/main/.github/docs/mcp-usage.md

Comparison of development approaches, highlighting the recommended combination of MCP for current information and skills for proven patterns.

```text
# BAD: Skill only (may use outdated API)
Load azure-cosmos-db-py → Implement

# BAD: MCP only (no patterns, reinventing wheel)
Search docs → Implement from scratch

# GOOD: MCP + Skill
Search docs (current API) → Load skill (patterns) → Implement
```

--------------------------------

### Generate available_skills XML with skills-ref to-prompt

Source: https://github.com/microsoft/skills/blob/main/.github/docs/skills.md

CLI command from the skills-ref reference library to generate the <available_skills> XML for agent prompts.

```bash
skills-ref to-prompt <path>...
```

--------------------------------

### Azure Deployment Commands

Source: https://github.com/microsoft/skills/blob/main/.github/prompts/scaffold-foundry-app.prompt.md

Commands to authenticate and deploy the application to Azure.

```bash
# Login
az login
azd auth login

# Deploy
azd up
```

--------------------------------

### Mounting a new router in main.py

Source: https://github.com/microsoft/skills/blob/main/.github/agents/backend.agent.md

Register a new router in the main application file to expose the API endpoints.

```python
from app.routers.my_router import router as my_router
app.include_router(my_router)
```

--------------------------------

### Parse SKILL.md frontmatter metadata (pseudocode)

Source: https://github.com/microsoft/skills/blob/main/.github/docs/skills.md

Pseudocode for parsing the frontmatter of a SKILL.md file at startup to extract the skill's name, description, and path. This keeps initial context usage low by only parsing the frontmatter.

```pseudocode
function parseMetadata(skillPath):
    content = readFile(skillPath + "/SKILL.md")
    frontmatter = extractYAMLFrontmatter(content)

    return {
        name: frontmatter.name,
        description: frontmatter.description,
        path: skillPath
    }
```

--------------------------------

### Create Service Class

Source: https://github.com/microsoft/skills/blob/main/.github/prompts/add-endpoint.prompt.md

Implement the service logic in src/backend/app/services/${RESOURCE_NAME}_service.py to handle database interactions.

```python
from typing import Optional
from app.db.cosmos import get_container, query_documents, upsert_document
from app.models.${RESOURCE_NAME} import ${RESOURCE_NAME.title()}, ${RESOURCE_NAME.title()}Create

class ${RESOURCE_NAME.title()}Service:
    def _use_cosmos(self) -> bool:
        return get_container() is not None
    
    async def get_${RESOURCE_NAME}_by_id(
        self, ${RESOURCE_NAME}_id: str
    ) -> Optional[${RESOURCE_NAME.title()}]:
        if self._use_cosmos():
            docs = await query_documents(
                doc_type="${RESOURCE_NAME}",
                extra_filter="AND c.id = @id",
                parameters=[{"name": "@id", "value": ${RESOURCE_NAME}_id}],
            )
            return self._doc_to_${RESOURCE_NAME}(docs[0]) if docs else None
        return None
    
    async def create_${RESOURCE_NAME}(
        self, data: ${RESOURCE_NAME.title()}Create, user_id: str
    ) -> ${RESOURCE_NAME.title()}:
        # Implementation
        pass
    
    def _doc_to_${RESOURCE_NAME}(self, doc: dict) -> ${RESOURCE_NAME.title()}:
        return ${RESOURCE_NAME.title()}(**doc)
```

--------------------------------

### .gitignore Configuration

Source: https://github.com/microsoft/skills/blob/main/.github/plugins/deep-wiki/commands/build.md

Standard ignore file for the wiki project to exclude build artifacts and dependencies.

```text
node_modules/
.vitepress/cache/
.vitepress/dist/
```

--------------------------------

### Configure Parameters in infra/main.parameters.json

Source: https://github.com/microsoft/skills/blob/main/.github/prompts/scaffold-foundry-app.prompt.md

The parameter file used to inject environment-specific values into the main Bicep template.

```json
{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "environmentName": {
      "value": "${AZURE_ENV_NAME}"
    },
    "location": {
      "value": "${AZURE_LOCATION}"
    }
  }
}
```

--------------------------------

### Commit and Push Generated Wiki

Source: https://github.com/microsoft/skills/blob/main/.github/plugins/deep-wiki/commands/crisp.md

Commands to stage and push the generated wiki files to the repository.

```bash
git add wiki/ .github/workflows/ llms.txt AGENTS.md CLAUDE.md
git commit -m "docs: add crisp wiki with VitePress site"
git push
```

--------------------------------

### Pre-Commit Configuration

Source: https://github.com/microsoft/skills/blob/main/.github/docs/pattern-enforcement.md

Automate verification using pre-commit hooks for type checking and linting.

```yaml
# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: type-check
        name: Type checking
        entry: mypy src/
        language: system
        
      - id: lint
        name: Linting
        entry: ruff check src/
        language: system
```

--------------------------------

### Create Store File

Source: https://github.com/microsoft/skills/blob/main/.github/prompts/create-store.prompt.md

Template for creating a new store file at src/frontend/src/store/${STORE_NAME}-store.ts using the subscribeWithSelector middleware.

```typescript
import { create } from 'zustand';
import { subscribeWithSelector } from 'zustand/middleware';

// State interface
export interface ${STORE_NAME.charAt(0).toUpperCase() + STORE_NAME.slice(1)}State {
  // Add ${STATE_FIELDS}
  isLoading: boolean;
  error: string | null;
}

// Actions interface
export interface ${STORE_NAME.charAt(0).toUpperCase() + STORE_NAME.slice(1)}Actions {
  // Add ${ACTIONS}
  setLoading: (loading: boolean) => void;
  setError: (error: string | null) => void;
  reset: () => void;
}

// Combined store type
export type ${STORE_NAME.charAt(0).toUpperCase() + STORE_NAME.slice(1)}Store = 
  ${STORE_NAME.charAt(0).toUpperCase() + STORE_NAME.slice(1)}State & 
  ${STORE_NAME.charAt(0).toUpperCase() + STORE_NAME.slice(1)}Actions;

// Initial state
const initialState: ${STORE_NAME.charAt(0).toUpperCase() + STORE_NAME.slice(1)}State = {
  // Initialize ${STATE_FIELDS}
  isLoading: false,
  error: null,
};

// Create store with subscribeWithSelector
export const use${STORE_NAME.charAt(0).toUpperCase() + STORE_NAME.slice(1)}Store = create<${STORE_NAME.charAt(0).toUpperCase() + STORE_NAME.slice(1)}Store>()(
  subscribeWithSelector((set, get) => ({
    ...initialState,
    
    // Add action implementations
    
    setLoading: (loading) => set({ isLoading: loading }),
    
    setError: (error) => set({ error }),
    
    reset: () => set(initialState),
  }))
);
```

--------------------------------

### Check for existing deployment workflows

Source: https://github.com/microsoft/skills/blob/main/.github/plugins/deep-wiki/commands/crisp.md

Use these commands to verify if a deployment workflow already exists before creating a new one.

```bash
ls .github/workflows/deploy-wiki.yml 2>/dev/null
grep -rl "deploy-pages\|pages-artifact" .github/workflows/ 2>/dev/null
```

--------------------------------

### Configure MCP servers in .vscode/mcp.json

Source: https://github.com/microsoft/skills/blob/main/.github/docs/mcp-usage.md

Defines the configuration structure for MCP servers, including type, command, arguments, and environment variables.

```json
{
  "servers": {
    "microsoft-docs": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@anthropic/microsoft-docs-mcp"]
    },
    "context7": {
      "type": "stdio", 
      "command": "npx",
      "args": ["-y", "@anthropic/context7-mcp"]
    },
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@anthropic/github-mcp"],
      "env": {
        "GITHUB_TOKEN": "${env:GITHUB_TOKEN}"
      }
    }
  }
}
```

--------------------------------

### Check environment variables

Source: https://github.com/microsoft/skills/blob/main/.github/docs/mcp-usage.md

Ensure required environment variables like GITHUB_TOKEN are set for specific MCP servers.

```text
GITHUB_TOKEN
```

--------------------------------

### Create Dockerfile

Source: https://github.com/microsoft/skills/blob/main/.github/prompts/scaffold-foundry-app.prompt.md

Defines the container image build process for the backend application.

```dockerfile
FROM python:3.11-slim

WORKDIR /app

RUN pip install --no-cache-dir uv

COPY pyproject.toml ./
RUN uv pip install --system -e .

COPY . .

EXPOSE 8000

CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
```

--------------------------------

### Global styles in src/frontend/src/index.css

Source: https://github.com/microsoft/skills/blob/main/.github/prompts/scaffold-foundry-app.prompt.md

Global CSS file importing Tailwind directives and setting root styles.

```css
@tailwind base;
@tailwind components;
@tailwind utilities;

:root {
  font-family: system-ui, -apple-system, sans-serif;
  line-height: 1.5;
  font-weight: 400;
  color-scheme: dark;
}

body {
  margin: 0;
  min-height: 100vh;
}
```

--------------------------------

### Implement Zoom and Pan Functionality

Source: https://github.com/microsoft/skills/blob/main/.github/plugins/deep-wiki/commands/build.md

Handles mouse dragging for panning, keyboard shortcuts for zooming, and backdrop clicks to close the overlay. Uses onMounted and route watchers to ensure DOM availability.

```javascript
// Pan with mouse drag
      let isPanning = false
      let startX = 0, startY = 0
      content.addEventListener('mousedown', (e) => {
        isPanning = true; startX = e.clientX - translateX; startY = e.clientY - translateY
        content.style.cursor = 'grabbing'
      })
      document.addEventListener('mousemove', (e) => {
        if (!isPanning) return
        translateX = e.clientX - startX; translateY = e.clientY - startY
        applyTransform()
      })
      document.addEventListener('mouseup', () => {
        isPanning = false; content.style.cursor = 'grab'
      })

      // Keyboard shortcuts
      const keyHandler = (e: KeyboardEvent) => {
        if (e.key === 'Escape') closeOverlay()
        if (e.key === '+' || e.key === '=') { scale = Math.min(scale * 1.3, 5); applyTransform() }
        if (e.key === '-') { scale = Math.max(scale / 1.3, 0.2); applyTransform() }
        if (e.key === '0') { scale = 1; translateX = 0; translateY = 0; applyTransform() }
      }
      document.addEventListener('keydown', keyHandler)

      // Backdrop click to close
      overlay.addEventListener('click', (e) => {
        if (e.target === overlay) closeOverlay()
      })

      const closeOverlay = () => {
        document.removeEventListener('keydown', keyHandler)
        document.body.style.overflow = ''
        overlay.remove()
      }
    }

    onMounted(() => initZoom())
    watch(() => route.path, () => nextTick(() => initZoom()))
  },
}
```

--------------------------------

### Frontend Package Configuration (package.json)

Source: https://github.com/microsoft/skills/blob/main/.github/prompts/scaffold-foundry-app.prompt.md

Frontend dependencies and scripts for the React application.

```json
{
  "name": "${PROJECT_NAME}-frontend",
  "private": true,
  "version": "0.1.0",
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "tsc && vite build",
    "lint": "eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0",
    "preview": "vite preview"
  },
  "dependencies": {
    "@fluentui/react-components": "^9.54.0",
    "@fluentui/react-icons": "^2.0.245",
    "framer-motion": "^11.0.0",
    "react": "^18.2.0",
    "react-dom": "^18.2.0"
  },
  "devDependencies": {
    "@types/react": "^18.2.0",
    "@types/react-dom": "^18.2.0",
    "@typescript-eslint/eslint-plugin": "^7.0.0",
    "@typescript-eslint/parser": "^7.0.0",
    "@vitejs/plugin-react": "^4.2.0",
    "autoprefixer": "^10.4.0",
    "eslint": "^8.57.0",
    "eslint-plugin-react-hooks": "^4.6.0",
    "eslint-plugin-react-refresh": "^0.4.0",
    "postcss": "^8.4.0",
    "tailwindcss": "^3.4.0",
    "typescript": "^5.3.0",
    "vite": "^5.1.0"
  }
}
```

--------------------------------

### package.json Configuration

Source: https://github.com/microsoft/skills/blob/main/.github/plugins/deep-wiki/commands/build.md

The package.json file defining dependencies for VitePress, Mermaid, and medium-zoom.

```json
{
  "name": "wiki",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "scripts": {
    "dev": "vitepress dev",
    "build": "vitepress build",
    "preview": "vitepress preview"
  },
  "devDependencies": {
    "medium-zoom": "^1.1.0",
    "mermaid": "^11.12.2",
    "vitepress": "^1.6.4",
    "vitepress-plugin-mermaid": "^2.0.17"
  }
}
```

--------------------------------

### Configure pyproject.toml

Source: https://github.com/microsoft/skills/blob/main/.github/prompts/scaffold-foundry-app.prompt.md

Defines project metadata, dependencies, and development tools for the backend.

```toml
[project]
name = "${PROJECT_NAME}-backend"
version = "0.1.0"
description = "${PROJECT_DESCRIPTION}"
requires-python = ">=3.11"
dependencies = [
    "fastapi>=0.109.0",
    "uvicorn[standard]>=0.27.0",
    "pydantic>=2.6.0",
    "pydantic-settings>=2.1.0",
    "azure-identity>=1.15.0",
    "azure-ai-projects>=1.0.0b1",
]

[project.optional-dependencies]
dev = [
    "pytest>=8.0.0",
    "pytest-asyncio>=0.23.0",
    "pytest-cov>=4.1.0",
    "httpx>=0.27.0",
    "ruff>=0.3.0",
]

[tool.ruff]
target-version = "py311"
line-length = 88

[tool.ruff.lint]
select = ["E", "F", "I", "UP", "B", "SIM"]

[tool.pytest.ini_options]
asyncio_mode = "auto"
testpaths = ["tests"]
```

--------------------------------

### Commit Deployment Files

Source: https://github.com/microsoft/skills/blob/main/.github/plugins/deep-wiki/commands/deploy.md

Stage and commit the generated workflow and lock files to your repository.

```bash
git add .github/workflows/deploy-wiki.yml wiki/package-lock.json
git commit -m "ci: add GitHub Pages deployment for wiki"
git push
```

--------------------------------

### Scan Wiki Directory for Incompatibilities

Source: https://github.com/microsoft/skills/blob/main/.github/plugins/deep-wiki/commands/ado.md

Use these bash commands to identify Mermaid blocks, flowchart keywords, HTML breaks, front matter, relative links, and VitePress containers within the wiki source directory.

```bash
# Count mermaid code fence blocks
grep -rc '```mermaid' --include="*.md" wiki/ | grep -v ':0$'

# Find flowchart keyword usage
grep -rn '^\s*flowchart ' --include="*.md" wiki/

# Find <br> tags in mermaid labels  
grep -rn '<br>' --include="*.md" wiki/ | head -20

# Count YAML front matter files
for f in $(find wiki/ -name "*.md"); do
  head -1 "$f" | grep -q '^---$' && echo "FRONT MATTER: $f"
done

# Find parent-relative links
grep -rn '](\.\./' --include="*.md" wiki/ | wc -l

# Find VitePress container directives
grep -rn '^:::' --include="*.md" wiki/ | grep -v mermaid
```

--------------------------------

### Web manifest in src/frontend/public/site.webmanifest

Source: https://github.com/microsoft/skills/blob/main/.github/prompts/scaffold-foundry-app.prompt.md

JSON manifest file for PWA capabilities.

```json
{
  "name": "${PROJECT_NAME}",
  "short_name": "${PROJECT_NAME}",
  "icons": [
    { "src": "/favicon.ico", "sizes": "32x32", "type": "image/x-icon" },
    { "src": "/apple-touch-icon.png", "sizes": "180x180", "type": "image/png" }
  ],
  "theme_color": "#0a0a0a",
  "background_color": "#0a0a0a",
  "display": "standalone"
}
```

--------------------------------

### GitHub Actions workflow for VitePress deployment

Source: https://github.com/microsoft/skills/blob/main/.github/plugins/deep-wiki/commands/deploy.md

The configuration file for .github/workflows/deploy-wiki.yml, which handles building and deploying the VitePress site to GitHub Pages.

```yaml
name: Deploy Wiki to GitHub Pages

on:
  push:
    branches: [main]
    paths:
      - 'wiki/**'
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
          cache-dependency-path: wiki/package-lock.json

      - name: Setup Pages
        uses: actions/configure-pages@v5

      - name: Install dependencies
        run: npm ci
        working-directory: wiki

      - name: Build with VitePress
        run: npm run build
        working-directory: wiki

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: wiki/.vitepress/dist

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    needs: build
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4
```

--------------------------------

### Generate package-lock.json

Source: https://github.com/microsoft/skills/blob/main/.github/plugins/deep-wiki/commands/deploy.md

Run this command within the wiki directory to generate the lock file required for CI deployments.

```bash
cd wiki && npm install
```

--------------------------------

### Docker configuration in src/frontend/Dockerfile

Source: https://github.com/microsoft/skills/blob/main/.github/prompts/scaffold-foundry-app.prompt.md

Multi-stage Dockerfile to build the frontend and serve it with Nginx.

```dockerfile
FROM node:20-alpine AS builder
WORKDIR /app
RUN corepack enable && corepack prepare pnpm@latest --activate
COPY package.json pnpm-lock.yaml ./
RUN pnpm install --frozen-lockfile
COPY . .
RUN pnpm build

FROM nginx:alpine
COPY --from=builder /app/dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/conf.d/default.conf
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]
```

--------------------------------

### Mount Router in main.py

Source: https://github.com/microsoft/skills/blob/main/.github/prompts/add-endpoint.prompt.md

Register the new resource router in the main application file located at src/backend/app/main.py.

```python
from app.routers.${RESOURCE_PLURAL} import router as ${RESOURCE_PLURAL}_router
app.include_router(${RESOURCE_PLURAL}_router)
```

--------------------------------

### Verify MCP configuration file

Source: https://github.com/microsoft/skills/blob/main/.github/docs/mcp-usage.md

The configuration for the MCP server is located in the .vscode/mcp.json file.

```json
.vscode/mcp.json
```

--------------------------------

### Project Structure Overview

Source: https://github.com/microsoft/skills/blob/main/.github/prompts/scaffold-foundry-app.prompt.md

Visual representation of the project directory layout.

```text
├── azure.yaml              # azd configuration
├── infra/                  # Bicep infrastructure
├── src/
│   ├── frontend/           # React + Fluent UI + Vite
│   └── backend/            # FastAPI + Pydantic
└── .github/workflows/      # CI/CD
```

--------------------------------

### Project Directory Structure

Source: https://github.com/microsoft/skills/blob/main/.github/agents/scaffolder.agent.md

Shows the complete directory layout for the scaffolded project, including azd config, frontend and backend source files, infrastructure Bicep templates, and CI/CD workflow.

```plaintext
${PROJECT_NAME}/
├── azure.yaml                    # azd config
├── .env.example                  # Foundry setup instructions
├── README.md                     # Setup guide
├── .pre-commit-config.yaml
├── .gitignore
├── infra/
│   ├── main.bicep
│   ├── main.parameters.json
│   └── modules/
│       ├── container-apps-environment.bicep
│       └── container-app.bicep
├── src/
│   ├── frontend/
│   │   ├── package.json
│   │   ├── vite.config.ts
│   │   ├── tailwind.config.js
│   │   ├── postcss.config.js
│   │   ├── tsconfig.json
│   │   ├── Dockerfile
│   │   └── src/
│   │       ├── App.tsx
│   │       ├── main.tsx
│   │       ├── index.css
│   │       ├── theme/
│   │       │   ├── brand.ts
│   │       │   └── dark-theme.ts
│   │       └── components/
│   │           └── Layout.tsx
│   └── backend/
│       ├── pyproject.toml
│       ├── Dockerfile
│       ├── app/
│       │   ├── __init__.py
│       │   ├── main.py
│       │   ├── config.py
│       │   ├── routers/
│       │   │   ├── __init__.py
│       │   │   └── health.py
│       │   ├── models/
│       │   │   └── __init__.py
│       │   └── services/
│       │       └── __init__.py
│       └── tests/
│           ├── __init__.py
│           └── test_health.py
└── .github/
    └── workflows/
        └── ci.yaml
```

--------------------------------

### Scan Repository Structure

Source: https://github.com/microsoft/skills/blob/main/.github/plugins/deep-wiki/commands/crisp.md

Perform a single-pass scan to identify key configuration and source files within the repository.

```bash
find . -maxdepth 3 -type f \( -name "*.md" -o -name "package.json" -o -name "pyproject.toml" -o -name "Cargo.toml" -o -name "*.csproj" -o -name "go.mod" -o -name "Dockerfile" -o -name "*.yml" -o -name "*.yaml" \) | head -50
```

--------------------------------

### Azure Deployment CLI Commands

Source: https://github.com/microsoft/skills/blob/main/.github/agents/infrastructure.agent.md

Standard Azure Developer CLI (azd) commands for authentication, deployment, and resource cleanup.

```bash
azd auth login        # Authenticate
azd up                # Deploy everything
azd deploy            # Deploy app changes only
azd down              # Tear down resources
```

--------------------------------

### Pre-commit Configuration (.pre-commit-config.yaml)

Source: https://github.com/microsoft/skills/blob/main/.github/prompts/scaffold-foundry-app.prompt.md

Configures pre-commit hooks for linting, formatting, and local ESLint execution.

```yaml
repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.5.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-yaml
      - id: check-added-large-files

  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.3.0
    hooks:
      - id: ruff
        args: [--fix]
      - id: ruff-format

  - repo: local
    hooks:
      - id: eslint
        name: eslint
        entry: pnpm --filter frontend lint
        language: system
        files: \.(ts|tsx)$
        pass_filenames: false
```

--------------------------------

### Configure VitePress Base Path

Source: https://github.com/microsoft/skills/blob/main/.github/plugins/deep-wiki/commands/deploy.md

Add the base path to your wiki/.vitepress/config.mts if your site is hosted as a project site.

```typescript
export default defineConfig({
  base: '/{repo-name}/',
  // ... rest of config
})
```

--------------------------------

### Implement API Service Functions

Source: https://github.com/microsoft/skills/blob/main/.github/prompts/add-endpoint.prompt.md

Create API client functions in src/frontend/src/services/api.ts to handle fetching and creating resources.

```typescript
export async function get${RESOURCE_NAME.title()}(id: string): Promise<${RESOURCE_NAME.title()}> {
  return authFetch(`/api/${RESOURCE_PLURAL}/${id}`);
}

export async function create${RESOURCE_NAME.title()}(data: ${RESOURCE_NAME.title()}Create): Promise<${RESOURCE_NAME.title()}> {
  return authFetch('/api/${RESOURCE_PLURAL}', {
    method: 'POST',
    body: JSON.stringify(data),
  });
}
```

--------------------------------

### Define Container Apps Environment Module

Source: https://github.com/microsoft/skills/blob/main/.github/prompts/scaffold-foundry-app.prompt.md

Infrastructure module for creating a managed environment with Log Analytics integration.

```bicep
param name string
param location string = resourceGroup().location
param tags object = {}

resource logAnalytics 'Microsoft.OperationalInsights/workspaces@2022-10-01' = {
  name: '${name}-logs'
  location: location
  tags: tags
  properties: {
    sku: { name: 'PerGB2018' }
    retentionInDays: 30
  }
}

resource containerAppsEnvironment 'Microsoft.App/managedEnvironments@2023-05-01' = {
  name: name
  location: location
  tags: tags
  properties: {
    appLogsConfiguration: {
      destination: 'log-analytics'
      logAnalyticsConfiguration: {
        customerId: logAnalytics.properties.customerId
        sharedKey: logAnalytics.listKeys().primarySharedKey
      }
    }
  }
}

output name string = containerAppsEnvironment.name
output id string = containerAppsEnvironment.id
```

--------------------------------

### Presenter Component Directory Structure

Source: https://github.com/microsoft/skills/blob/main/.github/agents/presenter.agent.md

The file structure for the presenter mode components within the project.

```text
components/presenter/
├── PresenterView.tsx       # Main presenter container
├── PresenterSidebar.tsx    # Navigation sidebar with groups/nodes
├── PresenterSlide.tsx      # Single node display
├── PresenterControls.tsx   # Playback controls
├── Teleprompter.tsx        # Script display
└── index.ts               # Barrel export
```

--------------------------------

### PostCSS configuration in src/frontend/postcss.config.js

Source: https://github.com/microsoft/skills/blob/main/.github/prompts/scaffold-foundry-app.prompt.md

PostCSS configuration enabling Tailwind and Autoprefixer.

```javascript
export default {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
};
```

--------------------------------

### Validate a skill directory with skills-ref

Source: https://github.com/microsoft/skills/blob/main/.github/docs/skills.md

CLI command from the skills-ref reference library to validate a skill directory.

```bash
skills-ref validate <path>
```
Tokens:
Raw