Nothing was wrong when Chris came to me.

Good pay. Good life. Ten years at the same company, senior engineering leader in space and deep sea robotics — no crisis, nothing broken. He’d mentally mapped out four more years on autopilot and figured he’d sort out what came next once he retired.

Here’s how he put it: “I had good pay, a good life, and I was enjoying it — but I wasn’t getting much out of it.”

That’s still burnout. It just didn’t come from doing too much.

Two and a half months later he’d left the job he’d held for ten years, moved across the country to be closer to family, and started as an engineering director. Nothing had to break first. He simply got clear on what he actually wanted, and a four-year plan collapsed into now.

I’ve heard hundreds of engineering leaders describe some version of what Chris felt, and almost all of them apologize for calling it burnout. The pay is good. The reviews are good. Nobody’s pulling 70-hour weeks anymore. What am I even complaining about?

Here’s what’s actually happening.

Every role demands a certain level of skill from you. When you’re new, your capability climbs fast to meet it — steep, uncomfortable, exciting. Then you get good at the job you were hired for, the new inputs stop, and the curve flattens.

Stay on that flat part long enough and it doesn’t hold you level. It pulls you back down. Another project like the last project. Another hire like the last hire. You feel like you’re losing your edge, because you are.

The most exhausting run I’ve ever taken down a mountain was the easiest one — a flat cat track in Park City that went on forever and left my calves burning. Ten inches of powder the next day, black diamonds all afternoon, and I had energy for hours. Easy terrain drains you. Your edge gives it back.

You’re not tired because the work is too hard. You’re tired because it stopped asking anything of you.

One caution before you go any further with this: depleted and stuck feel almost identical from the inside, and they need opposite responses. If you’re running on empty from an unsustainable workload or a culture that’s grinding you down, what you need first is recovery, not a new challenge. This episode is for the other version — the one where you have plenty left in the tank and nothing worth spending it on.

If that’s you, the real question is which one you’ve outgrown: the role, the company, or the direction. In this episode I walk through how to tell the difference, the one question that decides whether you push inside your company or pivot out of it, and three small experiments you can run instead of waiting for clarity to arrive on its own. The free Next Move Experiment below has the full diagnostic plus all three, so you can work it through on paper before you make any giant career decision.

You are not stuck with the career you designed five years ago.

The Happy Engineer Podcast

Bored at Work but Exhausted? That’s Still Burnout

LISTEN NOW

Back to ALL EPISODES

 

The post Bored at Work but Exhausted? That’s Still Burnout appeared first on OACO.

Directions on Microsoft built its own AI Assistant to help with Microsoft technology and licensing queries. Analysts Barry Briggs and Andrew Snodgrass share experiences and lessons learned with Mary Jo Foley.



Download audio: https://www.directionsonmicrosoft.com/wp-content/uploads/2026/09/season5ep14atlasai.mp3

This week, Mistral announced it raised €3 billion in a Series D funding round, pushing its post-money valuation past €21 billion. With the influx of cash — $3.5 billion in US dollars — it plans to expand its frontier research, scale compute capacity for model training, and grow its infrastructure. 

Where Mistral’s allocating new funds suggests what the French AI company is betting on for the future of AI power: open-weight models can only do so much if the compute and infrastructure underneath remain concentrated among a few key players. 

Open weights can only go so far

So far, model superiority has been a major factor in who gets to rule the AI roost. Some open-weight advocates have been touting open-weight models as a way to combat this concentration by giving developers more choice over the models they use — and a way to escape dependence on proprietary APIs. This way, rather than relying exclusively on one provider’s model, developers can adapt open-weight models for their own use.

The catch? Running powerful models takes enormous amounts of compute. Training frontier models — and serving them at high volume — requires compute capacity concentrated among a relatively small number of labs, chip suppliers, and infrastructure providers.

For his part, Dario Amodei, CEO and co-founder of Anthropic, challenged that vision for open-weight models last month in an exchange on X, where he wrote that open weights “are nowhere near a sufficient solution because they simply shift the concentration somewhat to those with the most compute and chips.” 

1/2 Thanks Gavin for an especially thoughtful exchange. I don't usually spend much time on social media but I wanted to engage here because it really brings out the heart of an important conversation.

First, on regulation, I think that “either concentrate it in the hands of a… https://t.co/2W6vWJAE8Y

— Dario Amodei (@DarioAmodei) August 15, 2026

But the expansion plans Mistral briefly outlines in its funding news suggest there’s a different way to combat that dominance: Don’t stop at opening the model. Build more of the stack, instead. 

So Mistral is building more of the stack

“Mistral is the only AI company in the world building the full stack required to answer that question,” claims the French AI company, writing about how organizations can take advantage of AI for mission-critical needs without giving up control of the infrastructure and intelligence loop.

For Mistral, building that stack means developing open-weight models and the infrastructure and compute capacity on which those models run, along with the downstream products that bring them into production. And with a new €3B in the bank — led by Samsung Electronics, with Scaleup Europe Fund, managed by EQT, and existing investor PSG Equity as co-leads — parts of that stack will keep expanding. 

Looking ahead, Mistral says it aims to use its full stack and open approach to AI to free customers from dependence on a single vendor’s roadmap, pricing, and availability so they can build on its stack “without exposing their most valuable data, workflows and institutional knowledge to anyone outside their walls.” 

That addresses one piece of Amodei’s critique of open-weight models. Because Mistral’s stack includes not only the models but also the compute, infrastructure, and production layer, its open-weight strategy depends less on rival-controlled infrastructure. 

It’s been moving this way for a while 

Launched three years ago, Mistral has made a name for itself by releasing open-weight models. Interestingly, it’s also been expanding into the infrastructure layer as of late. 

Last month, the company said it would begin hosting third-party open models, putting the likes of GLM-5.2 from China’s Z.ai on the same infrastructure as its own models — another move that suggests it sees the infrastructure layer as an increasingly important part of the AI race. 

In July, Arthur Mensch, co-founder and CEO, Mistral, added to the case for more openness by taking to LinkedIn to express his concerns about dependence on closed-model providers, writing: 

“Of course you need to use open-source models if you’re an enterprise leader. Closed-model providers, that are now forcing data retention, are gaining immense leverage on your business if you don’t.” 

Bigger picture, it looks like Mistral’s betting that whoever ends up ruling the AI roost will need more than the best-performing model; they’ll also need to control enough of the surrounding infrastructure to give customers choices about which models they want to use and on what infrastructure. 

Whether this can meaningfully shift AI power, though, remains to be seen. 

The post Mistral wants open-weight AI to compete at the frontier. It just raised $3.5 billion to do it. appeared first on The New Stack.

When several Visual Studio instances are open, identifying the right one becomes a surprisingly repetitive task. Two windows showing different checkouts of the same solution can look almost identical. Reading the title works, but a small visual cue is easier to spot.

That's the problem behind Solution Colors. Inspired by the Peacock extension for VS Code and a Visual Studio feature request, it associates a color with a solution or folder without replacing your editor theme.

Give each solution a visual identity

Right-click the solution in Solution Explorer, choose Set Solution Color, and select a color. The predefined choices use the familiar document-tab color palette, and Custom... opens a color picker when you want something different. Open Folder workspaces are supported too.

The color can appear around the window, behind the solution name in the title bar, and in taskbar thumbnails. Taskbar icon overlays are also available, with the documented limitation that taskbar items need to be ungrouped. You can choose the surfaces that help you and leave the others alone.

Under Tools > Options > Environment > Fonts and Colors > Solution Colors, you can adjust border placement and thickness or enable automatic color assignment. Automatic mode selects from the palette using a hash of the solution path; explicitly saved colors take precedence.

A small extension with two kinds of integration

The project is an in-process VSIX built with the Visual Studio SDK and the Community Toolkit. Its ToolkitPackage registers commands and listens for solution and folder open/close events. The menu lives in a VSCT command table, while the color commands share a generic BaseCommand<T> implementation.

That is the conventional part. Coloring the existing window chrome is less conventional.

The implementation searches the WPF visual tree for named shell elements such as BottomDockBorder and PART_SolutionNameTextBlock. It changes brushes and border thickness rather than introducing a new tool window. For the title label, it also uses reflection to access the foreground property and Visual Studio's ColorUtilities.CompareContrastWithBlackAndWhite to choose black or white text.

This is an important tradeoff for extension authors: finding an element in the shell's visual tree is not the same as having a dedicated, stable extensibility contract for it. Names and structure can change. The lookup code is worth isolating, and these integrations need testing against the Visual Studio versions you support.

Decoration must not get in the way

One revealing detail is hit testing. The extension disables hit testing on the non-top borders it colors so they don't intercept mouse input. But it deliberately leaves the top element alone: MainWindowTitleBar contains interactive UI, and disabling hit testing there would also block menu interaction.

That distinction is easy to overlook when the feature appears to be "just a border." Decorative changes still participate in layout and input routing.

Timing matters too. Package initialization does not guarantee that every shell element is ready. The startup path makes a bounded series of colorization attempts, with delays between them. UI changes switch to the main thread, while Git branch file reads are dispatched to a background task.

Taskbar integration uses a different mechanism: WPF's TaskbarItemInfo, noninteractive ThumbButtonInfo entries, and an overlay image. There is no need to reach into the taskbar's visual tree.

Branch colors are a state problem, not just a brush problem

The settings offer one color across branches, a separate color per branch, or a combined gradient. Assignments are stored as simple branch:color lines in a color.txt file, normally under the solution's .vs directory. An option puts the file in the root instead. The parser also accepts the older single-color format.

There is a compatibility detail worth knowing: the implementation uses the literal key master for its shared/base color. That is an internal convention, not automatic discovery of a repository's configured default branch.

A recent fix illustrates why separating decisions from rendering helps. In per-branch mode, a branch with an explicit color should remain colored even when no base color has been assigned. The code now expresses the removal decision in ShouldRemoveColorization, with focused unit tests covering the different modes and automatic-color behavior.

That is a useful pattern beyond this extension: put the state rules in a testable method, then let the UI code apply the result. You shouldn't need to launch an experimental Visual Studio instance just to verify whether a missing base setting overrides a branch-specific one.

Try it, or borrow the ideas

If you regularly juggle Visual Studio windows, install Solution Colors from the Marketplace and give your solutions a visual identity.

If you're building extensions, browse the source on GitHub. Start with SolutionColorsPackage for the lifecycle, ColorHelper for the shell integration, and the tests for the branch-color rules. A few pixels of color turn out to be a useful case study in extending the IDE without getting in the user's way.

For over two decades, the API Gateway has been one of the most important pieces of modern application architecture. Whether you’re building a mobile application, a SaaS platform, or a collection of microservices, chances are every request from your users passes through an API Gateway before it reaches your backend.

But something has changed.

The clients making requests are no longer just browsers and mobile apps. Increasingly, they’re AI agents, and AI agents behave very differently from traditional software. As a result, we are beginning to see the emergence of a new architectural component called the Agent Gateway.

To understand why it is needed, it helps to trace how gateways have evolved.

The API Gateway: A Reverse Proxy with API-Specific Capabilities

When I think about gateways in software, the first concept that comes to mind is a proxy.

A proxy is an intermediary between two systems. A forward proxy acts on behalf of a client, while a reverse proxy sits in front of one or more servers and acts on their behalf.

At its core, an API Gateway is a reverse proxy with capabilities designed specifically for managing APIs. That may sound like an oversimplification, but it is a useful mental model.

An API Gateway sits between API consumers and the services that fulfill their requests.

Imagine a user opening a food-delivery application and tapping Order food. The application sends a request through an API Gateway, which routes it to the appropriate backend services.

The gateway may handle routing and load balancing, authentication and authorization, rate limiting and quotas, TLS termination, Protocol translation, Request and response transformation, Caching, Logging, tracing, and observability, API versioning and lifecycle policies and many more.

Most importantly, the API Gateway makes a fundamental assumption about its client:

The client already knows which API it wants to call.

A mobile app doesn’t ask “How do I order food?”. Its developers have already encoded that logic into the application. The client knows that it needs to send a request such as:

The API Gateway’s job is to authenticate, govern, route, and reliably deliver that request at scale.

AI Agents Don’t Work That Way

Now imagine replacing that mobile app with an AI agent. Instead of receiving a predetermined instruction to call a specific endpoint, the agent receives a goal. “Book me a hotel near the conference venue under $250.”

To accomplish this, the agent might need to:

• Identify the conference venue
• Search multiple hotel providers
• Compare prices and cancellation policies
• Read reviews
• Calculate travel time
• Check room availability
• Ask the user to clarify missing preferences
• Reserve the selected room
• Send a confirmation

The exact sequence is not necessarily known in advance. It may change depending on the information returned by each tool, but the agent must repeatedly decide:

• Which tools are available?
• Which tool is appropriate for this step?
• What arguments should I send?
• Do I have enough information to proceed?
• Should I retry a failed operation?
• Should I select a different provider?
• Is user approval required?
• Has the overall goal been completed?

This is fundamentally different from traditional applications. Instead of executing workflows that developers have already mapped out. An AI agent determines parts of the workflow dynamically at runtime. That flexibility is what makes agents powerful. It is also what makes them difficult to control.

The LLM Gateway: API Gateway Capabilities for Model Traffic

As large language models became widely adopted, organizations encountered a new set of production concerns. Applications were no longer calling only conventional APIs. They were also sending prompts to multiple model providers, receiving probabilistic outputs, consuming tokens, and incurring variable costs.

This led to the emergence of the LLM Gateway, sometimes called an AI Gateway.

An LLM Gateway applies familiar gateway patterns to model inference traffic. It can centralize capabilities such as:

• Model and provider routing
• Fallbacks and retries
• Token-based rate limits
• Prompt and response logging
• Cost and usage tracking
• Semantic caching
• Prompt guardrails
• PII and secret redaction
• Content filtering
• Load balancing across models
• Latency and quality monitoring

For example, an LLM Gateway might route simple classification requests to a smaller, less expensive model while sending complex reasoning tasks to a more capable one. It might switch providers when a model is unavailable, enforce a team’s monthly budget, or redact sensitive information before a prompt leaves the organization.

These are important production capabilities, but the primary object being managed is still the model request.

An LLM Gateway helps an application use models reliably, securely, and cost-effectively.

An agent, however, depends on much more than a model.

The MCP Gateway: Managing Access to Tools and Context

Anthropic introduced the Model Context Protocol, or MCP, in November 2024 as an open standard for connecting AI applications to external tools and data sources. Since then, MCP has become an important part of the agentic ecosystem.

Instead of creating a proprietary integration for every agent and every external system, developers can expose capabilities through MCP servers. An agent can then use those servers to search a database, retrieve a document, create an issue, send a message, query an API, or perform another action.

However, standardizing the protocol does not automatically solve the operational problems involved in managing a large tool ecosystem.

Different MCP servers may represent different security boundaries. They may depend on separate authorization servers, credentials, scopes, network policies, and downstream APIs. One MCP server may use an API key for authentication, while another uses OAuth 2.0, and another OAuth 2.1 + DCR. This makes centrally managing auth difficult. The MCP specification recommends OAuth-based mechanisms, but deployment models and implementation maturity can still vary across servers and a lot of MCP servers today are not fully complaint with the spec.

As organizations connect agents to tens or hundreds of tools, several challenges emerge:

• How are users and agents authenticated consistently?
• Which MCP servers should each agent access?
• Which tools within a server are permitted?
• Where are credentials stored and exchanged?
• How can tool calls be audited centrally?
• How do you revoke access across many servers?
• How do you prevent sensitive tool results from leaking into prompts?
• How do you avoid loading hundreds of irrelevant tool definitions into the model’s context?

The final problem is particularly important. Tool definitions and tool results consume context. As the number of available tools grows, blindly exposing all of them to the model can increase token consumption, latency, and the likelihood that the model selects the wrong tool. Tool discovery and selective loading therefore become operational concerns, not merely prompt-engineering concerns.

An MCP Gateway provides a centralized control point between MCP clients and MCP servers.

Depending on the implementation, it can provide:

• Centralized authentication and credential brokering
• Authorization and scope enforcement
• MCP server registration and discovery
• Tool filtering
• Tool namespacing
• Request and response inspection
• Audit logging
• Rate limiting
• Policy enforcement
• Tool-definition caching
• On-demand tool discovery
• Protection against malicious or untrusted tool output

The MCP Gateway governs access to MCP-based capabilities. But MCP servers are still only one part of an agentic system.

The Agent Gateway

An AI agent may depend on some or all of the following:

• One or more large language models
• APIs
• MCP servers and tools
• Databases and knowledge stores
• Short-term and long-term memory
• Other specialized agents
• Human approval workflows
• Identity and policy systems

An Agent Gateway is an intelligent middleman between an AI Agent, and all the components it relies on. Agent Gateways provide a centralized control plane and enforcement point across these interactions. These can include, LLMs, MCP Tools, Memory, other Agents, and of course, an API.

Like an API Gateway, an Agent Gateway may proxy requests, enforce access controls, apply policies, limit traffic, and collect telemetry.

Like an LLM Gateway, it may govern model selection, token usage, prompts, responses, safety controls, and cost.

Like an MCP Gateway, it may manage tool discovery, credentials, permissions, and tool invocation.

But its scope is broader than any one of those categories. It governs the agent’s interactions as part of a complete runtime workflow.

An Agent Gateway may be responsible for:

• Establishing and propagating agent identity
• Discovering and exposing relevant tools
• Enforcing policies before and after tool calls
• Routing requests across models, APIs, tools, and other agents
• Redacting sensitive data
• Requiring human approval for high-risk actions
• Applying budget, token, and execution limits
• Detecting loops and abnormal behavior
• Recording end-to-end traces
• Coordinating access to memory and context
• Evaluating whether an action is permitted in the current state
• Terminating an agent run when safety or cost thresholds are exceeded
• …and many more.

Why Agentic Systems need a Gateway

Agent identity is still an unsolved operational problem

Traditional API security is usually based on a relatively clear identity chain.

A user authenticates to an application. The application receives a token. The token identifies the user, the application, or both. Backend services validate that identity and enforce the corresponding permissions.

Agents complicate this model. An agent may be acting on behalf of a user, running as an independent workload, invoked by another agent, operating across multiple sessions, delegating work to subagents, using shared infrastructure, or even calling tools that require different identities.

When an agent invokes a tool, which identity should the tool evaluate? Is it the identity of the user, the application, the agent, or the organization? What happens when one agent delegates a task to another? Which permissions should be transferred, and for how long?

Without a consistent identity and delegation model, systems tend to fall back to shared API keys or overly broad service accounts. That makes least-privilege authorization difficult and weakens accountability.

An Agent Gateway can provide a consistent point for establishing agent identity, propagating user context, exchanging credentials, narrowing scopes, and recording who or what initiated each action.

Agents expand the security boundary

A traditional chatbot primarily generates text. An agent can generate text and then use that text to take action. It may send an email, modify source code, issue a refund, retrieve customer records, deploy an application, or initiate a payment.

This creates risks that do not exist in an ordinary API traffic:

• Prompt injection can influence tool selection.
• Untrusted tool output can manipulate subsequent reasoning.
• A model can generate valid but unsafe tool arguments.
• An agent can combine individually harmless operations into a harmful sequence.
• Credentials may cross boundaries between users, agents, tools, and models.
• A compromised tool can return instructions disguised as trusted data.

Authentication alone does not solve these problems. A request can be properly authenticated and still be unsafe. Agentic systems need policies that evaluate more than the caller and endpoint. They may need to consider the user’s intent, the selected tool, the arguments, the current workflow state, the sensitivity of the resource, and the potential consequence of the action.

An Agent Gateway can enforce controls at these boundaries. For example, it might allow an agent to search financial transactions but require human approval before issuing a refund.

Agents introduce stateful workflows

An individual LLM request is generally stateless i.e the model receives an input and produces an output.

An agentic workflow is stateful and may maintain conversation history, a task plan, previous tool results, user preferences, intermediate artifacts, approval status, retry counts, budget consumed, and long-term memories.

This does not mean the gateway itself must store all agent memory. In many architectures, memory will remain in dedicated databases, vector stores, or state-management services. The gateway’s role is to govern access to that state.

It can determine which agent may read or write a memory, what context may be sent to a model, which information must be redacted, and whether state from one user or session can be reused in another. This distinction matters. An Agent Gateway does not need to become the memory database.

It needs to become the policy and visibility layer through which memory is accessed.

Agentic observability is difficult

API observability typically focuses on individual requests, such as which endpoint was called, how long it took, what status code was returned, and which service handled the request.

LLM observability adds another set of questions, including which model was used, how many tokens were consumed, what the request cost, and whether a guardrail was triggered. Agentic observability must connect all of these events into a coherent execution trace.

For a single user request, an agent might make several model calls, invoke multiple tools, query memory, delegate to another agent, retry failed operations, and wait for human approval.

When the final result is wrong, it is not enough to know that one API returned a 200 OK; you need to understand the goal the agent received, the plan it formed, the tools available, why it selected a particular tool, which arguments it generated, what the tool returned, how that result affected the next decision, where time and tokens were spent, which policy decisions were applied, which user, agent, and credential were involved, and where the workflow failed.

An Agent Gateway can capture these interactions at a shared boundary and correlate them into an end-to-end trace.

Autonomous execution needs limits

A traditional application usually has bounded execution paths, but an agent can keep planning, calling tools, evaluating results, and retrying until it reaches a stopping condition. Without clear limits, this can lead to long or infinite loops, repeated tool calls, runaway token usage, escalating costs, duplicate side effects, cascading agent-to-agent delegation, and repeated failed authentication attempts.

Conventional request-per-second limits are not enough for agentic systems. They need controls that account for the full workflow, including token and cost budgets, tool-call volume, delegation depth, execution time, retries, concurrency, and the sensitivity of the requested operation.

The Agent Gateway can enforce these limits across the entire execution, rather than evaluating each request in isolation.

From Managing Requests to Governing Intent

API Gateways were designed for a world in which applications knew which endpoints to call.

LLM Gateways emerged when model inference introduced new routing, cost, privacy, and safety requirements.

MCP Gateways emerged as agents gained access to a growing ecosystem of tools and context providers.

Agent Gateways are the next step in that evolution.

They are needed because the unit being governed is no longer only an API request, a model invocation, or a tool call. It is an agentic execution, a sequence of decisions and actions taken dynamically to achieve a goal. That shift alone changes the role of the gateway.

The gateway is no longer concerned only with:

Is this client allowed to call this endpoint?

It must also help answer:

Is this agent allowed to take this action, with this tool, using this identity, in this context, at this point in the workflow?

APIs are not disappearing. They remain the foundation on which agents act, but the clients consuming them are changing. They can reason, choose tools, delegate work, maintain state, and take consequential actions.

As clients evolve, the gateway must evolve with them.

Building the Future: Fabric Gateway

At Postman, we are building what we believe is the next generation of this architecture, we call it the Fabric Gateway.

Fabric Gateway is designed to bring together the capabilities discussed in this article – API governance, model routing, MCP tool management, and agent-level policy enforcement, into a unified control plane for agentic systems.

Our goal is simple: make it possible to safely run agents in production without sacrificing flexibility, speed, or developer experience.

We are currently opening up early access to teams that are building agentic applications and want to help shape this new category.

If you are exploring agents in production, or thinking about how to govern them at scale, we would love to hear from you.

Join the early access and help define what the Agent Gateway should become.

The post Agent Gateway: The Next Evolution of the API Gateway appeared first on Postman Blog.

tl;dr
Imagine an AI assistant in your company that can write emails, check expense reports, and run CI pipeline steps — but it has every capability baked into one giant prompt. It’s slow, expensive, brittle, and dangerously able to access systems it shouldn’t. Now imagine the same assistant composed from many small, well-documented, auditable “skills”: a policy-checker skill for expenses, an email-composer skill, a CI-invoker skill. Each skill advertises a compact summary the agent sees up-front and provides richer instructions or safe code only when needed. That’s the difference agent skills make: modularity, safety, and maintainability.

In this post you’ll get:

• A practical definition of agent skills and why they matter.
• The SKILL.md packaging convention and how agents discover and use skills.
• Runnable C# patterns for semantic (prompt) functions and native (C#) functions that agents can call.
• A small retrieval-augmented (RAG) example (embeddings + local vector store).
• Concrete operational guidance: progressive disclosure, security, testing, telemetry and CI.

What are agent skills?
A skill is a small, focused package that gives an AI agent a specific capability. A skill typically contains:

• Metadata (name, summary, inputs/outputs, examples).
• A description of what the skill is for
• One or more prompt templates (semantic functions).
• Optional native code (API wrappers, scripts) that the agent can call.
• Optional supporting assets (examples, test cases).

Why skills matter

• Modularity & reuse: Package common workflows once and share them across agents and projects.
• Progressive disclosure: Agents initially see only compact summaries (low-cost), fetching full prompts or code only when needed (reduced context bloat).
• Interoperability: Emerging conventions (SKILL.md / skill folders and plugin metadata) let skills be discovered and loaded by different frameworks.
• Testability & governance: Skills can be versioned, tested, audited, and signed independently from orchestration code.

SKILL.md: the portable skill package
A commonly adopted pattern is a small folder that contains a single SKILL.md file (YAML or structured text) that describes the skill plus optional prompt, code and example files. This single file is how registries, marketplaces and agent orchestrators discover and reason about a skill.

A minimal skill folder:

• DocumentSummarizer/
• SKILL.md
• prompts/
  • summarize.txt
• examples/
  • example1.txt

Example SKILL.md (YAML-like):
name: Document Summarizer
summary: Summarize documents into a single short paragraph.
description: |
The Document Summarizer skill produces a concise, factual paragraph that preserves
key facts and avoids hallucination. Use it for internal reports and documentation.
inputs:

• name: input
  type: string
  description: The text to summarize.
  outputs:
• name: summary
  type: string
  description: One-paragraph summary.
  prompts:
• file: prompts/summarize.txt
• prompts/summarize.txt:
• Summarize the text below in one short paragraph, focusing on main factual points. {{input}}

Two broad kinds of functions inside skills

• Semantic (prompt) functions: natural language templates packaged as callable functions. These send text to the LLM and return a string output.
• Native (plugin) functions: compiled code (C#, Python, HTTP endpoints) that expose controlled side-effecting operations (call an API, query a DB, create a ticket).

How agents use skills (discovery → execution)

1. Discovery: Agent finds available skill folders (local, registry, or marketplace).
2. Visibility: Agent sees compact metadata (name, summary, I/O).
3. Planning: Agent decides if a given skill is relevant to the user request.
4. Progressive disclosure: Agent loads the full prompt or code only on demand.
5. Execution: Agent calls a semantic function (LLM) or a native function (HTTP or SDK call).
6. Audit: Invocation logged and reviewed.

C# approach: two patterns

• Manual skill loader (framework-agnostic, runnable): show how to load SKILL.md, create prompt functions and call an LLM endpoint directly from C#. This is portable and doesn’t require a specific SDK.
• SDK-based integration (Microsoft Agent Framework): map skills to a Kernel and register C# methods as callable functions. I’ll explain the SDK approach conceptually and how to adapt the manual loader to it.

Runnable sample: a small console app that demonstrates semantic and native skills
This sample is framework-agnostic and uses HTTP calls to a standard LLM API (OpenAI-style). Files provided:

• AgentSkillsSample.csproj
• Program.cs
• SkillLoader.cs
• Models/SkillDefinition.cs
• Skills/DocumentSummarizer/SKILL.md
• Skills/DocumentSummarizer/prompts/summarize.txt
• Skills/FinanceSkill.cs (native skill)

Project file: AgentSkillsSample.csproj
Exe net7.0 latest

Notes: YamlDotNet reads SKILL.md, Serilog logs audit events, Newtonsoft.Json serializes HTTP payloads. You can substitute other libs (System.Text.Json) if you prefer.

Note: This code was generated by Copilot and has not been fully tested. Caveat Programmer!

using System.Collections.Generic;
public class SkillDefinition
{
   public string Name { get; set; }
   public string Summary { get; set; }
   public string Description { get; set; }
   public List<SkillIO> Inputs { get; set; } = new();
   public List<SkillIO> Outputs { get; set; } = new();
   public List<PromptFile> Prompts { get; set; } = new();
}

public class SkillIO
{
   public string Name { get; set; }
   public string Type { get; set; }
   public string Description { get; set; }
}

public class PromptFile
{
   public string File { get; set; }
}

Skill loader: SkillLoader.cs

using System;
using System.IO;
using YamlDotNet.Serialization;
using YamlDotNet.Serialization.NamingConventions;

public static class SkillLoader
{
// Loads SKILL.md (YAML) and returns SkillDefinition; progressive disclosure: never load prompt files here
public static SkillDefinition LoadSkillMetadata(string skillFolder)
{
var path = Path.Combine(skillFolder, "SKILL.md");
if (!File.Exists(path)) throw new FileNotFoundException("SKILL.md not found", path);   
 var yaml = File.ReadAllText(path);
    var deserializer = new DeserializerBuilder()
        .WithNamingConvention(CamelCaseNamingConvention.Instance)
        .Build();

    var def = deserializer.Deserialize<SkillDefinition>(yaml);
    return def;
}

// Load a prompt file only when invoked
public static string LoadPrompt(string skillFolder, string promptFile)
{
    var path = Path.Combine(skillFolder, promptFile);
    return File.Exists(path) ? File.ReadAllText(path) : throw new FileNotFoundException(promptFile);
}
}

using System;

[AttributeUsage(AttributeTargets.Method)]
public class SkillFunctionAttribute : Attribute
{
   public string Name { get; set; }
   public SkillFunctionAttribute(string name = null) { Name = name; }
}

using System.Threading.Tasks;

public class FinanceSkill
{
[SkillFunction("GetExchangeRate")]
public Task GetExchangeRateAsync(string currency)
{
// Replace with real API call; this is a stub for demo
return Task.FromResult(currency.ToUpper() switch
{
   "EUR" => "1 USD = 0.92 EUR",
   "JPY" => "1 USD = 150 JPY",
   _ => "1 USD = 1 UNKNOWN"
});
}
}

Native skill attribute and example: Skills/SkillFunctionAttribute.cs and Skills/FinanceSkill.cs

using System;
using System.IO;
using System.Linq;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;
using Serilog;

class Program
{
static readonly string OPENAI_API_KEY = Environment.GetEnvironmentVariable("OPENAI_API_KEY");
static readonly HttpClient http = new HttpClient();

static async Task Main()
{
    Log.Logger = new LoggerConfiguration()
        .WriteTo.Console()
        .CreateLogger();

    if (string.IsNullOrEmpty(OPENAI_API_KEY))
    {
        Console.WriteLine("Set OPENAI_API_KEY environment variable.");
        return;
    }

    // 1. Discover skills (metadata only)
    var skillFolder = Path.Combine(Directory.GetCurrentDirectory(), "Skills", "DocumentSummarizer");
    var meta = SkillLoader.LoadSkillMetadata(skillFolder);
    Console.WriteLine($"Discovered skill: {meta.Name} - {meta.Summary}");

    // 2. Example: call semantic (prompt) function (progressive disclosure: load prompt on demand)
    var promptTemplate = SkillLoader.LoadPrompt(skillFolder, meta.Prompts.First().File);
    var inputText = File.ReadAllText(Path.Combine(skillFolder, "examples", "example1.txt"));
    var prompt = promptTemplate.Replace("{{input}}", inputText);

    Console.WriteLine("Calling LLM for summary...");
    var summary = await CallChatCompletionAsync(prompt);
    Console.WriteLine("Summary:\n" + summary);

    Log.Information("SkillInvocation: {@skill} {@inputLength}", meta.Name, inputText.Length);

    // 3. Example: call native skill directly via reflection
    var finance = new FinanceSkill();
    var method = typeof(FinanceSkill).GetMethods()
        .FirstOrDefault(m => m.GetCustomAttributes(false).Any(a => a.GetType().Name == "SkillFunctionAttribute"));
    if (method != null)
    {
        var resultTask = (Task<string>)method.Invoke(finance, new object[] { "EUR" });
        var rate = await resultTask;
        Console.WriteLine("Exchange rate (from native skill): " + rate);
        Log.Information("NativeSkillInvocation: {@skill}", "Finance:GetExchangeRate");
    }
}

// Minimal OpenAI Chat Completion HTTP call (simple completion flow). Adjust model as desired.
static async Task<string> CallChatCompletionAsync(string prompt)
{
    var request = new
    {
        model = "gpt-4o-mini",
        messages = new[] { new { role = "user", content = prompt } },
        max_tokens = 400
    };

    var req = new HttpRequestMessage(HttpMethod.Post, "https://api.openai.com/v1/chat/completions");
    req.Headers.Add("Authorization", $"Bearer {OPENAI_API_KEY}");
    req.Content = new StringContent(JsonConvert.SerializeObject(request), Encoding.UTF8, "application/json");

    var resp = await http.SendAsync(req);
    resp.EnsureSuccessStatusCode();
    var json = await resp.Content.ReadAsStringAsync();
    dynamic data = JsonConvert.DeserializeObject<dynamic>(json);
    // Extract the assistant content safely
    var text = (string)data.choices[0].message.content;
    return text.Trim();
}

How this demonstrates key patterns

• Progressive disclosure: SKILL.md metadata is loaded up-front; prompt files only when the agent invokes a skill.
• Semantic function: the prompt template is a first-class asset loaded and passed to the LLM.
• Native function: a C# method annotated with SkillFunctionAttribute is discoverable and callable by the orchestrator (the agent’s planner) via reflection.

RAG + embeddings: a minimal in-memory example
Real RAG pipelines use a vector DB (Pinecone, Weaviate, FAISS) and an embedding endpoint. For a compact demo we’ll:

• Call an embedding endpoint for documents and queries.
• Store vectors in memory.
• Compute cosine similarity for top-k retrieval.
• Pass retrieved texts into a semantic skill.

Embedding call (OpenAI-style)

static async Task GetEmbeddingAsync(string text)
{
var request = new { model = "text-embedding-3-small", input = text };
var req = new HttpRequestMessage(HttpMethod.Post, "https://api.openai.com/v1/embeddings");
req.Headers.Add("Authorization", $"Bearer {OPENAI_API_KEY}");
req.Content = new StringContent(JsonConvert.SerializeObject(request), Encoding.UTF8, "application/json");
var resp = await http.SendAsync(req);
resp.EnsureSuccessStatusCode();
dynamic data = JsonConvert.DeserializeObject(await resp.Content.ReadAsStringAsync());
var vector = data.data[0].embedding.ToObject();
return vector;
}

Simple in-memory vector store (pseudo code)

• Store: List<(string id, string text, float[] vector)>
• Query: compute cosine similarities and return top-k texts.

RAG flow (high level)

1. Index documents: embed and store vectors.
2. On user query: embed query, retrieve top-k docs.
3. Build a RAG context: join top-k texts with separators (truncation/careful length management).
4. Pass context to the semantic skill prompt and call LLM.

Operational concerns: security, governance, and robustness
Skills are powerful and potentially dangerous. Here are concrete controls and practices.

1) Least privilege for native skills

• Native skills that perform sensitive actions (modify database, call billing APIs) must run under scoped credentials.
• Don’t give skills a “root” service principal; instead issue short-lived tokens scoped to exact operations.
• Example pattern: the orchestrator authenticates the agent using an identity token, then performs an OAuth token-exchange per invocation to obtain least-privilege credentials for the skill runtime.

2) Runtime isolation & sandboxing

• Execute native plugin code in a sandbox or separate process with tight ACLs.
• Use containerization (small docker container per plugin) or platform sandboxing (AppDomains are not sufficient) and restrict network access.

3) Audit logging

• Log: skill name, invocation timestamp, actor (user/session id), input hashes, output hash, status (success/fail), and duration. Redact secrets.
• Example Serilog event:
  {
  “Timestamp”:”2026-09-10T12:00:00Z”,
  “Event”:”SkillInvocation”,
  “Skill”:”DocumentSummarizer”,
  “User”:”user-123″,
  “InputHash”:”sha256:abcd…”,
  “OutputHash”:”sha256:ef01…”,
  “DurationMs”:312,
  “Result”:”Success”
  }
• Retention: keep logs for the retention period required by compliance (e.g., 90 days, 1 year). Make them queryable.

4) Approval & registry

• Keep a registry of approved skills. New skills must pass code review, static analysis, and security review.
• Require signatures or checksums when installing third-party skills.

5) Limit function-calling from LLM

• When you advertise native functions to the LLM, provide explicit allow lists. Only expose the signatures the model truly needs.
• Consider requiring explicit operator approval for risky operations (e.g., “Do you want to run job X? Click approve.”).

Testing & CI for skills
Treat skills like code: add unit tests, integration tests and CI gates.

1) Unit tests

• Native functions: test logic with xUnit/MSTest, mocking dependencies.
• Semantic functions: unit test prompt templates by calling a local/mock LLM that returns deterministic output. Mock the HTTP client (HttpMessageHandler) so you can assert prompt content and expected result parsing.

Example xUnit test for FinanceSkill
[Fact]
public async Task GetExchangeRate_ReturnsExpected()
{
var svc = new FinanceSkill();
var res = await svc.GetExchangeRateAsync(“EUR”);
Assert.Contains(“EUR”, res);
}

2) Integration tests

• A test that runs the orchestration path: index a small set of docs, run RAG + semantic skill, assert returned summary contains a known fact.
• Use a staging LLM key with usage limits to avoid cost.

3) CI pipeline (GitHub Actions example)
name: CI
on: [push, pull_request]
jobs:
build_and_test:
runs-on: ubuntu-latest
steps:
– uses: actions/checkout@v4
– uses: actions/setup-dotnet@v4
with:
dotnet-version: 7.0.x
– run: dotnet restore
– run: dotnet build –configuration Release –no-restore
– run: dotnet test –no-build –verbosity normal

Add a step for SKILL.md schema validation (use a small script that parses SKILL.md using YamlDotNet and fails CI for missing fields).

Observability & telemetry

• Track metrics: per-skill invocation count, error rate, latency and model tokens consumed.
• Export traces: instrument the orchestrator to emit distributed traces (OpenTelemetry) for each skill invocation, so you can correlate LLM calls with native actions in traces.
• Use Serilog + sink to Application Insights or to a log platform.

Resilience patterns

• Retries and backoff for failing native calls (use exponential backoff with jitter).
• Circuit breakers for repeatedly failing or slow skills.
• Request batching for embedding calls (batch inputs to embedding endpoints to reduce cost).

Advanced patterns and mapping to SDKs

• Microsoft Agent Framework: these SDKs give built-in primitives that map to this model:
• Import prompt files as “semantic functions” and native C# methods as plugin functions using attributes like [KernelFunction]/[SKFunction] so the model can call them directly.
• The SDK advertises function signatures to the LLM (function-calling) and can automatically route decisions.
• SKILL.md mapping: when loading a skill folder you can:
• Parse SKILL.md to enumerate functions and prompts.
• For each prompt, call Kernel.CreateSemanticFunction or your equivalent helper to register it.
• For native code, reflect over types with attributes and register them as callable functions.

Common failure modes and mitigations
1) Hallucinations / incorrect output

• Mitigation: RAG (ground responses in retrieved docs), explicit instructions in prompts, ask agent to state uncertainty.
  2) Incorrect skill selection
• Mitigation: improve skill summaries and include disambiguating examples; add a planner policy that prefers small, well-defined skills.
  3) Malicious or buggy skill
• Mitigation: vet skills, require signatures, run native skills in sandbox and under restricted credentials.
  4) Escalation loops between skills
• Mitigation: set depth limits on planner calls, track call stack, and abort when loops detected.
  5) Cost runaway (too many model calls)
• Mitigation: enforce quotas, use cheaper models for routine tasks, cache results.

When to use semantic vs native skills

• Semantic skill (prompt) when: the task is pure language transformation or reasoning (summaries, analysis, paraphrase).
• Native skill when: you need to call external systems, perform deterministic computations, or run actions that must be auditable and auditable (DB writes, sending emails, creating tickets).

Packaging and governance checklist

• SKILL.md with schema-validated fields (name, summary, inputs, outputs, author, version).
• Example inputs and expected outputs (test vectors).
• Unit tests that run in CI.
• Security review & signing (PGP or similar).
• Runtime policy: allowed to run? who can install/update?
• Observability hooks: logging, metrics, tracing.

Key takeaways

• Agent skills let you compose agents from small, testable, auditable capabilities that are discoverable and loaded on demand.
• Use SKILL.md-like packaging, progressive disclosure, and clear input/output contracts.
• For C# developers, you can implement skills yourself (load SKILL.md, create prompt functions, expose native C# methods via reflection or attributes) or use SDKs like Semantic Kernel for structured integration.
• Secure native code, audit invocations, add tests and CI, instrument telemetry, and enforce governance.