# 🧠 Awesome GBB Skills
> A curated collection of agentic Skills by **AI Global Black Belts** at Microsoft.
[](#skills-catalog)
[](LICENSE)
---
## Contents
- [What Are Skills?](#what-are-skills)
- [Featured Pipeline: Threadlight](#-featured-pipeline-threadlight) _(moved to [threadlight-skills](https://github.com/aiappsgbb/threadlight-skills))_
- [Featured Workspace: Zava](https://github.com/aiappsgbb/zava-constellation)
- [Demo Guide](DEMOS.md)
- [Supported Coding Runtimes](#supported-coding-runtimes)
- [Skills Catalog](#skills-catalog)
- [🏗️ Foundry Building Blocks](#️-foundry-building-blocks)
- [🛠️ Cross-Cutting Helpers](#️-cross-cutting-helpers)
- [🛡️ Governance](#️-governance)
- [📊 Content Generation](#-content-generation)
- [🧬 Org Composition](#-org-composition)
- [🔍 Discovery](#-discovery)
- [How to Use](#how-to-use)
- [Repository Structure](#repository-structure)
- [Contributing](#contributing)
---
## What Are Skills?
Skills are reusable, composable building blocks for AI agents. Each Skill encodes domain expertise as a structured markdown file (`SKILL.md`) that any compatible agentic coding runtime can load and execute.
These are **developer-oriented skills** — they help you build, deploy, and ship faster. A skill tells the agent **what to do**, **when to activate**, and **how to do it** — step by step.
---
## 🧵 Featured Pipeline: Threadlight
> **Threadlight has moved to its own repo →
> [aiappsgbb/threadlight-skills](https://github.com/aiappsgbb/threadlight-skills)**
>
> Eight `threadlight-*` skills that take a customer from a one-paragraph brief
> through spec → local test → deploy → safe-check gate → demo. See the
> [live experience page](https://aiappsgbb.github.io/threadlight-skills/).
>
> Install alongside awesome-gbb for the full pipeline:
> ```bash
> copilot plugin marketplace add aiappsgbb/threadlight-skills
> copilot plugin install threadlight-skills@threadlight-skills
> ```
---
## 🏙️ Featured Workspace: Zava
> **Zava has moved to its own repo →
> [aiappsgbb/zava-constellation](https://github.com/aiappsgbb/zava-constellation)**
>
> Three skills (`research-company` → `compose-org` → `zava-workspace-deploy`)
> that take a company name and produce a deployed, branded digital-clone
> workspace on Azure. See the
> [live experience page](https://aiappsgbb.github.io/zava-constellation/).
>
> **Zava + Threadlight = full story.** Threadlight (in
> [threadlight-skills](https://github.com/aiappsgbb/threadlight-skills))
> designs and deploys individual business-process agents. Zava wraps them in a
> multi-domain control plane with fleet orchestration and a polished dashboard.
---
## Supported Coding Runtimes
Skills are agnostic Markdown contracts — they load in any runtime that understands the `SKILL.md` shape. The runtime capabilities below are not a live-validation claim for unreleased entries; see the [AgentOps validation status](docs/maintenance/foundry-agentops-validation.md).
| Runtime | Shell + package installs | Long-running processes | Best for |
|---|---|---|---|
| **GitHub Copilot CLI** (`gh copilot`) | ✅ Full | ✅ | **Primary target**. Supports end-to-end execution; validation is per skill. |
| **GitHub Copilot App** ([`github/app`](https://github.com/github/app)) | ✅ Full | ✅ | **Desktop GUI built on the CLI** — inherits skills, MCP servers, plugins, hooks. Best for users who prefer a click-installer (DMG/EXE/AppImage) over `npm install -g`. Public preview. |
| **GitHub Copilot Coding Agent** (cloud) | ✅ Full | ✅ | All skills, hands-off cloud runs. |
| **Cursor** | ✅ Full | ✅ | All skills (load via project `.cursorrules` shim). |
| **VS Code GitHub Copilot Chat** | ✅ Full | ✅ | All skills (terminal-attached). Agent-mode also supports the agent-plugin bundle format (preview). |
| **Claude Code** (`clawpilot`) | ✅ Full | ✅ | All skills. Native plugin format (`.claude-plugin/plugin.json`) is auto-detected by VS Code and Copilot too. |
| **Microsoft Copilot Cowork** | ❌ Restricted | ❌ | Spec / pitch / config-gen skills only — see callout below. |
> [!IMPORTANT]
> **Microsoft Copilot Cowork compatibility caveat.** Cowork is the recommended
> seller surface for `threadlight-design` (it shines at structured-document
> generation), but its sandbox **does not allow `pip`/`npm`/`uv` installs,
> cannot shell out to `azd`/`az`/`docker`/`gh`, and cannot run long-lived
> processes**. As a rule of thumb, only a handful of skills are Cowork-friendly:
>
> - **`threadlight-design`** — the seller pitch + spec generator (its primary home).
> - **`ip-catalog`** — read-only MCP discovery of the GBB IP catalog.
> - **`gbb-pptx`** — content planning and editorial review work on accessible
> text; PPTX generation also requires `python-pptx` in the Cowork Python sandbox.
> - **`html-presentation`** — lean 20-file upload supports local HTML authoring
> when Python/filesystem access is available. Browser verification and Microsoft
> research still need the relevant tools; unavailable checks are disclosed.
> - **`gbb-humanizer`** — pure prose-polish pass over `overview.html`,
> prep-guide, demo script, or speaker notes (text-only, no shell needed).
>
> Everything else in this catalog assumes a real shell. Skills that deploy,
> build containers, run evals against a live model, render videos, or run a
> local FastMCP **will not work in Cowork** — use Copilot CLI, Coding Agent,
> Cursor, VS Code Copilot Chat, or Claude Code instead. They may still
> **author** their artifacts in Cowork (markdown / Bicep / Dockerfile is text),
> but the `azd up` / build / eval step needs a real shell. Plan workshops
> accordingly.
---
## Skills Catalog
> **Memory has moved to the official workflow.** Catalog 5.0.0 removes the
> duplicate `foundry-memory` skill. Use the Memory reference inside Microsoft's
> `microsoft-foundry` skill; there is no separate official `foundry-memory`
> entrypoint in the reviewed Azure Skills bundle.
> See [migration and local installation](docs/maintenance/foundry-memory-retirement.md).
> This changes coding guidance only, not existing memory stores, application
> dependencies, Threadlight deployment contracts, or Azure resources.
> [!IMPORTANT]
> **Merged source, not production readiness.** `foundry-agentops` 1.0.0 merged
> in [#484](https://github.com/aiappsgbb/awesome-gbb/pull/484) at
> `2db28d1f52bf288f2d0fd40b7c8beb913ceeee09` and is available in the main-branch
> catalog source. Separate release approval remains **unreleased / release PENDING**.
> The exact `96b30384` candidate's [targeted CI run](https://github.com/aiappsgbb/awesome-gbb/actions/runs/34001218180)
> completed the technical negative-path smoke, not full-matrix or readiness acceptance.
> Historical **corrected-source manual execution PASS**;
> **quality FAIL (4/5 thresholds)**; **Doctor readiness BLOCKED**.
> See the [sanitized validation record](docs/maintenance/foundry-agentops-validation.md)
> for manual evidence as of 2026-09-05, before PR CI, and its limits.
> Neither source availability nor a green technical smoke overrides these gates.
> **Unreleased addition, proposed catalog 4.32.0:** `foundry-mcp-auth` has live
> single-user delegated evidence for Prompt/direct-MCP, Prompt/Toolbox and
> Hosted/Toolbox. Hosted/direct, multi-user isolation and lifecycle cases are not certified.
> Deployment/Entra/connection writes require separate approval. See its
> [acceptance status](docs/maintenance/foundry-mcp-auth-validation.md).
### 🏗️ Foundry Building Blocks
Reference patterns for Microsoft Foundry agents (prompt and hosted), memory, MCP servers, evals, RAG, vision/speech, and observability.
| Skill | Description |
|-------|-------------|
| [**foundry-prompt-agents**](skills/foundry-prompt-agents/) | Create declarative Foundry agents — model + instructions + tools, no containers, no custom code. `PromptAgentDefinition`, tool wiring (web search, code interpreter, file search, MCP, OpenAPI), versioning, structured inputs, agent applications |
| [**foundry-voice-live**](skills/foundry-voice-live/) | Build real-time voice agents with Azure Voice Live (GA 2026-04-10) through a four-rung migration from Azure OpenAI Realtime to the native Voice Live SDK. Covers semantic VAD, echo cancellation, Neural HD voices, Foundry agent routing, benchmark patterns, and the FastRTC 0.0.34 plus Gradio 5.50 compatibility boundary |
| [**foundry-voice-agents**](skills/foundry-voice-agents/) | Managed prompt Voice Agent candidate (public preview): synthetic audio turns, greeting, local function tools, barge-in and consented readback/deletion. Separate Projects 2.7 environment. Manual functionality and service correlation passed; metadata-only tracing failed, so automation refuses configured tracing. Not the Voice Live API migration path. See the [validation record](docs/maintenance/foundry-voice-agents-validation.md). |
| [**foundry-hosted-agents**](skills/foundry-hosted-agents/) | GA container-deploy hosted agents via unified `azure.yaml` + `azd` — `Agent` + `FoundryChatClient` + `ResponsesHostServer`, implicit-access identity model (no default role grant), MCP wiring, **`SkillsProvider` progressive skill loading**, stable `update_details` rollout, and an opt-in [private no-tools BASIC consumer](skills/foundry-hosted-agents/references/private-basic.md) with ACR-connection validation and native readback (fresh live acceptance pending). |
| [agent-framework-harness](skills/agent-framework-harness/) | Build MAF `create_harness_agent` runtimes with accurate defaults, compaction, plan/execute modes, recovery, bounded loops, and Hosted Agents adapter wiring |
| [**foundry-routines**](skills/foundry-routines/) | Automate existing agents with the GA Routines service while preserving its beta SDK/client boundaries. Covers isolated creator-identity configuration, real timer versus manual dispatch, run correlation and downstream result checks; delegated consent and external event prerequisites remain separate. |
| [**foundry-teams-bot**](skills/foundry-teams-bot/) | Connect a hosted agent to Microsoft Teams + M365 Copilot (CEA manifest 1.21) — bot code, Bicep, Teams manifest, UAMI auth, ACA deployment |
| [**ghcp-hosted-agents**](skills/ghcp-hosted-agents/) | Deploy Foundry hosted agents using GitHub Copilot SDK (GHCP) — BYOK auth, Invocations protocol, SSE streaming, long-running tool loops |
| [**foundry-mcp-aca**](skills/foundry-mcp-aca/) | Deploy custom MCP servers as ACA / Azure Functions — Cosmos MCPToolKit, Playwright MCP, mock MCP, **validate-or-reject** evidence enforcement |
| [**foundry-mcp-aca-jobs**](skills/foundry-mcp-aca-jobs/) | Expose durable MCP tools backed by pre-provisioned ACA Jobs — SEP-2663 Tasks, immediate fallback tools, Cosmos idempotency, managed-identity callbacks, and one immutable image with separate server/worker entrypoints. |
| [**foundry-mcp-auth**](skills/foundry-mcp-auth/) | **Unreleased candidate:** custom Entra OAuth recipe, strict resource-server policy and safe user receipts. Three of four paths verified for one user; see [validation notes](docs/maintenance/foundry-mcp-auth-validation.md) for evidence and remaining gates. |
| [**foundry-evals**](skills/foundry-evals/) | Evaluate agents through supported agent-target runs or an explicit invoke+score fallback with real captured responses. Includes bounded polling, per-item scores, configurable judges and corrected citation URL checks, while preserving enriched tool transcripts and the last-run/EVAL-201 integration. |
| [**foundry-agentops**](skills/foundry-agentops/) | Adopt native Azure AgentOps **0.14.0** for one existing agent — skill **1.0.0** (merged source; readiness not certified). Review Doctor diagnostics, release evidence, regression baselines, and workflow ownership; its owner-authorized encrypted Doctor diagnostic is not full-matrix acceptance and never uploads raw output or an operator private key. |
| [**foundry-iq**](skills/foundry-iq/) | Enterprise RAG with Foundry IQ — Azure AI Search Knowledge Bases, agentic retrieval, multi-hop reasoning, citation-backed responses, **hosted-agent runtime identity callout** + **7-item bootstrap hardening checklist** (no-`az rest`-uploads, fail-fast, key sanitization, 32k-byte chunking, RBAC propagation wait, post-upload count verify, idempotent recovery) |
| [**foundry-doc-vision-speech**](skills/foundry-doc-vision-speech/) | Wire vision (gpt-5.4 family), Document Intelligence v4, and Azure Speech (STT/TTS) into a hosted agent — MCP and native Toolbox patterns + RBAC matrix |
| [**foundry-observability**](skills/foundry-observability/) | End-to-end App Insights + Log Analytics + OpenTelemetry across hosted agents, MCP servers, ACA jobs, bot, workspace — **closes the silent-telemetry gap** where `azd up` returns 0 but AppIn stays empty |
| [**foundry-cross-resource**](skills/foundry-cross-resource/) | Cross-resource model invocation via AI Gateway (APIM) — use models from another Foundry resource or a shared pool |
| [**foundry-vnet-deploy**](skills/foundry-vnet-deploy/) | Deploy Foundry with **Agent Setup inside a private VNet** — preserves the vendored templates, fixed-timestamp retry and optional Citadel peering/APIM DNS modules. Adds ownership-aware intake and read-only account/PE/subnet inventory, keeping management-plane observations separate from private runtime connectivity and gating recovery writes explicitly. |
| [**foundry-toolbox**](skills/foundry-toolbox/) | Manage GA Toolbox versions, A2A 1.0 and BM25 Tool Search with explicit pinning/search metadata. Preserves hosted runtime pins, consent/approval boundaries and exact discovered names; labels the Prompt bridge and Skills separately as preview and records A2A service-managed retention separately from active-resource cleanup. |
| [**foundry-skill-catalog**](skills/foundry-skill-catalog/) | Versioned Skills preview API with pinned/default downloads, build-time bundles and the compatible **`FoundrySkillsSource(SkillsSource)`** adapter. Includes the existing MAF 1.17 native MCP provider for progressive inline-body loading, distinct from eager download/injection, with explicit approval and version boundaries. |
### 🛠️ Cross-Cutting Helpers
Multi-skill scaffolding and operational discipline used by the [Threadlight pipeline](https://github.com/aiappsgbb/threadlight-skills) and standalone Foundry deployments.
| Skill | Description |
|-------|-------------|
| [**azd-patterns**](skills/azd-patterns/) | Tips and patterns for Azure Developer CLI (`azd`) — hooks, postdeploy/postprovision, ACA Job deployment, **silent-failure debug playbook** (6-rung diagnostic ladder). |
| [**azure-tenant-isolation**](skills/azure-tenant-isolation/) | Multi-tenant Azure CLI / AZD isolation for concurrent terminal sessions — index-file driven, per-tenant `AZURE_CONFIG_DIR` + `az account show` two-layer guard. |
| [**gbb-humanizer**](skills/gbb-humanizer/) | Remove signs of AI-generated writing from prose — 29 patterns from Wikipedia's "Signs of AI writing" (em-dash overuse, rule-of-three, AI vocabulary, copula avoidance, sycophantic openers, signposting), two-pass rewrite + AI-tell audit. **Reader-first pass** backed by comprehension research (lead with the point, verbs over nouns, known before new, no added personality in work writing). **Ships pre-canned GBB voice samples** (seller pitch + technical blog), **section-aware mode** (skip code/tables/SME quotes), **density-preserving guardrail** so domain rule-of-three lists survive. Adapted from [blader/humanizer](https://github.com/blader/humanizer) v2.5.1 (MIT). |
| [**ghcp-cli-config**](skills/ghcp-cli-config/) | Bootstrap GitHub Copilot CLI for GBB workflows — 6 recommended MCP servers (mslearn, Azure, Playwright, context7, tavily, mem0), `settings.json` baseline (model, `sessionSync`, `allowedUrls`, `trustedFolders`), work-iq plugin family for Microsoft staff, `autoApprove` safe-default matrix, and a **fresh-machine bootstrap procedure** the agent can execute step-by-step. Distilled from a live GBB engineer's `~/.copilot/`. |
| [**paygo-ptu-cost-analyzer**](skills/paygo-ptu-cost-analyzer/) | Headless PAYGO-vs-PTU cost analysis for Azure OpenAI deployments — vendored analyzer (`analysis.py` / `formatting.py` / `models.json` / 2× KQL) from [`aiappsgbb/ptu-paygo-mix`](https://github.com/aiappsgbb/ptu-paygo-mix) `@e1786f8` with the Streamlit UI stripped out. Ingests **CSV / Log Analytics KQL / synthetic** and emits a 4-file report (markdown + JSON + 2× PNG charts) with PTU sizing across configurable percentiles, monthly/yearly term pricing, global/data-zone tier rates, and a recommendation rule (target percentile under PAYGO baseline). Ships **two KQL paths** — default uses `InputTokens − ProcessedPromptTokens` for cached-token derivation; `active_tokens.kql` is the fallback for telemetry configs that only expose `ActiveTokens`. CLI: `python references/run_report.py --csv input.csv --model gpt-5.4 --tier global --out-dir ./report`. |
| [**token-economics**](skills/token-economics/) | Cut cost per successful task, TPM pressure and context size for Responses API apps and agents. Ordered ladder (prompt/tool-output diet → **deferred tool loading with `tool_search` + `defer_loading`, gpt-5.4+** → cache-friendly prefix → reasoning effort/verbosity/`max_output_tokens` → compaction → model right-sizing → Flex/Batch/Priority). Live-measured eager-vs-deferred script (cost, latency, tool selection, session mode): measured on gpt-5.4 → gpt-6.1-sol: deferral cut money 37–68% on a 160-function catalog but **raised** it +24–171% on a small warm catalog, on every family. Also `allowed_tools` for cache-safe per-turn restriction. |
| [**progress-guard**](skills/progress-guard/) | **Local simplification candidate:** execution memory, bounded recovery and terminal-only child coordination. Persistent coordinator/executor roles, task-focused kickoffs and targeted acceptance; solo work stays direct. No supervisors, runtime threshold control or tool preemption. [Behavioral acceptance pending](docs/maintenance/progress-guard-validation.md). |
| [**copilot-doctor**](skills/copilot-doctor/) | **Local source candidate:** read-only Copilot App/CLI setup inventory, source-attributed MCP and skill findings, opt-in private scan history, bounded CLI help checks, and approval-gated repair runbook. Preserves pins and exclusions; no automatic cleanup or MCP startup. [Validation and limits](docs/maintenance/copilot-doctor-validation.md). |
### 🛡️ Governance
The **AI Citadel** governance ladder — three skills that compose into
defence-in-depth for production agent platforms:
1. **Layer 1 (gateway infra)** — `citadel-hub-deploy` stands up the
shared APIM AI gateway + Foundry control plane + telemetry sink.
2. **Layer 1 (per-spoke wiring)** — `citadel-spoke-onboarding` connects
each agent project to the hub via per-team Access Contracts, gateway
routing, and product policies.
3. **Layer 1.5 (in-process)** — `foundry-agt` is a separate action/tool
enforcement layer that runs inside the agent runtime itself:
deterministic per-tool-call capability allow/deny before the tool body
executes, plus a tamper-evident, hash-chained audit trail. It
complements the gateway and network isolation rather than adapting
into Citadel.
Compose with `foundry-hosted-agents` / [`threadlight-deploy`](https://github.com/aiappsgbb/threadlight-skills) for
MAF middleware, and `foundry-vnet-deploy` for network isolation.
| Skill | Description |
|-------|-------------|
| [**citadel-hub-deploy**](skills/citadel-hub-deploy/) | Deploy the **AI Citadel Governance Hub** (Layer 1 infra) — APIM AI Gateway + 2× Microsoft Foundry control plane + Cosmos usage telemetry + Logic App billing + 4 LLM APIs (Azure OpenAI / OpenAI Realtime / Universal LLM / Unified AI wildcard) + 13 Private DNS Zones + Managed Redis semantic cache. Wraps `Azure-Samples/ai-hub-gateway-solution-accelerator` `citadel-v1` branch (azd template, MIT) at a pinned commit; **does NOT fork or vendor upstream Bicep**. Ships 3 curated env profiles (`pilot-quickstart`, `enterprise-baseline`, `vnet-isolated-spoke-aware`), pre-flight checklist, live audit notes against a real `rg-citadel-hub-01` deployment in Sweden Central (resource inventory + APIM smoke calls + latency baselines + 8 Known Issues incl. `api-key` header convention + `max_completion_tokens` GPT-5.4 migration). |
| [**citadel-spoke-onboarding**](skills/citadel-spoke-onboarding/) | Onboard a GenAI app or Foundry project as a spoke into an AI Citadel Governance Hub — Access Contracts, APIM connections, Key Vault secrets, product policies, JWT auth. **Combines with `foundry-vnet-deploy` for VNet-isolated spokes** (Option B Foundry Connection auth posture mandatory). Pairs with `citadel-hub-deploy` for the full Layer 1 story. |
| [**foundry-agt**](skills/foundry-agt/) | Wrap the [Microsoft Agent Governance Toolkit (AGT)](https://github.com/microsoft/agent-governance-toolkit) v4.1.0 (Public Preview) around a Foundry hosted agent's Microsoft Agent Framework runtime — **in-process middleware only, no sidecar or adapter path**. Loads two starter YAML policies (default / PII-deny, inbound message text only) into a PolicyEvaluator, and separately enforces deterministic per-tool-call allow/deny via `CapabilityGuardMiddleware`'s explicit allow/deny lists before the tool body executes; emits a tamper-evident, hash-chained `AuditLog` with CloudEvents export, and composes with a real `FoundryChatClient`. `agt verify` is a toolkit self-assessment, not a certification. Wrapper skill — upstream is canon, links don't duplicate. |
| [**azure-sre-agent**](skills/azure-sre-agent/) | GBB wrapper for [Azure SRE Agent](https://learn.microsoft.com/en-us/azure/sre-agent/) (preview). **Thin** — uses Microsoft's official toolchain at [`microsoft/sre-agent`](https://github.com/microsoft/sre-agent) (Bicep + Terraform + azd + PS deploy backends, `bin/` CLI) and plugin marketplace at [`Azure/sre-agent-plugins`](https://github.com/Azure/sre-agent-plugins). Adds the three things MS won't ship: **3 GBB recipes** (`citadel-routed`, `foundry-hosted-agents`, `threadlight-pilot-handover`) in upstream byte-exact shape; **2 GBB plugins** (`gbb-citadel`, `gbb-foundry`) with 5 expert skills (JWT 403 debug, APIM throttle, hosted-agent deploy triage, BYOK 401, AOAI quota); a **pre-flight runbook** for the gotchas the official docs assume away (Zscaler `*.azuresre.ai`, region scarcity, `Microsoft.App` RP); and **`data_plane.py`** so other awesome-gbb skills (Threadlight) can post incidents via HTTP trigger. |
### 📊 Content Generation
| Skill | Description |
|-------|-------------|
| [**web-experience-design**](skills/web-experience-design/) | **Merged source; release pending:** task-first web experiences for reports, comparisons, catalogs, tools and sites. Content and navigation before styling; meaningful icons/motion; real-content wireframes and browser task evidence. No mandatory theme, stack or external generator. [Output acceptance pending](docs/maintenance/web-experience-design-validation.md). |
| [**gbb-pptx**](skills/gbb-pptx/) | Plan, review and generate content-first presentations: audience, storyline, evidence, storyboard and editorial checks before python-pptx rendering. Confirm audience/depth; default complete decks to cover, framing, development and closing. Optional browser-first guidance requires early export proof and explicit editability; retains native rendering, themes and notes. |
| [**html-presentation**](skills/html-presentation/) | Evidence-backed continuous HTML presentations: native scrolling and chapter anchors, purposeful explorers, supplied Azure palette, authentic artwork and accessible offline runtime. WorkIQ, Seismic and Microsoft Learn grounding with explicit source gaps. Lean Cowork packaging; model evaluations deferred. Use web-experience-design for general web UX and gbb-pptx for editable native PowerPoint. |
| [**html-deck-to-pptx**](skills/html-deck-to-pptx/) | Convert an existing HTML slide deck (reveal.js, `section.slide`, keyboard-driven) into a native, editable PPTX: text runs, linear gradients, tables, bullets, hyperlinks, speaker notes and embedded video; only icons/diagrams are rasterized. Visual QA renders the PPTX in PowerPoint or LibreOffice and ranks slides by difference from the HTML. Local Node.js + Playwright; no Azure. |
| [**auto-demo-producer**](skills/auto-demo-producer/) | Produce narrated video demos of web apps automatically — Playwright browser recording + edge-tts neural narration + ffmpeg assembly into polished MP4 |
### 🧬 Org Composition & Zava Workspace
> **Moved to [aiappsgbb/zava-constellation](https://github.com/aiappsgbb/zava-constellation)** —
> `research-company`, `compose-org`, and `zava-workspace-deploy`.
### 🔍 Discovery
| Skill | Description |
|-------|-------------|
| [**ip-catalog**](skills/ip-catalog/) | Discover AI Apps GBB IP catalog via MCP — search, list, filter, and inspect intellectual property assets including metadata and READMEs |
---
## How to Use
> [!TIP]
> **Browse the full catalog →** <https://fluffy-carnival-6qny72q.pages.github.io/> — searchable skill index, per-skill detail pages, plugin install commands, and an [`llms.txt`](https://fluffy-carnival-6qny72q.pages.github.io/llms.txt) machine-readable listing for AI agents. Mirrors the [`github/awesome-copilot`](https://awesome-copilot.github.com/) site pattern.
> [!TIP]
> **Install the catalog in one command via plugin.** The proposed catalog contains 45 skills in a single [Copilot CLI plugin](plugin.json). Main includes AgentOps, delegated-auth and web-experience-design source; progress-guard, copilot-doctor and managed voice are source candidates. The html-presentation and html-deck-to-pptx additions have local tooling checks, not completed model evaluations. Installation does not certify remaining acceptance gates:
>
> ```bash
> # Register the marketplace once:
> copilot plugin marketplace add aiappsgbb/awesome-gbb
>
> # Install the catalog source; review each skill's acceptance status:
> copilot plugin install awesome-gbb@awesome-gbb
> ```
>
> The plugin also works in the [Copilot Desktop App (preview)](https://github.com/github/app), [VS Code Copilot Chat agent mode (preview)](https://code.visualstudio.com/docs/copilot/chat/chat-agent-mode), and [Claude Code](https://docs.anthropic.com/en/docs/claude-code/plugins) — same `plugin.json` spec, cross-runtime auto-detect.
**Or install one skill at a time with `gh` CLI:**
> [!TIP]
> **First time on Copilot CLI?** Install [**ghcp-cli-config**](skills/ghcp-cli-config/) first — it bootstraps `~/.copilot/` with the 6 recommended MCP servers (`mslearn`, `Azure`, `Playwright`, `context7`, `tavily`, `mem0`), a sensible `settings.json` baseline, and the work-iq plugin family for Microsoft staff. The agent can run the bootstrap end-to-end on a fresh machine.
> [!TIP]
> **Prefer a GUI over the terminal?** Install the [**GitHub Copilot App**](https://github.com/github/app) (public preview) — a native macOS / Windows / Linux desktop application built on Copilot CLI. Because it shares `~/.copilot/`, **every skill in this catalog works in the app out of the box** — same `gh skill install` commands, same MCP servers, same plugins. Lower-friction onramp for SEs and sellers who don't live in a terminal.
>
> - **Business / Enterprise subscribers:** Download today: [Mac (Apple Silicon)](https://github.com/github/app/releases/latest/download/GitHub-Copilot-darwin-arm64.dmg) · [Windows](https://github.com/github/app/releases/latest/download/GitHub-Copilot-windows-x64-setup.exe) · [Linux AppImage](https://github.com/github/app/releases/latest/download/GitHub-Copilot-linux-x64.AppImage) · [Mac (Intel)](https://github.com/github/app/releases/latest/download/GitHub-Copilot-darwin-x64.dmg) · [Windows (ARM)](https://github.com/github/app/releases/latest/download/GitHub-Copilot-windows-arm64-setup.exe)
> - **Pro / Pro+ subscribers:** [Sign up for early access](https://gh.io/github-app) (waitlist).
> - **Docs + walkthrough:** <https://gh.io/github-app-docs>
> - **First-launch tip:** if you have Copilot CLI installed already, the app picks up your existing `~/.copilot/` automatically. Otherwise run the [**ghcp-cli-config**](skills/ghcp-cli-config/) skill from inside the app to seed the directory.
```bash
gh skill install aiappsgbb/awesome-gbb <skill-name> --scope user
```
**Or with `npx skills`:**
```bash
npx skills add aiappsgbb/awesome-gbb --skill <skill-name> -g
```
**As a project-level skill (scoped to a repo):**
```bash
gh skill install aiappsgbb/awesome-gbb <skill-name>
```
> [!TIP]
> **Recommended global install for sellers + SEs:** `foundry-hosted-agents`, `foundry-observability`, `azure-tenant-isolation` (from awesome-gbb) plus the full [threadlight-skills](https://github.com/aiappsgbb/threadlight-skills) plugin. For Zava skills, see [zava-constellation](https://github.com/aiappsgbb/zava-constellation). Other skills can stay at project scope.
### Per-agent AgentOps adoption
Use [`foundry-agentops`](skills/foundry-agentops/SKILL.md) (skill 1.0.0,
merged source with pending readiness gates) for the adoption and release-evidence workflow for **one
already deployed agent**, using exactly `agentops-accelerator==0.14.0`.
Select its agent root and approved deployment context, review evaluation results
and Doctor evidence, decide whether to accept a regression baseline, and hand off
missing prerequisites. Standalone workflow generation requires separate approval;
Threadlight mode supplies prerequisites only, never a competing pipeline.
AgentOps **does not replace Citadel or Threadlight**:
[`citadel-spoke-onboarding`](skills/citadel-spoke-onboarding/SKILL.md) retains
gateway/access-contract ownership, and
[Threadlight](https://github.com/aiappsgbb/threadlight-skills) retains pipeline
ownership and final readiness scoring. Deep evaluators/datasets remain with
[`foundry-evals`](skills/foundry-evals/SKILL.md), OTel/App Insights wiring with
[`foundry-observability`](skills/foundry-observability/SKILL.md), and runtime
policy enforcement with [`foundry-agt`](skills/foundry-agt/SKILL.md).
Aggregated evidence is not production-ready certification. The
[sanitized manual results](docs/maintenance/foundry-agentops-validation.md) distinguish
the completed corrected-source execution from its **quality FAIL (4/5 thresholds)**
and **Doctor readiness BLOCKED** outcome. The prior 5/5 cycle remains historical,
not the corrected result. Neither manual CLI-user cycle validates the unchanged
CI/SP path, full matrix, or release readiness. The later exact-candidate
[targeted CI result](https://github.com/aiappsgbb/awesome-gbb/pull/484)
proves technical CI execution with quality FAIL and Doctor BLOCKED; it is not
full-matrix or release acceptance. [#502](https://github.com/aiappsgbb/awesome-gbb/pull/502)
only corrects dependency-only CI selection, not quality or approval requirements.
**Optional Toolbox guardrails:** [native named version policies](https://learn.microsoft.com/azure/foundry/agents/how-to/tools/toolbox#configure-guardrails)
can filter tool inputs/outputs independently of model filtering. This adds policy
setup, exact-version binding/readback and targeted behavior acceptance; the
benefit is centralized filtering for tools that actually traverse that Toolbox.
The catalog's wiring sample does not attach such a policy or cover direct/local
tools outside the Toolbox. Approval metadata still requires runtime enforcement.
No mandatory rerouting, new guardrail implementation, live acceptance or replacement
for signed action policy, audit acknowledgement and one-use human approval is implied.
---
## Agentic Loop — The BUILD → RUN → SCALE Pipeline
The [`agentic-loop`](https://github.com/aiappsgbb/agentic-loop) initiative provides the **orchestration layer** that drives awesome-gbb skills through a 5-stage development loop: **Specify → Plan → Implement → Verify → Deploy**. It uses the [Lean Toolkit (Spec2Cloud)](https://github.com/Azure-Samples/Spec2Cloud) plugin and an `agentic-loop` skill that applies GBB defaults (Foundry hosted agents, model selection, region picker) and recommends which awesome-gbb skills to install for each spec.
**Quick setup:**
```bash
# 1. Install the lean toolkit plugin (5-stage loop)
copilot plugin marketplace add Azure-Samples/Spec2Cloud
copilot plugin install lean@Spec2Cloud
# 2. Install the agentic-loop skill (GBB defaults + skill recommender)
gh skills install aiappsgbb/agentic-loop agentic-loop --dir .github/skills --agent github-copilot
# 3. Run the loop
copilot -p "/lean:specify <your idea here>"
```
The agentic-loop skill will recommend awesome-gbb skills based on your spec's content — foundational skills for every build, plus specialized skills when the spec mentions evals, governance, MCP, VNet isolation, or production gateway patterns. See the [getting-started playbook](https://github.com/aiappsgbb/agentic-loop/tree/main/playbooks/getting-started) for a step-by-step walkthrough.
---
## How we test — six CI gates, four testing tiers, live Azure
Every skill in this catalog is a **contract**: the code samples in `SKILL.md` are the exact code a consumer will copy. If a sample doesn't run, the skill is broken. To keep that contract honest as upstream SDKs move, we run a self-healing test+freshness pipeline on real Azure infrastructure — not just lint.
```mermaid
flowchart LR
PR[PR opened] --> G1[skill-validation<br/>T0 lint]
PR --> G2[automation-pr-gate<br/>mass-edit invariants]
PR --> G3[pin-validation<br/>T1 re-runs validation.script]
PR --> G4[skill-test<br/>T2 import smoke + T3 E2E Azure]
G1 & G2 & G3 & G4 --> M{all green?}
M -- yes --> R[human review + merge]
M -- yes, Copilot PR --> A[auto-merge-copilot<br/>squash-merges]
CRON[weekly cron] --> F[skill-freshness<br/>drift detection]
F --> ISSUE[consolidated issue<br/>impact-classified]
ISSUE --> TIER{automation tier}
TIER -- issue_only --> HISSUE[human-owned issue]
TIER -- auto --> MODE{execution mode}
MODE -- manual / repository default --> MAN[manual-review issue]
MODE -- copilot --> COP[@Copilot-assigned issue]
HISSUE --> HPR[human opens refresh PR] --> PR
MAN --> HPR
COP --> CPR[coding agent opens PR] --> PR
```
**Six CI gates** (see [`.github/workflows/`](.github/workflows/)):
| Gate | When | What it checks |
|------|------|----------------|
| [`skill-validation.yml`](.github/workflows/skill-validation.yml) | Every PR | Frontmatter parses, description ≤ 1024 chars, valid SemVer, no forbidden strings, pin files conform to schema, plugin manifests version-consistent |
| [`automation-pr-gate.yml`](.github/workflows/automation-pr-gate.yml) | Every PR | Mass-edit invariants (no normalization of reference canon, no cross-skill body edits without `[multi-skill]`, no MAJOR bumps from metadata-only changes) |
| [`pin-validation.yml`](.github/workflows/pin-validation.yml) | Every PR touching `skills/<skill>/` | **Re-runs `validation.script` on the runner** for the pin file of every changed skill — no "trust me, I tested" path |
| [`skill-freshness.yml`](.github/workflows/skill-freshness.yml) | Weekly cron + on-demand | Detects SHA drift, PyPI version bumps, upstream KI closures, link rot, validation age — opens one consolidated issue per skill with `impact:critical/high/medium/low`; auto-tier issues stay `manual-review` by default and switch to `@Copilot` only in copilot mode |
| [`skill-test.yml`](.github/workflows/skill-test.yml) | Every PR + push to main + weekly cron | T2 import smoke (all auto-tier pins) + **T3 E2E Azure** (deploys agents, calls models, verifies the credential chain works against real resources in `<ci-resource-group>`) |
| [`auto-merge-copilot.yml`](.github/workflows/auto-merge-copilot.yml) | On check-suite completion | Auto-approves and squash-merges Copilot-mode refresh PRs once all gates pass — closes the delivery loop when execution mode is `copilot` |
**Four testing tiers** (see [AGENTS.md § 9.8](AGENTS.md#98--skill-testing-tiers)) — each subsumes the ones below:
- **T0 · Lint** — frontmatter parses, description ≤ 1024, no forbidden strings, deprecated-API scan passes. Every PR.
- **T1 · Pin validation** — `validation.script` runs end-to-end; every `expected_output` substring must appear in stdout. Required on pin-file changes.
- **T2 · Import smoke** — `pip install <pinned-version>` + `python -c "from X import Y"` for every import in SKILL.md code samples. Required on MINOR/MAJOR upstream bumps.
- **T3 · E2E Azure** — deploys real agents, makes real API calls (Foundry, ACA, ACR), verifies the credential chain works end-to-end. CI has OIDC-federated credentials and dedicated infra (`<ci-foundry-account>`, `<ci-container-registry>`, `<ci-container-app-env>`, `gpt-5.4-mini`, `text-embedding-3-small`). Required for any skill that tells consumers to connect to Azure.
**Self-healing freshness loop.** Every wrapper skill ships a machine-readable [`upstream-pin.md`](scripts/templates/upstream-pin.template.md). The detector always runs: `skill-freshness.yml` resolves `execution_mode=repository` against the repository variable `FRESHNESS_EXECUTION_MODE`, and if that variable is absent the safe default is `manual`. In manual mode, auto-tier issues stay human-owned and gain the `manual-review` label; in copilot mode, those same auto-tier issues are assigned to **`@Copilot`** and the delivery loop (`copilot-pr-autorun` → `auto-merge-copilot`) resumes. `automation_tier: issue_only` remains human-only in both modes. See the [manual freshness runbook](docs/maintenance/manual-skill-freshness.md) for the operating procedure.
**Patterns from the trenches.** The pipeline is what it is because 25 hard-won patterns (LAW ingestion lag, OIDC TTL on teardown, ARM cross-resource cache lag, Foundry project-MI vs caller-UAMI 401s, autoregressive marker priming, Copilot-CLI 429 throttling, …) are baked into the workflows and fixture authoring rules. Each pattern carries a forensic provenance link to the run that exposed it. See [AGENTS.md § 9.7](AGENTS.md#97--azure-ci-credentials-and-e2e-infrastructure) for the full list, or the [Engineering page](https://aiappsgbb.github.io/awesome-gbb/engineering/) for a curated tour.
---
## Repository Structure
```
README.md # This file — catalog index + install instructions
DEMOS.md # Demo guide for Foundry walkthroughs
AGENTS.md # Contributor & sub-agent safety guide
plugin.json # Single plugin manifest (39 skills in the proposed catalog via "skills/")
skills/
<skill-name>/
SKILL.md # Skill definition (frontmatter + instructions)
README.md # Optional: extended docs, examples, changelog
```
---
## Contributing
> [!IMPORTANT]
> **Read [AGENTS.md](AGENTS.md) first** if you (or a sub-agent acting on your
> behalf) are about to edit any skill. It captures the invariants — agnostic
> wording, reference-data canon, `metadata.version` rules, the mass-edit
> safety rails — most of which are **now enforced by CI** (see § 9 of
> AGENTS.md and the [`automation-pr-gate`](.github/workflows/automation-pr-gate.yml)
> workflow).
1. **Fork & branch** — create a feature branch from `main`.
2. **Add your Skill** — place it under `skills/<your-skill-name>/SKILL.md`.
3. **Open a PR** — describe the scenario, target audience, and any dependencies.
4. **Peer review** — at least one GBB team member must approve before merge.
### Skill Quality Checklist
- [ ] Clear, concise `description` in frontmatter (≤ 1024 chars — CI-enforced)
- [ ] Well-defined trigger phrases (when should the skill activate?)
- [ ] Actionable instructions (the agent *does* the work, not just advises)
- [ ] No secrets or credentials embedded
- [ ] Tested with at least one agentic runtime
- [ ] If the skill wraps an external repo/SDK: include `references/upstream-pin.md`
from [`scripts/templates/upstream-pin.template.md`](scripts/templates/upstream-pin.template.md)
so the freshness lifecycle picks it up
### 🪴 Freshness lifecycle
Wrapper skills (those citing a `github.com/<org>/<repo>` or pinning a
preview SDK version) ship a machine-readable `references/upstream-pin.md`
declaring their upstream contract. The
[`Skill freshness`](.github/workflows/skill-freshness.yml) GitHub Action
runs weekly and opens a per-skill GitHub issue when it detects:
- SHA drift on the pinned upstream branch
- PyPI version drift on a pinned package
- Closure of an upstream issue documented in `known_issues[]`
- Link rot on a documented URL
- Validation age > 180 days
Detection always runs in both modes. For `automation_tier: auto`, the
repository variable `FRESHNESS_EXECUTION_MODE` decides issue ownership:
`manual` (the safe default when the variable is absent) keeps the issue
human-owned with a `manual-review` label, while `copilot` assigns the
issue to `@Copilot` so the coding agent can open the refresh PR. Skills
with `automation_tier: issue_only` stay human-only in both modes. See
the [manual freshness runbook](docs/maintenance/manual-skill-freshness.md)
and [AGENTS.md § 9](AGENTS.md#9--skill-freshness-lifecycle) for the full
lifecycle convention.
## License
This project is licensed under the [MIT License](LICENSE).
## Code of Conduct
This project follows the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).