Agent Integration with Skills

How AI agents discover, load, and use skills from this repository.

Skill Discovery Mechanism

Agents discover skills through a two-phase process:

Phase 1: Directory Scanning

At startup, agents scan configured skill directories (typically .github/skills/) for folders containing a SKILL.md file:

.github/skills/
├── azure-cosmos-db-py/
│   └── SKILL.md          # Valid skill
├── azure-ai-agents-ts/
│   └── SKILL.md          # Valid skill
├── mcp-builder/
│   └── SKILL.md          # Valid skill
└── some-folder/
    └── README.md         # NOT a skill (no SKILL.md)

Phase 2: Metadata Extraction

For each discovered skill, agents parse only the YAML frontmatter:

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

This metadata is loaded into the agent's context at startup, using ~50-100 tokens per skill.

VS Code / GitHub Copilot Discovery

GitHub Copilot and VS Code agents discover skills via:

1. Workspace scanning: Skills in .github/skills/ are automatically detected
2. Copilot instructions: The .github/copilot-instructions.md file references available skills
3. Agent personas: Files in .github/agents/ (e.g., backend.agent.md) can specify which skills to load

Copilot Configuration Example

In .github/copilot-instructions.md:

## Available Skills

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

Progressive Disclosure

Skills use a three-tier loading strategy to manage context efficiently:

Tier	Content	When Loaded	Token Cost
1. Metadata	name + description from frontmatter	Startup	~50-100 per skill
2. Instructions	Full SKILL.md body	On activation	~500-2000
3. Resources	Files in scripts/, references/, assets/	On demand	Variable

Example: Skill Activation Flow

User: "Create a Cosmos DB service for user data"

Agent thinks:
  → Scans loaded metadata for relevant skills
  → Finds: "azure-cosmos-db-py: Build Azure Cosmos DB NoSQL services..."
  → Activates skill by reading full SKILL.md
  → Follows instructions to implement the service

Skill Loading by Agent Type

Claude Code / Copilot CLI

Filesystem-based agents load skills via shell commands:

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

The skill's location field in the available skills prompt tells the agent where to find it.

Tool-Based Agents

Agents without filesystem access use dedicated tools:

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

Selective Loading Best Practice

Never load all skills at once. This causes context rot:

• Diluted attention across unrelated domains
• Wasted tokens on irrelevant instructions
• Conflated patterns from different SDKs

Do this instead:

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.

Adding Skills to Your Project

Via npx (recommended)

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

Manual Installation

# 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

Skill Naming Convention

Skills use language suffixes for automatic categorization:

Suffix	Language	Example
-py	Python	azure-cosmos-db-py
-dotnet	.NET/C#	azure-ai-inference-dotnet
-ts	TypeScript	azure-ai-agents-ts
-java	Java	azure-cosmos-java
(none)	Cross-language	mcp-builder, skill-creator

This allows agents to filter skills by the project's technology stack.