🧰 Agent Skills Explained: Turn Any Agent Into an On-Demand Specialist with SKILL.md

A comprehensive guide to the open standard that turns AI agents into on-demand specialists

Quick start with LM-Kit.NET

Shell
dotnet add package LM-Kit.NET

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

registry.TryParseSlashCommand("/explain", out var skill, out _);

var activator = new SkillActivator(registry);
string prompt = activator.FormatForInjection(skill, SkillInjectionMode.UserMessage)
    + "\n\n---\n\nUser request: " + userInput;

Full tutorial in Section 9. Full demo on GitHub.

1. The Problem: Why We Need Agent Skills

If you have built an AI agent that does more than one thing, you have probably hit this wall:

Your system prompt keeps growing. Every new capability means more instructions, more examples, more edge cases. A prompt that started at 200 tokens is now 5,000. The agent gets slower, more expensive, and less reliable because it is trying to juggle everything at once.

Behavior is inconsistent. Ask the same agent to review code on Monday and again on Friday, and you might get different formats, different levels of detail, different criteria. There is nothing enforcing a consistent process.

Prompts live in code. The instructions that define your agent's behavior are buried in C# strings, Python f-strings, or YAML configs. Non-developers cannot review or improve them. Version control is awkward. Deploying a small wording change means a code release.

Knowledge is not reusable. You build a great code review workflow for Project A. Project B needs the same thing. You copy-paste the prompt, it drifts, and now you maintain two copies.

These are not edge cases. They are the daily reality of production AI development. Agent Skills were created to solve exactly these problems.

2. What Agent Skills Are

Agent Skills is an open specification for defining modular, reusable AI agent capabilities as self-contained directories. It was developed by Anthropic and introduced publicly on October 16, 2025. On December 18, 2025, the format was published as an open standard for cross-platform portability.

At its core, a skill is a folder containing one required file:

The SKILL.md file has two parts: YAML frontmatter with metadata (name, description, version) and a Markdown body with the actual instructions.

Markdown
---
name: explain
description: Explains any topic in plain language.
metadata:
  version: "1.0"
---

# Plain Language Explainer

You explain topics so anyone can understand them.

## Output Format

## <Topic>

**In one sentence:** <simple, one-sentence definition>
**How it works:** <2-3 sentences using an everyday analogy>
**Why it matters:** <1-2 sentences on why someone should care>
**Example:** <one concrete, real-world example>

## Rules

1. **No jargon.** If you must use a technical term, define it.
2. **Use analogies.** Compare unfamiliar concepts to everyday things.
3. **Be concise.** The entire explanation fits on one screen.
4. **Assume zero background knowledge.**
5. Never say "it's complicated" or "it depends."

Optional Resources

For more complex skills, the directory can include additional folders:

These resources are loaded lazily: the agent only reads them when it actually needs them, not at startup.

YAML Frontmatter Reference

3. What Agent Skills Are NOT

Skills are not tools. A tool is a deterministic action: call it with inputs, get a structured output. A skill is a set of instructions interpreted by an LLM. Skills describe how to do something. Tools do something. As the Goose team at Block put it: skills describe the workflow, while MCP provides the runner.

Skills are not prompts. A prompt is ephemeral, reactive, and embedded in code. A skill is a persistent, portable, version-controlled artifact that loads dynamically based on context.

Skills are not agents. An agent is an execution runtime with its own tools, memory, and decision loop. A skill is a knowledge module that any agent can load. Think of skills as "apps" and agents as the "operating system."

Skills are not deterministic. Because an LLM interprets the instructions, there is inherent non-determinism. If you need guaranteed structure, combine a skill with structured output constraints or use tool calls for the critical parts.

Skills are not a replacement for MCP. MCP provides secure connectivity to external systems. Skills provide procedural knowledge for using those systems. Different layers, same stack.

4. Agent Skills vs. MCP vs. Tool Use vs. Prompts

Skills vs. MCP (Model Context Protocol)

MCP is a communication protocol (spec). It defines how an agent talks to external systems. An MCP server exposes tools and resources. Agent Skills are knowledge files. A skill tells the agent how to think about a task. The Goose team at Block summarized it well: MCP gives agents abilities; skills teach agents how to use those abilities well.

A concrete example: an MCP server connects to your PostgreSQL database and exposes a run_query tool. But the agent still needs to know how to write safe, efficient SQL for your specific schema. That is what a database-query skill provides.

Skills vs. Tool Use / Function Calling

Tool use is the mechanism where an LLM invokes a structured function. Skills operate at a higher level of abstraction. A single skill might orchestrate multiple tool calls as part of a workflow. In LM-Kit.NET, a skill can be exposed as a tool via SkillTool, letting the model decide when to activate a particular skill through the function calling interface.

Skills vs. System Prompts

A system prompt is always present, always consuming tokens, and typically hardcoded. A skill is loaded only when needed and unloaded when done. Skills are portable artifacts that live outside your code, so you can share, version, review, and swap them without changing a line of code.

Skills vs. Subagents

A subagent is a fully independent agent with its own model, tools, and conversation history. A skill is lighter: it augments an existing agent's behavior without creating a new execution context. Think of subagents as "hiring a specialist contractor" and skills as "reading the specialist's playbook yourself."

The Full Comparison

5. How Progressive Disclosure Works

The key architectural innovation of Agent Skills is progressive disclosure: a three-tier loading strategy that keeps context efficient.

With 20 skills, that is roughly 1,000 tokens of metadata at startup. The agent knows what it can do, but carries none of the detailed instructions. When activated, only the relevant skill's instructions load. You only pay for what you use.

6. What Problems Do Agent Skills Solve in Practice?

Context efficiency. Without skills, 10 workflows at 500 tokens each means 5,000 tokens of permanent overhead. With skills, it is ~500 tokens for the catalog plus ~500 for the active skill. A 10x reduction.

Consistent, repeatable output. A skill specifies an exact output format, rules, and examples. Every time the agent runs that skill, it follows the same structure.

Modularity. Add a capability by dropping a folder. Remove one by deleting it. Update a workflow by editing the Markdown. No code changes, no redeployment.

Version control and governance. Skills are plain text files in your Git repository. Review changes in pull requests, track history, roll back, require approval. This matters enormously in regulated industries where AI behavior must be auditable.

Portability. Agent Skills is an open standard adopted by a growing number of products. Write once, use everywhere. No vendor lock-in.

Team collaboration. Because skills are Markdown, anyone can write or improve them. Domain experts author skills, developers review and deploy them. This separates "what the AI should do" from "how the AI works."

7. Why Agent Skills Make Even More Sense for Local Inference

Context windows are tighter. Local models typically run with 4K to 32K contexts. Progressive disclosure goes from "nice optimization" to "architectural necessity." You cannot afford to load all instructions at once.

Every token costs compute, not dollars. With local inference, extra context tokens mean more latency and memory. Skills keep prompts lean for the common case.

No network dependency. Skills are local files. The model is local. The entire pipeline happens in-process with zero network calls. Ship the model and the skills folder together.

Privacy and control. When skills run locally, the instructions never leave your machine. Proprietary compliance rules, internal procedures, or sensitive domain knowledge stays in your process memory.

8. Before and After: A Code Review Example

Same 4B model, same user question, with and without a skill:

Same model, same weights, same temperature. The only difference is 800 tokens of skill instructions.

9. Implementing Agent Skills with LM-Kit.NET

LM-Kit.NET provides a complete, production-ready implementation of the Agent Skills specification.

9.1 Create the Project

Shell
dotnet new console -n SkillAssistant
cd SkillAssistant
dotnet add package LM-Kit.NET

9.2 Create Your Skills

Create a skills/ directory with two skills. Use the explain skill from Section 2, and add an email-writer skill:

Markdown
---
name: email-writer
description: Writes a professional email from a short description.
metadata:
  version: "1.0"
---

# Professional Email Writer

You write complete, professional emails from a short description.

## Output Format

Subject: <concise subject line>

<greeting>,

<body: 2-3 short paragraphs>

<sign-off>,
[Your Name]

## Rules

1. **Never ask for more details.** Make reasonable assumptions.
2. **Be concise.** No paragraph longer than 3 sentences.
3. **Start with the purpose.** First sentence states why.
4. **End with a next step.** Include a specific action or timeline.
5. **Use [Name] placeholders** for unknown names.
6. **Default to professional tone.**

9.3 Copy Skills to Output

XML
<ItemGroup>
  <None Include="skills\**\*">
    <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
    <Link>skills\%(RecursiveDir)%(Filename)%(Extension)</Link>
  </None>
</ItemGroup>

9.4 Write the Application

C#
using LMKit.Agents.Skills;
using LMKit.Model;
using LMKit.TextGeneration.Chat;
using LMKit.TextGeneration.Sampling;
using System.Text;

Console.InputEncoding = Encoding.UTF8;
Console.OutputEncoding = Encoding.UTF8;

var registry = new SkillRegistry();
var activator = new SkillActivator(registry);

string skillsPath = Path.Combine(AppContext.BaseDirectory, "skills");
if (Directory.Exists(skillsPath))
{
    int count = registry.LoadFromDirectory(skillsPath,
        errorHandler: (path, ex) =>
            Console.WriteLine($"  Warning: {ex.Message}"));
    Console.WriteLine($"Loaded {count} skill(s).\n");
}

var model = LM.LoadFromModelID("gemma3:4b");
var chat = new MultiTurnConversation(model);
chat.MaximumCompletionTokens = 4096;
chat.SamplingMode = new RandomSampling { Temperature = 0.7f };
chat.AfterTextCompletion += (_, e) => Console.Write(e.Text);

AgentSkill? activeSkill = null;

Console.WriteLine("Available skills:");
foreach (var skill in registry.Skills)
    Console.WriteLine($"  /{skill.Name} - {skill.Description}");
Console.WriteLine("  /off - Deactivate current skill\n");

while (true)
{
    Console.Write("\nYou: ");
    string? input = Console.ReadLine();
    if (string.IsNullOrWhiteSpace(input)) break;

    if (input.StartsWith("/"))
    {
        if (input.Trim() == "/off")
        { activeSkill = null; Console.WriteLine("Skill deactivated."); continue; }

        if (registry.TryParseSlashCommand(input, out var matched, out _))
        { activeSkill = matched; Console.WriteLine($"Skill activated: {matched.Name}"); continue; }

        Console.WriteLine("Unknown command."); continue;
    }

    string prompt = input;
    if (activeSkill != null)
    {
        string instructions = activator.FormatForInjection(
            activeSkill, SkillInjectionMode.UserMessage);
        prompt = instructions + "\n\n---\n\nUser request: " + input;
    }

    Console.Write("\nAssistant: ");
    var result = chat.Submit(prompt);
    Console.WriteLine();
}

10. Production Features in LM-Kit.NET

Automatic skill matching. SkillRegistry can match a user's natural-language request to the best skill using keyword scoring or embedding-based semantic search via FindMatches and FindMatchesWithEmbeddings. Build assistants that route to the right skill automatically.

Remote skill loading. SkillRegistry.LoadFromUrlAsync fetches skills from URLs, ZIP archives, or GitHub repositories. Host a skill library centrally and have agents pull the latest versions at startup.

Hot reload. SkillWatcher monitors the skills directory and automatically reloads any SKILL.md that changes. Edit the file, save, and the agent picks up the new instructions without restarting.

C#
using var watcher = new SkillWatcher(registry, skillsPath);
watcher.Start();

Programmatic skill creation. SkillBuilder provides a fluent API for constructing skills in code rather than from files.

Skills as tools. SkillTool wraps the skill registry as an ITool, letting the model decide which skill to activate through function calling.

Validation. SkillRegistry.ValidateAll() checks all loaded skills against the spec. Run this in CI to catch errors before deployment.

LM-Kit.NET Agent Skills API at a Glance

11. Best Practices for Writing Great Skills

Naming: Use lowercase with hyphens: code-review, email-writer. Keep it short and descriptive (max 64 characters). Avoid generic names like helper.

Description: Write it as a one-sentence action statement. Include keywords that help with automatic matching. Keep it under 1024 characters.

Instructions: Put the most important constraints first. Specify the exact output format with a template. Write explicit, numbered rules. Include at least one example. Keep it concise (500-2,000 tokens).

SKILL.md Template

Markdown
---
name: your-skill-name
description: One sentence explaining when to use this skill.
metadata:
  version: "1.0"
---

# Role Title

One paragraph defining the agent's role.

## Output Format

<exact template with placeholders>

## Rules

1. **Rule one.** Short explanation.
2. **Rule two.** Short explanation.

## Example

**Input:** <sample input>
**Output:** <sample output following the format above>

The Skill Authoring Checklist

• Name is lowercase, hyphenated, and descriptive
• Description clearly states when to use the skill
• Version is set (start with 1.0)
• Output format is explicitly defined with a template
• At least 3 clear rules constrain behavior
• At least 1 example input/output is included
• Instructions fit within ~2,000 tokens
• Skill validates without errors
• Tested with at least 2 different models

12. Security Considerations

Agent Skills are powerful, and that power requires care. Cisco's AI Defense team found that a significant number of publicly shared skills contained vulnerabilities, including prompt injection and credential exfiltration.

• Review all skills before deployment. Treat SKILL.md files like code: review them in pull requests.
• Be cautious with scripts/. Scripts execute on the host machine. Only include scripts from trusted sources.
• Use the allowed-tools field. Explicitly declare which system tools a skill can invoke.
• Never put secrets in skills. No API keys, passwords, or tokens in SKILL.md files.
• Validate inputs. Ensure your agent validates user-provided data before acting on it.
• Pin versions. When loading remote skills, pin to specific versions or commit hashes.

13. Industry Adoption

The standard was developed by Anthropic and published as open source. The broader agentic AI ecosystem is coordinated through the Agentic AI Foundation under the Linux Foundation, whose platinum members include AWS, Anthropic, Block, Google, Microsoft, and OpenAI.

14. Conclusion

Agent Skills solve a real, specific problem: how to give AI agents specialized, reusable expertise without overwhelming their context windows. The solution is elegant in its simplicity. A skill is a Markdown file in a folder. The agent loads it on demand. The output becomes consistent.

Here is what to remember:

• A skill is a folder with a SKILL.md file. YAML frontmatter for metadata, Markdown body for instructions.
• Progressive disclosure keeps context efficient. Metadata at startup, instructions on activation, resources on execution.
• Skills are not tools, not prompts, not agents. They are portable knowledge modules that complement all three.
• The standard is open and widely adopted. OpenAI, Microsoft, Anthropic, and a growing number of platforms support it.
• LM-Kit.NET provides a complete implementation. Registry, activator, hot reload, remote loading, validation, tool integration.

Resources

Further Reading

• Agent Skills Specification
• Claude Blog: Skills Explained
• OpenAI Codex Skills Documentation
• VS Code Agent Skills
• Goose Blog: "Did Skills Kill MCP?"
• LlamaIndex: Skills vs MCP Tools
• The New Stack: Agent Skills Analysis
• Simon Willison on Agent Skills
• Spring AI: Agent Skills in Java
• Cisco: Agent Skills Security Research
• LM-Kit.NET Documentation
• LM-Kit.NET Agent Skills Glossary
• LM-Kit.NET Samples Repository