AI agents become more useful when they can access specialized knowledge and repeatable workflows.
A general-purpose agent may know how to answer questions, but a production agent often needs additional domain expertise:
Expense policies
Incident-response procedures
Data-analysis workflows
Compliance rules
Customer-support processes
Internal engineering standards
Business-specific operating procedures
Agent Skills provide a standardized way to package this expertise as reusable instructions, resources, and scripts. Microsoft Agent Framework supports skills in .NET and can now discover them directly from Model Context Protocol (MCP) servers.
This changes the distribution model.
Instead of:
Agent A
|
+-- Skill Files
Agent B
|
+-- Skill Files
Agent C
|
+-- Skill Files
organizations can use:
MCP Skills Server
|
+----------+----------+
| | |
v v v
Agent A Agent B Agent C
A central team can publish a skill once, and multiple agents can discover it through MCP.
This article explores practical production patterns for implementing that architecture safely.
What Is an Agent Skill?
An Agent Skill is a reusable package of domain-specific expertise.
The core file-based representation is typically a SKILL.md file containing metadata and instructions, with optional resources and scripts. Agent Skills use progressive disclosure so that the agent initially receives lightweight skill metadata and loads the full instructions only when the task requires them.
A simple skill can look like:
expense-report/
├── SKILL.md
├── references/
│ └── reimbursement-policy.md
└── scripts/
└── validate-expense.py
The important design principle is that the agent does not need to load everything immediately.
Instead:
Skill Metadata
|
v
Task Matches Skill
|
v
Load SKILL.md
|
v
Read Resources
|
v
Run Approved Scripts
This reduces unnecessary context while keeping detailed domain knowledge available when needed.
Why Serve Skills Through MCP?
Traditional file-based skills require the skill content to be available with the application.
For example:
Application
|
+-- skills/
|
+-- finance/
+-- support/
+-- security/
This creates a distribution problem.
When the skill changes, every application containing that skill may need to be updated.
MCP-based skills provide another model:
Central Skills Server
|
+-- Finance Skill
+-- Security Skill
+-- Support Skill
+-- Data Analysis Skill
Agents discover the available skills from the server.
Microsoft's .NET implementation uses UseMcpSkills to add an MCP skills source to an AgentSkillsProviderBuilder.
Centralized Skill Distribution
A common enterprise architecture is:
Platform Team
|
v
Skills Repository
|
v
MCP Skills Server
|
+-------------+-------------+
| | |
v v v
Finance Agent Support Agent Ops Agent
The platform or domain team owns the skill.
Application teams consume it.
This creates a clear ownership model:
| Component | Typical Owner |
|---|
| Skill content | Domain team |
| MCP server | Platform team |
| Agent | Application team |
| Authentication | Security/platform team |
| Approval policy | Security/application team |
| Monitoring | Platform/SRE |
The exact ownership model should match the organization's operating structure.
Progressive Disclosure
One of the most important Agent Skills concepts is progressive disclosure.
Instead of injecting a large skill into the model context immediately, the framework exposes the skill's metadata first.
Conceptually:
Stage 1
Skill Name + Description
|
v
Stage 2
Load SKILL.md
|
v
Stage 3
Read Required Resources
|
v
Stage 4
Execute Approved Scripts
Microsoft documents this four-stage pattern for Agent Skills to minimize context usage while still providing access to detailed expertise when required.
This is particularly useful when an organization has dozens or hundreds of skills.
Why Progressive Disclosure Matters
Imagine an enterprise agent with:
100 Skills
Loading every skill completely into the prompt would create unnecessary context.
Instead:
100 Skill Descriptions
|
v
User Request
|
v
3 Relevant Skills
|
v
Load Detailed Instructions
This allows the agent to work with a much smaller active context.
It also makes skill discovery more scalable.
MCP Skill Discovery
Microsoft's .NET implementation exposes skills from an MCP server through a discovery document at:
skill://index.json
The framework can then retrieve the skill content through the authenticated MCP connection.
Conceptually:
Agent
|
v
MCP Client
|
v
skill://index.json
|
v
Available Skills
|
v
Selected Skill
|
v
Skill Resources
This is different from simply exposing a collection of MCP tools.
The MCP server is being used as a distribution mechanism for reusable agent expertise.
Two Skill Distribution Models
The current .NET implementation supports two MCP skill entry types:
skill-md
archive
Microsoft documents both models in the current Agent Framework implementation.
skill-md
With skill-md, the MCP server exposes the SKILL.md file and related resources through MCP resources.
The framework retrieves the content as required.
Conceptually:
MCP Server
|
+-- SKILL.md
+-- references/
+-- assets/
The agent loads individual content as needed.
archive
With the archive model, the skill is packaged into an archive such as:
ZIP
TAR
gzip-compressed TAR
The framework downloads the archive and extracts it into a controlled local directory.
Conceptually:
MCP Server
|
v
skill.zip
|
v
Download
|
v
Validate
|
v
Extract
|
v
Local Skill Directory
The two models can support the same overall Agent Skills workflow while using different distribution mechanisms.
Connect a .NET Agent to MCP Skills
The current .NET implementation uses the Microsoft.Agents.AI.Mcp package.
Install the package:
dotnet add package Microsoft.Agents.AI.Mcp --prerelease
Microsoft currently describes the MCP skills API as experimental, so production teams should pin and validate the exact package version they adopt.
Then connect an MCP client:
using Microsoft.Agents.AI;
using ModelContextProtocol.Client;
await using McpClient client =
await McpClient.CreateAsync(
new StdioClientTransport(new()
{
Name = "skills-server",
Command = "dotnet",
Arguments =
[
skillsServerPath,
"--server"
],
}));
The transport in a production deployment may be different.
The important architectural point is that the agent establishes an authenticated MCP connection to the server hosting the skills.
Create the Skills Provider
Once the MCP client is available:
var skillsProvider =
new AgentSkillsProviderBuilder()
.UseMcpSkills(client)
.Build();
The provider becomes the bridge between the MCP skills source and the agent.
Conceptually:
MCP Client
|
v
UseMcpSkills()
|
v
AgentSkillsProvider
|
v
AI Agent
This keeps skill discovery separate from the agent's core instructions.
Add the Skills Provider to an Agent
A simplified agent configuration can look like:
AIAgent agent =
new ChatClientAgent(
chatClient,
new ChatClientAgentOptions
{
Name = "OperationsAgent",
Instructions =
"Use available skills when they are relevant.",
AIContextProviders =
[
skillsProvider
]
});
The exact agent construction depends on the model provider and Agent Framework version.
The architectural pattern remains the same:
Agent
|
+-- Instructions
|
+-- Tools
|
+-- Skills Provider
|
v
MCP Server
Combine Local and MCP Skills
An agent does not necessarily need to choose between local skills and remote skills.
The builder can combine sources.
For example:
var skillsProvider =
new AgentSkillsProviderBuilder()
.UseFileSkill(
Path.Combine(
AppContext.BaseDirectory,
"local-skills"))
.UseMcpSkills(client)
.Build();
This creates a hybrid model:
Agent
|
+--------+--------+
| |
v v
Local Skills MCP Skills
| |
v v
Team-specific Shared enterprise
This can be useful when some expertise belongs to a particular application while other knowledge is centrally governed.
Use Local Skills for Application-Specific Knowledge
A local skill may be appropriate when:
It is tightly coupled to the application.
It changes with application releases.
It should not be shared broadly.
It depends on local resources.
The application team owns the complete lifecycle.
For example:
OrderProcessingAgent
|
+-- Local OrderWorkflowSkill
|
+-- MCP CorporatePolicySkill
This gives teams flexibility without forcing every skill into a central server.
Use MCP Skills for Shared Knowledge
MCP-based distribution becomes more attractive when many agents need the same skill.
Examples include:
Expense Policy
Security Incident Response
Data Classification
Compliance Workflow
Corporate Travel Policy
Instead of:
Agent A -> Copy
Agent B -> Copy
Agent C -> Copy
use:
Central Skill
|
+-- Agent A
+-- Agent B
+-- Agent C
This reduces duplication.
Centralized Updates
One of the strongest benefits of MCP-based skills is centralized distribution.
Suppose the finance team changes a reimbursement policy.
With copied skills:
Update Skill
|
+-- Build Agent A
+-- Build Agent B
+-- Build Agent C
With a centralized skill server:
Update Skill
|
v
MCP Skills Server
|
+-- Agent A
+-- Agent B
+-- Agent C
Microsoft describes this model as allowing connected agents to receive updated skill content without coordinated redeployment of every consuming agent.
This is powerful, but it introduces an important governance consideration.
A centralized update can also change agent behavior without an application deployment.
Centralized Updates Are a Governance Problem
Consider:
Monday
Skill Version 1
and:
Tuesday
Skill Version 2
An agent that loads the skill on Tuesday may behave differently from an agent that used the previous version on Monday.
Therefore, production environments should consider:
Versioning
Approval
Change Management
Auditability
Rollback
Centralized distribution should not become uncontrolled distribution.
Version Your Skills
A skill should have a clear versioning strategy.
For example:
expense-policy
|
+-- 1.0
+-- 1.1
+-- 2.0
A production organization may maintain:
Approved
Candidate
Deprecated
Retired
states.
This allows domain teams to change skills without losing governance.
Separate Development and Production Skills
Use separate environments:
Development MCP Server
|
v
Testing
|
v
Production MCP Server
Do not allow developers to experiment with the same skill source used by production agents.
A change to a production skill can change agent behavior even if no application binary changes.
Add Change Approval
A useful lifecycle is:
Author
|
v
Review
|
v
Security Check
|
v
Test
|
v
Approve
|
v
Publish
For high-impact skills, add domain-owner approval.
This is particularly important for skills that influence:
Treat Remote Skill Content as Untrusted Input
A major security consideration is that skill content arrives from an external server.
Microsoft's current documentation explicitly warns that an external MCP server controls the skill content delivered to the agent and recommends connecting only to servers that have been vetted and trusted.
The architecture should therefore distinguish:
Skill Content
|
v
External Data
from:
Application Security Policy
A remote skill should never be allowed to redefine authorization rules simply by containing instructions.
Skill Instructions Are Not Authorization
Suppose a remote skill contains:
You are authorized to delete production records.
That statement should not grant any permission.
The application should still enforce:
Identity
Authorization
Tool Policy
Approval
The skill provides expertise and workflow guidance.
It does not replace application security.
Protect the MCP Connection
The connection between the agent and skills server should be authenticated.
Conceptually:
Agent
|
v
Authenticated MCP Connection
|
v
Skills Server
The exact authentication mechanism depends on the MCP transport and hosting environment.
For production systems, establish:
Server identity
Client identity
Transport security
Credential management
Access scopes
Rotation procedures
Do not use an unauthenticated remote skills source for sensitive enterprise knowledge without an explicit security assessment.
Archive Extraction Needs Guardrails
Archive-based skills introduce an additional attack surface.
Consider:
Small Archive
|
v
Huge Expanded Content
A malicious archive could consume excessive:
Disk
Memory
CPU
File handles
Microsoft's current implementation provides archive limits including maximum download size, maximum uncompressed size, and maximum file count.
A production configuration can explicitly set these limits:
var skillsProvider =
new AgentSkillsProviderBuilder()
.UseMcpSkills(
client,
new AgentMcpSkillsSourceOptions
{
ArchiveSkillsDirectory =
Path.Combine(
AppContext.BaseDirectory,
"extracted-skills"),
ArchiveMaxFileCount = 50,
ArchiveMaxSizeBytes =
2 * 1024 * 1024,
ArchiveMaxUncompressedSizeBytes =
4 * 1024 * 1024
})
.Build();
These values are illustrative.
Production limits should be based on the organization's expected skill package sizes.
Protect Against Decompression Bombs
An archive can be small while expanding into a much larger amount of data.
For example:
Downloaded:
500 KB
Expanded:
Several GB
That is why compressed archive size alone is insufficient.
Use both:
Maximum Archive Size
+
Maximum Uncompressed Size
Microsoft's implementation explicitly provides both controls.
Limit File Count
A malicious archive could also contain an excessive number of files.
For example:
skill.zip
|
+-- file1
+-- file2
+-- ...
+-- file1000000
Even if the total byte size is within a limit, processing millions of files can create resource pressure.
A file-count limit provides another defense layer.
Remote Skill Scripts Need Strong Controls
Agent Skills can include scripts.
This creates a significant distinction between:
Instructions
and:
Executable Content
A script can have real side effects.
Microsoft's current MCP archive implementation deliberately does not execute scripts bundled in archive-type skills because executable content received from a remote MCP server is treated as untrusted.
This is an important production design principle.
Never Treat Remote Scripts as Automatically Trusted
Avoid an architecture like:
Remote MCP Server
|
v
Download Script
|
v
Execute Automatically
Instead:
Remote Skill
|
v
Inspect
|
v
Policy
|
v
Approval
|
v
Controlled Execution
If scripts need to execute, isolate them and establish explicit trust boundaries.
Approval for Skill Tools
Agent Skills can expose tools such as:
load_skill
read_skill_resource
run_skill_script
Microsoft's current MCP skills implementation requires approval by default for skill tools such as these, providing a human-in-the-loop checkpoint before actions are taken.
This is particularly relevant when skills contain executable workflows.
Skill Content Can Change Agent Behavior
A traditional library changes application behavior through code.
A skill can change agent behavior through instructions.
That means:
Code Deployment
is not the only change that matters.
Also monitor:
Skill Deployment
A change to:
SKILL.md
may alter how an agent interprets tasks.
Therefore, skill content deserves a controlled change-management process.
Build a Skill Registry
A production organization can maintain a registry:
| Skill | Owner | Version | Environment | Risk | Status |
|---|
| Expense Policy | Finance | 2.1 | Production | Medium | Approved |
| Incident Response | Security | 3.0 | Production | High | Approved |
| Data Analysis | Data | 1.4 | Staging | Medium | Testing |
| Deployment | Platform | 4.2 | Production | Critical | Restricted |
The registry becomes the source of governance information.
Define Skill Ownership
Every production skill should have an owner.
Avoid:
Skill
|
v
Unknown Owner
Prefer:
Skill
|
+-- Business Owner
+-- Technical Owner
+-- Security Contact
When a skill becomes inaccurate or vulnerable, someone must be accountable for reviewing it.
Monitor Skill Access
Track:
Skill Discovered
Skill Loaded
Resource Read
Script Requested
Approval Requested
Execution Completed
For example:
Agent: FinanceAgent
Skill: expense-policy
Version: 2.1
Loaded: 14:32
This helps answer:
Which agents are consuming a particular skill?
That becomes important when a skill needs to be withdrawn.
Support Skill Revocation
A centralized system makes revocation possible.
For example:
Security Issue Detected
|
v
Disable Skill
|
v
Agents Stop Discovering It
|
v
Investigate
|
v
Publish Fixed Version
This can be faster than waiting for every consuming application to release a new binary.
However, cached skill content must also be considered.
Understand Caching
Caching can improve performance:
MCP Server
|
v
Skill
|
v
Agent Cache
But caching creates a consistency question.
Suppose:
Server:
Skill 2.0
while an agent still has:
Cache:
Skill 1.9
The production design should define:
Cache Duration
Version Validation
Invalidation
Rollback
The appropriate strategy depends on the framework and deployment architecture.
Use Filtering for Large Skill Catalogs
If an MCP server exposes many skills, an agent may not need all of them.
For example:
Finance Agent
|
+-- Finance Skills
+-- Compliance Skills
while:
Engineering Agent
|
+-- Engineering Skills
+-- Security Skills
Filtering reduces unnecessary exposure and improves discoverability.
The Agent Skills provider supports filtering when composing skill sources.
Avoid Creating One Giant Skill
A common design mistake is:
enterprise-all-skills/
containing every business process.
A better approach is to create focused skills:
expense-policy
incident-response
data-classification
customer-refund
Each skill should have a clear domain and activation condition.
This improves:
Discoverability
Testing
Ownership
Versioning
Security review
Design Good Skill Descriptions
The skill description helps the agent determine when the skill is relevant.
A weak description:
description: Handles finance.
A better description:
description: >
Explains employee expense reimbursement rules,
including eligible expenses, receipt requirements,
approval limits, and international travel policies.
Use when answering employee reimbursement questions.
The description should explain both:
What the skill does
+
When it should be used
Microsoft specifically highlights the importance of the description for skill selection.
Keep SKILL.md Focused
Do not put every reference document directly into the main skill instructions.
Prefer:
expense-policy/
├── SKILL.md
└── references/
├── domestic-travel.md
├── international-travel.md
└── receipt-policy.md
The agent can load the relevant resource only when necessary.
This follows the progressive-disclosure model.
Keep Scripts Separate
If a skill needs scripts:
skill/
├── SKILL.md
├── references/
└── scripts/
├── validate.py
└── transform.py
The instructions can explain when a script is appropriate without embedding the complete implementation into the model context.
This also makes the scripts easier to test and secure independently.
Test Skills Like Software
Do not treat skills as ordinary documentation.
Test:
Skill Discovery
Skill Selection
Instruction Accuracy
Resource Retrieval
Script Behavior
Error Handling
Authorization
Approval
For example:
Input
|
v
Agent
|
v
Skill Selected?
|
+-- Yes
|
v
Instructions Correct?
|
v
Expected Action?
A skill should have test cases before production deployment.
Test Negative Cases
A production skill should be tested against requests that should not activate it.
For example:
Skill:
expense-policy
Test:
"How do I reset my password?"
The expense skill should not be selected simply because it exists.
Negative testing improves skill routing and reduces unnecessary context loading.
Test Conflicting Skills
Consider:
Skill A:
Expense Policy
Skill B:
International Travel Policy
A request such as:
"What is the reimbursement limit for international travel?"
could match both.
Define clear descriptions and precedence rules.
The application should not depend on accidental model behavior to resolve critical policy conflicts.
Security Testing
A production MCP skill system should test:
Unauthorized skill discovery
Unauthorized skill loading
Malicious instructions
Oversized archives
Decompression bombs
Excessive file counts
Path traversal
Malicious resources
Script execution
Credential exposure
Skill substitution
Version rollback
The exact test suite should depend on the threat model.
Common Mistakes
Treating Skills as Static Documentation
Skills can influence agent behavior and therefore require change management.
Trusting Every MCP Server
Remote skill content should come only from vetted sources.
Giving Every Agent Every Skill
Use filtering and separate skill catalogs where appropriate.
Allowing Remote Scripts to Execute Automatically
Executable content requires explicit trust and control.
Ignoring Archive Limits
Archive extraction can create resource-exhaustion risks.
Updating Production Skills Without Review
Centralized distribution makes updates easier but can also make uncontrolled changes more impactful.
Creating Giant Skills
Keep skills focused and modular.
Ignoring Versioning
Behavior can change when skill content changes.
Treating Skill Instructions as Authorization
Security policy must remain outside the model-controlled instruction layer.
Troubleshooting
The Agent Does Not Discover a Skill
Check:
MCP Connection
skill://index.json
Skill Metadata
Skill Description
Provider Configuration
Filtering Rules
The server must expose the expected skill discovery information.
The Agent Discovers the Skill but Does Not Load It
Review the description.
The agent uses skill metadata to determine whether the skill is relevant.
Also verify that the skill's content can be retrieved through the MCP connection.
Archive Skills Are Rejected
Check:
Archive Size
Uncompressed Size
File Count
Extraction Directory
The configured limits may be lower than the archive's requirements. Microsoft provides these safeguards specifically to prevent excessive resource consumption.
Skill Updates Are Not Reflected Immediately
Check caching and discovery behavior.
A centralized skill server does not necessarily mean every agent process instantly reloads every resource.
A Remote Skill Produces Unexpected Instructions
Treat the MCP server and skill content as a trust boundary.
Verify the server, skill version, ownership, and content before allowing it into production.
A Skill Contains a Script
Do not execute it automatically.
Review the script, determine its required permissions, and apply the organization's approval and sandboxing controls.
Production Architecture
A practical enterprise architecture can look like:
+----------------------+
| Skill Repository |
+----------+-----------+
|
v
+----------------------+
| MCP Skills Server |
| |
| skill://index.json |
+----------+-----------+
|
Authenticated MCP
|
+-----------------+-----------------+
| | |
v v v
Finance Agent Support Agent Ops Agent
| | |
+-----------------+-----------------+
|
v
Agent Skills Provider
|
v
Policy / Approval
|
v
Tool Execution
The exact infrastructure can vary, but the responsibilities should remain distinct.
Recommended Skill Lifecycle
A practical lifecycle is:
Author
|
v
Review
|
v
Test
|
v
Security Assessment
|
v
Version
|
v
Publish to Staging
|
v
Validate With Agents
|
v
Approve
|
v
Publish Production
|
v
Monitor
|
v
Update or Revoke
This treats skills as governed software artifacts rather than unmanaged prompt files.
Best Practices
Use MCP skills for knowledge that should be centrally distributed.
Keep application-specific skills local when appropriate.
Use progressive disclosure to reduce unnecessary context.
Give every production skill a clear owner.
Version important skills.
Separate development, staging, and production skill sources.
Authenticate MCP connections.
Vet external MCP servers before use.
Treat remote skill content as untrusted input until reviewed.
Limit archive size, uncompressed size, and file count.
Never automatically execute untrusted remote scripts.
Use approval for sensitive skill operations.
Filter skills so agents receive only relevant capabilities.
Monitor skill discovery and loading.
Maintain rollback and revocation procedures.
Test negative and conflicting skill-selection scenarios.
Keep SKILL.md focused and move detailed material into resources.
Do not use skill instructions as an authorization mechanism.
Frequently Asked Questions
What is the advantage of serving Agent Skills through MCP?
MCP allows skills to be distributed from a centralized server instead of being packaged separately with every agent. This can simplify sharing, centralized governance, and updates across multiple agents.
Can an agent use both local and MCP-based skills?
Yes. The .NET AgentSkillsProviderBuilder can combine multiple sources, including file-based and MCP-based skills.
Are MCP-based Agent Skills production-ready?
The underlying Agent Skills API for .NET was announced as stable in July 2026, but the current MCP skills API is explicitly documented as experimental and subject to change. Teams should therefore validate the exact package and API version before adopting it in production.
Can MCP skills contain scripts?
Skills can contain scripts, but remote executable content requires additional security controls. In the current .NET MCP archive implementation, scripts bundled in remote archives are not executed by the framework.
How does progressive disclosure work?
The agent initially sees lightweight skill metadata, loads the full SKILL.md only when the task matches, then reads additional resources or runs scripts when required.
Should every agent have access to every skill?
No.
Agents should receive only the skills relevant to their responsibilities. Filtering and separate skill catalogs can reduce unnecessary exposure and simplify governance.
Can a skill replace application authorization?
No.
Skills provide instructions and domain expertise. Authentication, authorization, approval, and other security controls must remain enforced by the application and infrastructure.
What happens when a centralized skill changes?
Agents can discover updated skill content from the server without necessarily requiring application redeployment. This is a major advantage of centralized distribution, but it also means organizations should establish versioning, review, testing, and rollback procedures.
Conclusion
MCP-based Agent Skills provide a useful architectural pattern for organizations building multiple AI agents.
Instead of copying domain expertise into every application:
Agent A
|
+-- Skill Copy
Agent B
|
+-- Skill Copy
Agent C
|
+-- Skill Copy
organizations can establish a shared source:
MCP Skills Server
|
+----------+----------+
| | |
v v v
Agent A Agent B Agent C
The current .NET implementation supports both skill-md and archive-based skill distribution, progressive disclosure, local and MCP skill composition, and archive resource limits.
The architectural benefit is clear:
Author once, govern centrally, and make specialized expertise available to multiple agents without duplicating the complete skill package in every application.
However, centralization also creates responsibility.
A production implementation should treat skills as governed software artifacts:
Ownership
+
Versioning
+
Security Review
+
Authentication
+
Resource Limits
+
Approval
+
Monitoring
+
Rollback
The most important distinction is that an Agent Skill provides knowledge and workflow guidance, while the application remains responsible for security and authorization.
Used with that separation of concerns, MCP-based skills can provide a scalable way to distribute enterprise expertise across a growing fleet of .NET AI agents.