spboyer

Skills, Tools & MCP Development Guide

A Practical Guide for Building Agent Capabilities

"Skills orchestrate the how. MCP Tools execute the what."

This guide consolidates learnings from building AI agent capabilities for Azure, focusing on the relationship between Skills (workflow orchestration) and MCP Tools (discrete operations). Whether you're creating a new Copilot Skill, building an MCP server, or integrating both, this document provides the architecture patterns, development best practices, and real-world case studies you need to build effective, non-conflicting agent capabilities. The core principle is simple: Skills act as the "brain" that orchestrates complex workflows, while MCP Tools serve as the "hands" that execute individual operations—and Skills should invoke MCP Tools, not duplicate them.

---

spboyer

Agent Skills: References, Recipes & Token Loading Behavior

Overview

This document captures learnings about how Agent Skills handle references/, recipes/, and services/ folders, including token budget implications and best practices based on the AgentSkills.io specification and GitHub Copilot implementation behavior.

Progressive Disclosure Model

Agent Skills use a three-tier loading model to efficiently manage LLM context windows:

spboyer

AI Evals — A Practical, End‑to‑End Overview

This document captures a consolidated, practical understanding of AI evaluations (evals) based on our discussions and the reference material you shared. It is intended as a mental model + system design reference for building, running, and operationalizing evals in modern, agentic AI systems.

---

1. What Are AI Evals?

AI evals are structured mechanisms for measuring, validating, and improving the behavior of AI systems—especially LLM‑powered applications and agents—against explicit goals.

spboyer

Copilot CLI Session Feedback

Session Info

Field	Value
Session ID	6dd7f2b4-e68a-4bc7-9309-619ff917d7ed
Duration	~10 minutes (20:43 - 20:53 UTC)
Date	2026-01-30
OS	Darwin 24.6.0 (macOS)
Terminal	iTerm.app

spboyer

Copilot CLI Session Recording

Session Metadata

Field	Value
Session ID	session-20260130-151839
Model	claude-sonnet-4-20250514
Start Time	2026-01-30T20:18:39
End Time	2026-01-30T20:34:47
Duration	~16 minutes

spboyer

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

---

spboyer

CLI Session Feedback

Date: 2026-01-29 17:08 Session ID: session-20260129-160211 Model: claude-sonnet-4-20250514 Duration: ~65 minutes Working Directory: /Users/shboyer/github/ontology-app

---

spboyer

CLI Session Feedback

Date: 2026-01-28 16:34 Model: claude-sonnet-4-20250514 Duration: 4 minutes Session ID: session-20260128-163354 Working Directory: /Users/shboyer/github/plain-html-test Git Branch: main

Summary

spboyer

Proposed Changes to AGENTS.md

Overview

Based on learnings from the Zava business management system implementation, this document proposes updates to AGENTS.md to improve accuracy, add critical setup steps, and prevent common issues.

---

Change 1: Fix Framework Documentation (CRITICAL)

Current (INCORRECT)

spboyer

{
  "name": "foundry-agent",
  "version": "0.1.0",
  "description": "Simple AI agent with web frontend using Azure AI Foundry",
  "private": true,
  "type": "module",
  "scripts": {
    "dev": "pnpm --filter web dev",
    "build": "pnpm --filter web build",
    "test": "pnpm --filter web test",