Table of Contents

What Are Agent Skills and How Do They Differ from Tools?


TL;DR

Skills define behavior. Tools provide capability. An Agent Skill is a self-contained instruction set (a SKILL.md file) that tells the agent how to act, what to prioritize, and what workflow to follow. A Tool is an executable .NET method that gives the agent something to do: call an API, read a file, perform a calculation. Skills shape the agent's approach; tools extend what the agent can physically accomplish. An agent can use skills and tools together.


Skills: Behavioral Instruction Packages

A skill is a SKILL.md file combining YAML metadata with Markdown instructions. It follows the open Agent Skills specification. Skills contain no executable code. They tell the agent what persona to adopt, what steps to follow, and what constraints to respect.

Example SKILL.md:

---
name: "email-writer"
description: "Converts a one-line description into a professional email"
version: "1.0.0"
---

# Email Writer

You are a professional email writer. When the user provides a brief description
of what they want to communicate:

1. Determine the appropriate tone (formal, friendly, urgent)
2. Write a complete email with subject line, greeting, body, and sign-off
3. Keep the email concise (under 200 words)
4. Ask the user if they want adjustments before finalizing

Skills are loaded at runtime and injected into the agent's context:

using LMKit.Agents.Skills;

var registry = new SkillRegistry();
registry.LoadFromDirectory("./skills");

// Each subdirectory with a SKILL.md becomes a skill
// skills/email-writer/SKILL.md → "email-writer" skill
// skills/code-review/SKILL.md  → "code-review" skill

Tools: Executable Capabilities

A tool is a .NET method that the model can call. It has a name, a JSON schema describing its parameters, and an InvokeAsync method that runs actual code:

using LMKit.Agents.Tools;

public class WeatherTool : ITool
{
    public string Name => "get_weather";
    public string Description => "Get current weather for a city";
    public string InputSchema => """{ "type": "object", "properties": { "city": { "type": "string" } }, "required": ["city"] }""";

    public async Task<string> InvokeAsync(string arguments, CancellationToken ct)
    {
        var args = JsonSerializer.Deserialize<WeatherArgs>(arguments);
        var weather = await FetchWeather(args.City, ct);
        return JsonSerializer.Serialize(weather);
    }
}

Side-by-Side Comparison

Aspect Agent Skill Tool
What it is Instruction set (Markdown + YAML) Executable .NET method
What it defines Behavior, persona, workflow, constraints A single callable operation
File format SKILL.md C# class implementing ITool
Contains code? No. Text instructions only. Yes. Runs actual .NET code.
How it works Injected into the agent's prompt context Called by the model via function calling
Can use tools? Yes. Skills can specify allowed-tools in metadata. N/A
Granularity High-level strategy (entire workflow) Low-level action (one operation)
Modification Edit a text file. No recompilation. Edit C# code. Requires recompilation.
Distribution Copy a folder. Load from GitHub URL. NuGet package or project reference.

Using Skills and Tools Together

The most powerful pattern combines both. A skill defines the strategy; tools provide the capabilities:

---
name: "research-assistant"
description: "Researches a topic using web search and summarizes findings"
allowed-tools: "websearch, http_get"
---

# Research Assistant

When the user asks you to research a topic:
1. Use web search to find relevant sources
2. Read the top 3 results
3. Synthesize a summary with citations
4. Ask if the user wants deeper analysis on any point

The agent follows the skill's workflow and uses the allowed tools to execute each step.


When to Use Each

Scenario Use a Skill Use a Tool
Change the agent's personality or tone ✓
Define a multi-step workflow ✓
Add domain expertise (legal, medical, financial) ✓
Call an external API ✓
Read or write files ✓
Perform calculations ✓
Combine strategy with capability ✓ + ✓

📚 Related Content

Share