From 3d00ec4c628b350fa1181e175d687862c099bdda Mon Sep 17 00:00:00 2001
From: Hashwanth Sutharapu <hashwanthsutharapu@Hashs-Macbook-Air.local>
Date: Sun, 18 Jan 2026 19:39:54 -0800
Subject: [PATCH 1/3] Add agentic-eval skill for agent evaluation patterns

---
 skills/agentic-eval/SKILL.md | 189 +++++++++++++++++++++++++++++++++++
 1 file changed, 189 insertions(+)
 create mode 100644 skills/agentic-eval/SKILL.md

diff --git a/skills/agentic-eval/SKILL.md b/skills/agentic-eval/SKILL.md
new file mode 100644
index 00000000..3cb14203
--- /dev/null
+++ b/skills/agentic-eval/SKILL.md
@@ -0,0 +1,189 @@
+---
+name: agentic-eval
+description: |
+  Patterns and techniques for evaluating and improving AI agent outputs. Use this skill when:
+  - Implementing self-critique and reflection loops
+  - Building evaluator-optimizer pipelines for quality-critical generation
+  - Creating test-driven code refinement workflows
+  - Designing rubric-based or LLM-as-judge evaluation systems
+  - Adding iterative improvement to agent outputs (code, reports, analysis)
+  - Measuring and improving agent response quality
+---
+
+# Agentic Evaluation Patterns
+
+Patterns for self-improvement through iterative evaluation and refinement.
+
+## Overview
+
+Evaluation patterns enable agents to assess and improve their own outputs, moving beyond single-shot generation to iterative refinement loops.
+
+```
+Generate → Evaluate → Critique → Refine → Output
+    ↑                              │
+    └──────────────────────────────┘
+```
+
+## When to Use
+
+- **Quality-critical generation**: Code, reports, analysis requiring high accuracy
+- **Tasks with clear evaluation criteria**: Defined success metrics exist
+- **Content requiring specific standards**: Style guides, compliance, formatting
+
+---
+
+## Pattern 1: Basic Reflection
+
+Agent evaluates and improves its own output through self-critique.
+
+```python
+def reflect_and_refine(task: str, criteria: list[str], max_iterations: int = 3) -> str:
+    """Generate with reflection loop."""
+    output = llm(f"Complete this task:\n{task}")
+    
+    for i in range(max_iterations):
+        # Self-critique
+        critique = llm(f"""
+        Evaluate this output against criteria: {criteria}
+        Output: {output}
+        Rate each: PASS/FAIL with feedback as JSON.
+        """)
+        
+        critique_data = json.loads(critique)
+        all_pass = all(c["status"] == "PASS" for c in critique_data.values())
+        if all_pass:
+            return output
+        
+        # Refine based on critique
+        failed = {k: v["feedback"] for k, v in critique_data.items() if v["status"] == "FAIL"}
+        output = llm(f"Improve to address: {failed}\nOriginal: {output}")
+    
+    return output
+```
+
+**Key insight**: Use structured JSON output for reliable parsing of critique results.
+
+---
+
+## Pattern 2: Evaluator-Optimizer
+
+Separate generation and evaluation into distinct components for clearer responsibilities.
+
+```python
+class EvaluatorOptimizer:
+    def __init__(self, score_threshold: float = 0.8):
+        self.score_threshold = score_threshold
+    
+    def generate(self, task: str) -> str:
+        return llm(f"Complete: {task}")
+    
+    def evaluate(self, output: str, task: str) -> dict:
+        return json.loads(llm(f"""
+        Evaluate output for task: {task}
+        Output: {output}
+        Return JSON: {{"overall_score": 0-1, "dimensions": {{"accuracy": ..., "clarity": ...}}}}
+        """))
+    
+    def optimize(self, output: str, feedback: dict) -> str:
+        return llm(f"Improve based on feedback: {feedback}\nOutput: {output}")
+    
+    def run(self, task: str, max_iterations: int = 3) -> str:
+        output = self.generate(task)
+        for _ in range(max_iterations):
+            evaluation = self.evaluate(output, task)
+            if evaluation["overall_score"] >= self.score_threshold:
+                break
+            output = self.optimize(output, evaluation)
+        return output
+```
+
+---
+
+## Pattern 3: Code-Specific Reflection
+
+Test-driven refinement loop for code generation.
+
+```python
+class CodeReflector:
+    def reflect_and_fix(self, spec: str, max_iterations: int = 3) -> str:
+        code = llm(f"Write Python code for: {spec}")
+        tests = llm(f"Generate pytest tests for: {spec}\nCode: {code}")
+        
+        for _ in range(max_iterations):
+            result = run_tests(code, tests)
+            if result["success"]:
+                return code
+            code = llm(f"Fix error: {result['error']}\nCode: {code}")
+        return code
+```
+
+---
+
+## Evaluation Strategies
+
+### Outcome-Based
+Evaluate whether output achieves the expected result.
+
+```python
+def evaluate_outcome(task: str, output: str, expected: str) -> str:
+    return llm(f"Does output achieve expected outcome? Task: {task}, Expected: {expected}, Output: {output}")
+```
+
+### LLM-as-Judge
+Use LLM to compare and rank outputs.
+
+```python
+def llm_judge(output_a: str, output_b: str, criteria: str) -> str:
+    return llm(f"Compare outputs A and B for {criteria}. Which is better and why?")
+```
+
+### Rubric-Based
+Score outputs against weighted dimensions.
+
+```python
+RUBRIC = {
+    "accuracy": {"weight": 0.4},
+    "clarity": {"weight": 0.3},
+    "completeness": {"weight": 0.3}
+}
+
+def evaluate_with_rubric(output: str, rubric: dict) -> float:
+    scores = json.loads(llm(f"Rate 1-5 for each dimension: {list(rubric.keys())}\nOutput: {output}"))
+    return sum(scores[d] * rubric[d]["weight"] for d in rubric) / 5
+```
+
+---
+
+## Best Practices
+
+| Practice | Rationale |
+|----------|-----------|
+| **Clear criteria** | Define specific, measurable evaluation criteria upfront |
+| **Iteration limits** | Set max iterations (3-5) to prevent infinite loops |
+| **Convergence check** | Stop if output score isn't improving between iterations |
+| **Log history** | Keep full trajectory for debugging and analysis |
+| **Structured output** | Use JSON for reliable parsing of evaluation results |
+
+---
+
+## Quick Start Checklist
+
+```markdown
+## Evaluation Implementation Checklist
+
+### Setup
+- [ ] Define evaluation criteria/rubric
+- [ ] Set score threshold for "good enough"
+- [ ] Configure max iterations (default: 3)
+
+### Implementation
+- [ ] Implement generate() function
+- [ ] Implement evaluate() function with structured output
+- [ ] Implement optimize() function
+- [ ] Wire up the refinement loop
+
+### Safety
+- [ ] Add convergence detection
+- [ ] Log all iterations for debugging
+- [ ] Handle evaluation parse failures gracefully
+```

From 105c0f55e2d0625675530f1c67c1aa28cad7c545 Mon Sep 17 00:00:00 2001
From: Hashwanth Sutharapu <hashwanthsutharapu@Hashs-Macbook-Air.local>
Date: Mon, 19 Jan 2026 17:25:39 -0800
Subject: [PATCH 2/3] chore: update README.skills.md via npm start

Ran the update script as requested by reviewer to regenerate the skills table.
---
 docs/README.skills.md | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/docs/README.skills.md b/docs/README.skills.md
index 93399de8..52183b72 100644
--- a/docs/README.skills.md
+++ b/docs/README.skills.md
@@ -22,6 +22,13 @@ Skills differ from other primitives by supporting bundled assets (scripts, code
 
 | Name | Description | Bundled Assets |
 | ---- | ----------- | -------------- |
+| [agentic-eval](../skills/agentic-eval/SKILL.md) | Patterns and techniques for evaluating and improving AI agent outputs. Use this skill when:
+- Implementing self-critique and reflection loops
+- Building evaluator-optimizer pipelines for quality-critical generation
+- Creating test-driven code refinement workflows
+- Designing rubric-based or LLM-as-judge evaluation systems
+- Adding iterative improvement to agent outputs (code, reports, analysis)
+- Measuring and improving agent response quality | None |
 | [appinsights-instrumentation](../skills/appinsights-instrumentation/SKILL.md) | Instrument a webapp to send useful telemetry data to Azure App Insights | `LICENSE.txt`<br />`examples/appinsights.bicep`<br />`references/ASPNETCORE.md`<br />`references/AUTO.md`<br />`references/NODEJS.md`<br />`references/PYTHON.md`<br />`scripts/appinsights.ps1` |
 | [azure-resource-visualizer](../skills/azure-resource-visualizer/SKILL.md) | Analyze Azure resource groups and generate detailed Mermaid architecture diagrams showing the relationships between individual resources. Use this skill when the user asks for a diagram of their Azure resources or help in understanding how the resources relate to each other. | `LICENSE.txt`<br />`assets/template-architecture.md` |
 | [azure-role-selector](../skills/azure-role-selector/SKILL.md) | When user is asking for guidance for which role to assign to an identity given desired permissions, this agent helps them understand the role that will meet the requirements with least privilege access and how to apply that role. | `LICENSE.txt` |

From a2525e3112b84f5dc12e22d698dab09f21280901 Mon Sep 17 00:00:00 2001
From: Aaron Powell <me@aaron-powell.com>
Date: Fri, 23 Jan 2026 10:06:44 +1100
Subject: [PATCH 3/3] fix: enhance markdown table cell formatting for
 descriptions in README and skills

---
 collections/azure-cloud-development.md |  2 +-
 docs/README.instructions.md            |  2 +-
 docs/README.skills.md                  |  8 +--
 eng/update-readme.mjs                  | 72 +++++++++++++++++++++-----
 4 files changed, 61 insertions(+), 23 deletions(-)

diff --git a/collections/azure-cloud-development.md b/collections/azure-cloud-development.md
index 33bd557d..4c7dbe65 100644
--- a/collections/azure-cloud-development.md
+++ b/collections/azure-cloud-development.md
@@ -21,7 +21,7 @@ Comprehensive Azure cloud development tools including Infrastructure as Code, se
 | [Azure Terraform Best Practices](../instructions/terraform-azure.instructions.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fterraform-azure.instructions.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fterraform-azure.instructions.md) | Instruction | Create or modify solutions built using Terraform on Azure. |  |
 | [Azure Terraform IaC Implementation Specialist](../agents/terraform-azure-implement.agent.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fterraform-azure-implement.agent.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fterraform-azure-implement.agent.md) | Agent | Act as an Azure Terraform Infrastructure as Code coding specialist that creates and reviews Terraform for Azure resources. |  |
 | [Azure Terraform Infrastructure Planning](../agents/terraform-azure-planning.agent.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fterraform-azure-planning.agent.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fterraform-azure-planning.agent.md) | Agent | Act as implementation planner for your Azure Terraform Infrastructure as Code task. |  |
-| [Azure Verified Modules (AVM) Terraform](../instructions/azure-verified-modules-terraform.instructions.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fazure-verified-modules-terraform.instructions.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fazure-verified-modules-terraform.instructions.md) | Instruction |  Azure Verified Modules (AVM) and Terraform |  |
+| [Azure Verified Modules (AVM) Terraform](../instructions/azure-verified-modules-terraform.instructions.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fazure-verified-modules-terraform.instructions.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fazure-verified-modules-terraform.instructions.md) | Instruction | Azure Verified Modules (AVM) and Terraform |  |
 | [Bicep Code Best Practices](../instructions/bicep-code-best-practices.instructions.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fbicep-code-best-practices.instructions.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fbicep-code-best-practices.instructions.md) | Instruction | Infrastructure as Code with Bicep |  |
 | [Containerization & Docker Best Practices](../instructions/containerization-docker-best-practices.instructions.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fcontainerization-docker-best-practices.instructions.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fcontainerization-docker-best-practices.instructions.md) | Instruction | Comprehensive best practices for creating optimized, secure, and efficient Docker images and managing containers. Covers multi-stage builds, image layer optimization, security scanning, and runtime best practices. |  |
 | [Kubernetes Deployment Best Practices](../instructions/kubernetes-deployment-best-practices.instructions.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fkubernetes-deployment-best-practices.instructions.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fkubernetes-deployment-best-practices.instructions.md) | Instruction | Comprehensive best practices for deploying and managing applications on Kubernetes. Covers Pods, Deployments, Services, Ingress, ConfigMaps, Secrets, health checks, resource limits, scaling, and security contexts. |  |
diff --git a/docs/README.instructions.md b/docs/README.instructions.md
index 4574b3d5..ed657be5 100644
--- a/docs/README.instructions.md
+++ b/docs/README.instructions.md
@@ -29,7 +29,7 @@ Team and project-specific instructions to enhance GitHub Copilot's behavior for
 | [Azure Logic Apps and Power Automate Instructions](../instructions/azure-logic-apps-power-automate.instructions.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fazure-logic-apps-power-automate.instructions.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fazure-logic-apps-power-automate.instructions.md) | Guidelines for developing Azure Logic Apps and Power Automate workflows with best practices for Workflow Definition Language (WDL), integration patterns, and enterprise automation |
 | [Azure Terraform Best Practices](../instructions/terraform-azure.instructions.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fterraform-azure.instructions.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fterraform-azure.instructions.md) | Create or modify solutions built using Terraform on Azure. |
 | [Azure Verified Modules (AVM) Bicep](../instructions/azure-verified-modules-bicep.instructions.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fazure-verified-modules-bicep.instructions.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fazure-verified-modules-bicep.instructions.md) | Azure Verified Modules (AVM) and Bicep |
-| [Azure Verified Modules (AVM) Terraform](../instructions/azure-verified-modules-terraform.instructions.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fazure-verified-modules-terraform.instructions.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fazure-verified-modules-terraform.instructions.md) |  Azure Verified Modules (AVM) and Terraform |
+| [Azure Verified Modules (AVM) Terraform](../instructions/azure-verified-modules-terraform.instructions.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fazure-verified-modules-terraform.instructions.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fazure-verified-modules-terraform.instructions.md) | Azure Verified Modules (AVM) and Terraform |
 | [Best Practices and Guidance for Code Components](../instructions/pcf-best-practices.instructions.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fpcf-best-practices.instructions.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fpcf-best-practices.instructions.md) | Best practices and guidance for developing PCF code components |
 | [Bicep Code Best Practices](../instructions/bicep-code-best-practices.instructions.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fbicep-code-best-practices.instructions.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fbicep-code-best-practices.instructions.md) | Infrastructure as Code with Bicep |
 | [Blazor](../instructions/blazor.instructions.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fblazor.instructions.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fblazor.instructions.md) | Blazor component and application patterns |
diff --git a/docs/README.skills.md b/docs/README.skills.md
index 52183b72..4872b576 100644
--- a/docs/README.skills.md
+++ b/docs/README.skills.md
@@ -22,13 +22,7 @@ Skills differ from other primitives by supporting bundled assets (scripts, code
 
 | Name | Description | Bundled Assets |
 | ---- | ----------- | -------------- |
-| [agentic-eval](../skills/agentic-eval/SKILL.md) | Patterns and techniques for evaluating and improving AI agent outputs. Use this skill when:
-- Implementing self-critique and reflection loops
-- Building evaluator-optimizer pipelines for quality-critical generation
-- Creating test-driven code refinement workflows
-- Designing rubric-based or LLM-as-judge evaluation systems
-- Adding iterative improvement to agent outputs (code, reports, analysis)
-- Measuring and improving agent response quality | None |
+| [agentic-eval](../skills/agentic-eval/SKILL.md) | Patterns and techniques for evaluating and improving AI agent outputs. Use this skill when:<br />- Implementing self-critique and reflection loops<br />- Building evaluator-optimizer pipelines for quality-critical generation<br />- Creating test-driven code refinement workflows<br />- Designing rubric-based or LLM-as-judge evaluation systems<br />- Adding iterative improvement to agent outputs (code, reports, analysis)<br />- Measuring and improving agent response quality | None |
 | [appinsights-instrumentation](../skills/appinsights-instrumentation/SKILL.md) | Instrument a webapp to send useful telemetry data to Azure App Insights | `LICENSE.txt`<br />`examples/appinsights.bicep`<br />`references/ASPNETCORE.md`<br />`references/AUTO.md`<br />`references/NODEJS.md`<br />`references/PYTHON.md`<br />`scripts/appinsights.ps1` |
 | [azure-resource-visualizer](../skills/azure-resource-visualizer/SKILL.md) | Analyze Azure resource groups and generate detailed Mermaid architecture diagrams showing the relationships between individual resources. Use this skill when the user asks for a diagram of their Azure resources or help in understanding how the resources relate to each other. | `LICENSE.txt`<br />`assets/template-architecture.md` |
 | [azure-role-selector](../skills/azure-role-selector/SKILL.md) | When user is asking for guidance for which role to assign to an identity given desired permissions, this agent helps them understand the role that will meet the requirements with least privilege access and how to apply that role. | `LICENSE.txt` |
diff --git a/eng/update-readme.mjs b/eng/update-readme.mjs
index dcb4e611..31e5c889 100644
--- a/eng/update-readme.mjs
+++ b/eng/update-readme.mjs
@@ -238,6 +238,39 @@ function extractDescription(filePath) {
   );
 }
 
+/**
+ * Format arbitrary multiline text for safe rendering inside a markdown table cell.
+ * - Preserves line breaks by converting to <br />
+ * - Escapes pipe characters (|) to avoid breaking table columns
+ * - Trims leading/trailing whitespace on each line
+ * - Collapses multiple consecutive blank lines
+ * This should be applied to descriptions across all file types when used in tables.
+ *
+ * @param {string|null|undefined} text
+ * @returns {string} table-safe content
+ */
+function formatTableCell(text) {
+  if (text === null || text === undefined) return "";
+  let s = String(text);
+  // Normalize line endings
+  s = s.replace(/\r\n/g, "\n");
+  // Split lines, trim, drop empty groups while preserving intentional breaks
+  const lines = s
+    .split("\n")
+    .map((l) => l.trim())
+    .filter((_, idx, arr) => {
+      // Keep single blank lines, drop consecutive blanks
+      if (arr[idx] !== "") return true;
+      return arr[idx - 1] !== ""; // allow one blank, remove duplicates
+    });
+  s = lines.join("\n");
+  // Escape table pipes
+  s = s.replace(/\|/g, "&#124;");
+  // Convert remaining newlines to <br /> for a single-cell rendering
+  s = s.replace(/\n/g, "<br />");
+  return s.trim();
+}
+
 function makeBadges(link, type) {
   const aka = AKA_INSTALL_URLS[type] || AKA_INSTALL_URLS.instructions;
 
@@ -298,8 +331,10 @@ function generateInstructionsSection(instructionsDir) {
     const badges = makeBadges(link, "instructions");
 
     if (customDescription && customDescription !== "null") {
-      // Use the description from frontmatter
-      instructionsContent += `| [${title}](../${link})<br />${badges} | ${customDescription} |\n`;
+      // Use the description from frontmatter, table-safe
+      instructionsContent += `| [${title}](../${link})<br />${badges} | ${formatTableCell(
+        customDescription
+      )} |\n`;
     } else {
       // Fallback to the default approach - use last word of title for description, removing trailing 's' if present
       const topic = title.split(" ").pop().replace(/s$/, "");
@@ -356,7 +391,9 @@ function generatePromptsSection(promptsDir) {
     const badges = makeBadges(link, "prompt");
 
     if (customDescription && customDescription !== "null") {
-      promptsContent += `| [${title}](../${link})<br />${badges} | ${customDescription} |\n`;
+      promptsContent += `| [${title}](../${link})<br />${badges} | ${formatTableCell(
+        customDescription
+      )} |\n`;
     } else {
       promptsContent += `| [${title}](../${link})<br />${badges} | | |\n`;
     }
@@ -533,7 +570,9 @@ function generateSkillsSection(skillsDir) {
         ? skill.assets.map((a) => `\`${a}\``).join("<br />")
         : "None";
 
-    content += `| [${skill.name}](${link}) | ${skill.description} | ${assetsList} |\n`;
+    content += `| [${skill.name}](${link}) | ${formatTableCell(
+      skill.description
+    )} | ${assetsList} |\n`;
   }
 
   return `${TEMPLATES.skillsSection}\n${TEMPLATES.skillsUsage}\n\n${content}`;
@@ -598,14 +637,12 @@ function generateUnifiedModeSection(cfg) {
       mcpServerCell = generateMcpServerLinks(servers, registryNames);
     }
 
+    const descCell =
+      description && description !== "null" ? formatTableCell(description) : "";
     if (includeMcpServers) {
-      content += `| [${title}](../${link})<br />${badges} | ${
-        description && description !== "null" ? description : ""
-      } | ${mcpServerCell} |\n`;
+      content += `| [${title}](../${link})<br />${badges} | ${descCell} | ${mcpServerCell} |\n`;
     } else {
-      content += `| [${title}](../${link})<br />${badges} | ${
-        description && description !== "null" ? description : ""
-      } |\n`;
+      content += `| [${title}](../${link})<br />${badges} | ${descCell} |\n`;
     }
   }
 
@@ -677,7 +714,9 @@ function generateCollectionsSection(collectionsDir) {
   // Generate table rows for each collection file
   for (const entry of sortedEntries) {
     const { collection, collectionId, name, isFeatured } = entry;
-    const description = collection.description || "No description";
+    const description = formatTableCell(
+      collection.description || "No description"
+    );
     const itemCount = collection.items ? collection.items.length : 0;
     const tags = collection.tags ? collection.tags.join(", ") : "";
 
@@ -719,7 +758,9 @@ function generateFeaturedCollectionsSection(collectionsDir) {
           const collectionId =
             collection.id || path.basename(file, ".collection.yml");
           const name = collection.name || collectionId;
-          const description = collection.description || "No description";
+          const description = formatTableCell(
+            collection.description || "No description"
+          );
           const tags = collection.tags ? collection.tags.join(", ") : "";
           const itemCount = collection.items ? collection.items.length : 0;
 
@@ -904,6 +945,9 @@ function buildCollectionRow({
     ? `[${title}](${link})<br />${badges}`
     : `[${title}](${link})`;
 
+  // Ensure description is table-safe
+  const safeUsage = formatTableCell(usageDescription);
+
   if (hasAgents) {
     // Only agents currently have MCP servers; future migration may extend to chat modes.
     const mcpServers =
@@ -912,9 +956,9 @@ function buildCollectionRow({
       mcpServers.length > 0
         ? generateMcpServerLinks(mcpServers, registryNames)
         : "";
-    return `| ${titleCell} | ${typeDisplay} | ${usageDescription} | ${mcpServerCell} |\n`;
+    return `| ${titleCell} | ${typeDisplay} | ${safeUsage} | ${mcpServerCell} |\n`;
   }
-  return `| ${titleCell} | ${typeDisplay} | ${usageDescription} |\n`;
+  return `| ${titleCell} | ${typeDisplay} | ${safeUsage} |\n`;
 }
 
 // Utility: write file only if content changed