SKILL.md Frontmatter Compliance Audit - Agent Skills Specification

skill-audit.md

SKILL.md Frontmatter Compliance Audit - Agent Skills Specification

SKILL.md Frontmatter Compliance Audit

Repository: microsoft/GitHub-Copilot-for-Azure
Date: 2026-01-30
Based on: Agent Skills Specification and community feedback

---

Executive Summary

This audit evaluates all 26 SKILL.md files against the Agent Skills specification best practices. The goal is to improve agent disambiguation—helping AI agents correctly identify when to invoke each skill and when not to.

Metric	Status
Total Skills Audited	26
High Adherence	0 (0%)
Medium Adherence	14 (54%)
Low Adherence	12 (46%)

Key Finding: All skills have valid name and description fields, but none include anti-triggers, compatibility requirements, or spec-compliant examples.

---

Best Practices Checklist

Based on the Agent Skills Specification and Anthropic's Skills Best Practices:

Required Fields

Field	Requirement	Limit
name	lowercase, hyphens only, must match directory name	64 chars max
description	Explain WHAT the skill does AND WHEN to invoke it	1024 chars max

Description Length Audit

All skills are within the 1024 character limit for description:

Skill	Length	Status
azure-deployment-preflight	475 chars	✅
azure-postgres	447 chars	✅
azure-create-app	427 chars	✅
azure-quick-review	434 chars	✅
azure-aigateway	319 chars	✅
azure-cost-optimization	290 chars	✅
azure-deploy	281 chars	✅
azure-resource-visualizer	275 chars	✅
azure-keyvault-expiration-audit	267 chars	✅
azure-validation	266 chars	✅
azure-kusto	256 chars	✅
markdown-token-optimizer	245 chars	✅
skill-authoring	238 chars	✅
azure-security-hardening	233 chars	✅
azure-role-selector	231 chars	✅
azure-diagnostics	229 chars	✅
entra-app-registration	221 chars	✅
azure-nodejs-production	220 chars	✅
microsoft-foundry	219 chars	✅
azure-storage	217 chars	✅
azure-ai	217 chars	✅
azure-networking	213 chars	✅
azure-security	203 chars	✅
azure-observability	195 chars	✅
azure-functions	136 chars	✅
appinsights-instrumentation	71 chars	✅ ⚠️ (too brief)

Note: While all descriptions are under 1024 chars, several are too brief to be effective. The spec recommends descriptions that include both WHAT the skill does AND WHEN to invoke it. Very short descriptions (under 150 chars) typically lack trigger context.

Recommended Practices

Practice	Why It Matters
Trigger keywords in description	Helps agents match user intent to the right skill
Anti-triggers ("DO NOT USE FOR")	Dramatically reduces agent confusion and skill collision
Compatibility field	Documents required tools so agents can make informed decisions
Examples section	Shows input → workflow → output patterns for agent learning
Granular reference files	Agents load on-demand; smaller files = less context consumption

Description Format (Recommended)

description: |
  [What the skill does - 1-2 sentences]
  
  USE FOR: [comma-separated trigger phrases]
  
  DO NOT USE FOR: [scenarios that should use other skills instead]

⚠️ Length Consideration: When adding anti-triggers and trigger phrases, ensure the total description stays under 1024 characters. Be concise—use comma-separated phrases rather than full sentences.

---

Full Audit Results

Adherence Scoring

• High (H): Has triggers, anti-triggers, and compatibility in frontmatter
• Medium (M): Has good trigger keywords but missing anti-triggers/compatibility
• Low (L): Basic description without clear triggers or disambiguation

Detailed Assessment

Skill	Triggers	Anti-triggers	Compatibility	Desc Length	Adherence
azure-deploy	✅ Excellent	❌ Missing	❌ Missing	281 ✅	M
azure-create-app	✅ Excellent	❌ Missing	❌ Missing	427 ✅	M
azure-deployment-preflight	✅ Excellent	❌ Missing	❌ Missing	475 ✅	M
azure-postgres	✅ Excellent	❌ Missing	❌ Missing	447 ✅	M
azure-functions	✅ In body	❌ Missing	❌ Missing	136 ⚠️	M
azure-quick-review	✅ Good	❌ Missing	❌ Missing	434 ✅	M
azure-cost-optimization	✅ Good	❌ Missing	⚠️ In body	290 ✅	M
azure-kusto	✅ Good	❌ Missing	❌ Missing	256 ✅	M
azure-keyvault-expiration-audit	✅ Good	❌ Missing	❌ Missing	267 ✅	M
azure-aigateway	✅ Good	❌ Missing	❌ Missing	319 ✅	M
azure-resource-visualizer	✅ Good	❌ Missing	❌ Missing	275 ✅	M
microsoft-foundry	⚠️ Basic	❌ Missing	⚠️ In body	219 ✅	M
skill-authoring	✅ Good	❌ Missing	❌ Missing	238 ✅	M
markdown-token-optimizer	✅ Good	❌ Missing	❌ Missing	245 ✅	M
azure-diagnostics	⚠️ Basic	❌ Missing	❌ Missing	229 ✅	L
azure-security	⚠️ Basic	❌ Missing	❌ Missing	203 ✅	L
azure-security-hardening	⚠️ Basic	❌ Missing	❌ Missing	233 ✅	L
azure-networking	⚠️ Basic	❌ Missing	❌ Missing	213 ✅	L
azure-observability	⚠️ Basic	❌ Missing	❌ Missing	195 ✅	L
azure-storage	⚠️ Basic	❌ Missing	❌ Missing	217 ✅	L
azure-ai	⚠️ Basic	❌ Missing	❌ Missing	217 ✅	L
azure-validation	⚠️ Basic	❌ Missing	❌ Missing	266 ✅	L
azure-nodejs-production	⚠️ Basic	❌ Missing	❌ Missing	220 ✅	L
entra-app-registration	⚠️ Basic	❌ Missing	❌ Missing	221 ✅	L
azure-role-selector	⚠️ Basic	❌ Missing	❌ Missing	231 ✅	L
appinsights-instrumentation	❌ Minimal	❌ Missing	❌ Missing	71 ⚠️	L

---

Example: Good Performer (Current)

azure-deploy - What It Does Well

---
name: azure-deploy
description: Deploy applications to Azure using Azure Developer CLI (azd). USE THIS SKILL when users want to deploy, publish, host, or run their application on Azure. Trigger phrases include "deploy to Azure", "host on Azure", "publish to Azure", "run on Azure", "deploy my app", "azd up", etc.
---

Strengths:

• ✅ Clear statement of what it does
• ✅ Explicit "USE THIS SKILL when..." guidance
• ✅ Lists specific trigger phrases
• ✅ Lowercase hyphenated name
• ✅ Description length (281 chars) leaves room for anti-triggers

What's Missing:

• ❌ No anti-triggers (when NOT to use)
• ❌ No compatibility/prerequisites in frontmatter

---

Example: Poor Performer & How to Fix

appinsights-instrumentation - Current State

---
name: appinsights-instrumentation
description: 'Instrument a webapp to send useful telemetry data to Azure App Insights'
---

Problems:

• ❌ Only 71 characters - too brief for effective disambiguation
• ❌ No trigger phrases - agent doesn't know when to activate
• ❌ No indication of supported frameworks
• ❌ No anti-triggers

appinsights-instrumentation - Recommended Fix

---
name: appinsights-instrumentation
description: |
  Instrument web apps to send telemetry to Azure Application Insights. USE FOR: 
  "add App Insights", "instrument my app", "set up monitoring", "add telemetry", 
  "track requests", "ASP.NET Core telemetry", "Node.js monitoring". DO NOT USE FOR: 
  querying logs (use azure-observability), creating alerts, or cost analysis.
compatibility: Supports ASP.NET Core (.NET 6+), Node.js. Requires App Insights resource.
---

Improvements:

• ✅ Now ~380 characters - informative but under 1024 limit
• ✅ Clear description of purpose
• ✅ Explicit trigger phrases for agent matching
• ✅ Anti-triggers prevent skill collision with azure-observability
• ✅ Compatibility documents supported frameworks

---

Example: Adding Anti-Triggers to Core Skills

For workflow skills that might conflict, anti-triggers are critical:

azure-create-app - Enhanced with Anti-Triggers

---
name: azure-create-app
description: |
  Create Azure-ready app configs with Azure Developer CLI (azd). Generates azure.yaml, 
  Bicep templates, Dockerfiles. USE FOR: "prepare for Azure", "create azure.yaml", 
  "azd init", "scaffold Azure project". DO NOT USE FOR: deploying configured apps 
  (use azure-deploy), validating Bicep (use azure-deployment-preflight), or 
  troubleshooting (use azure-diagnostics).
compatibility: Requires azd CLI, Azure subscription. Optional: Docker CLI.
---

Note: This enhanced description is ~410 characters, well under the 1024 limit while including triggers, anti-triggers, and compatibility.

---

Recommended Examples Section Format

Add this section to SKILL.md files for complex workflows:

## Examples

### Example 1: New Application
**User**: "Create a new API for Azure"

**Workflow**:
1. **Discovery** → No existing code detected
2. **Architecture** → Gather requirements → Recommend Container Apps + Cosmos DB
3. **Generation** → Create Dockerfile, infra/*.bicep, azure.yaml
4. **Output** → Configuration files ready for deployment

**Success Criteria**: azure.yaml exists, Bicep files validate, user can run `azd up`

---

### Example 2: Defer to Another Skill
**User**: "How do Cosmos DB partition keys work?"

**Response**: This is a service-specific question. Defer to **azure-ai** or Azure 
documentation for deep-dive guidance on partitioning strategies.

---

Priority Recommendations

Immediate (High Impact)

1. Add anti-triggers to core workflow skills:

   • azure-deploy
   • azure-create-app
   • azure-deployment-preflight

   These skills have the highest collision potential.

2. Improve Low-adherence descriptions:

   • appinsights-instrumentation (71 chars - too brief)
   • azure-functions (136 chars - triggers in body, not description)
   • azure-security (catalog-style, no triggers)
   • azure-diagnostics (no trigger phrases)

Short-term (Medium Impact)

3. Add compatibility field to skills with specific tool requirements:

   • azure-cost-optimization (requires azqr)
   • azure-kusto (requires Kusto cluster access)
   • microsoft-foundry (requires Foundry resources)

4. Standardize trigger format - Move triggers from body to description for:

   • azure-functions
   • azure-aigateway

Long-term (Nice to Have)

5. Add examples section to complex workflow skills
6. Break large reference files into focused units per the spec guidance

---

Spec Compliance Quick Reference

Requirement	Limit	Current Status
name lowercase + hyphens	64 chars	✅ All compliant
description includes triggers	1024 chars	⚠️ 14/26 have triggers
description includes anti-triggers	1024 chars	❌ 0/26
compatibility field	N/A	❌ 0/26
SKILL.md token budget	<5000 tokens	⚠️ Not audited
Reference files focused	<1000 tokens each	⚠️ Not audited

---

References

• Agent Skills Specification - Official spec
• Anthropic Skills Best Practices - Writing guidance
• anthropics/skills Repository - Reference implementations
• Azure Skills Architecture Discussion - Original architecture proposal
• Detailed Feedback on Frontmatter - Spec compliance review

---

Appendix: Quick Reference Card

# SKILL.md Frontmatter Template (keep description under 1024 chars total)
---
name: skill-name-here           # lowercase, hyphens, max 64 chars, match directory
description: |
  [1-2 sentence description of what the skill does]
  USE FOR: [trigger phrase 1], [trigger phrase 2], [trigger phrase 3]
  DO NOT USE FOR: [scenario] (use other-skill), [scenario] (use another-skill)
compatibility: Requires [tools]. Supports [frameworks]. Optional [extras].
---

Pro tip: Use abbreviated phrases and commas to fit triggers + anti-triggers + compatibility within the 1024 character description limit.