What is the difference between an agent skill and a tool?

A tool executes code and returns a result; a skill is instructions telling the agent how to accomplish something, often including how to use particular tools. A skill changes what the agent knows, a tool changes what it can do.

What is an AGENTS.md file?

A Markdown file placed in a project that tells an AI agent how to work in that codebase — build and test commands, conventions, and constraints. It is a convention rather than a formal standard, but it is widely recognised by coding agents.

Why are agent skills written in Markdown?

Because Markdown is readable by both humans and models, diffs cleanly in version control, and requires no parser or runtime. A skill is portable text, which is what makes it shareable.

How does an agent decide which skill to load?

From the skill description. The agent matches the task against short descriptions and loads the full instructions only for the ones that appear relevant, which is why a vague description means a skill never gets used.

What Is an AI Agent Skill? .md Files, SOUL.md and AGENTS.md

What is an AI agent skill?

An AI agent skill is a reusable, self-contained instruction set that teaches an agent how to do one specific job. In current practice a skill is usually a Markdown file — often with supporting scripts — that the agent loads when the task is relevant, rather than carrying every instruction in its context all the time.

Why skills exist

An agent's context window is finite and expensive. Loading every instruction the agent might ever need, on every request, wastes most of it and degrades quality — models attend worse to a long, mostly-irrelevant prompt.

Skills solve this by making instructions loadable on demand. The agent knows a skill exists and roughly what it covers; it loads the full instructions only when the task actually calls for it. This keeps the working context small and the instructions specific.

The Markdown convention

The ecosystem converged on plain Markdown, and the reasons are practical: it is readable by both humans and models, it diffs cleanly in version control, and it needs no runtime or parser.

Several filenames now carry conventional meaning:

AGENTS.md — instructions for how an agent should operate in a given repository or project: how to build, test, what conventions to follow.
SOUL.md — persona and behavioural definition; the agent's voice, values and boundaries.
IDENTITY.md — who the agent is and what it is for.
USER.md — durable facts about the person it works with.

These conventions are young and not formally standardised, so treat any specific filename as a strong convention rather than a specification.

What a good skill contains

The difference between a skill that works and one that gets ignored is mostly structure:

A precise trigger description. The agent decides whether to load a skill from its description alone. "Handles data" is useless; "Converts n8n workflow JSON to Make blueprint format" is loadable.

Procedure, not prose. Numbered steps beat paragraphs. The model is going to follow this, not admire it.

Worked examples. One concrete input and its correct output resolves more ambiguity than several paragraphs of explanation.

Explicit failure handling. What should the agent do when the input is malformed or a step fails? Unspecified means improvised.

Boundaries. State what the skill does not cover, so the agent stops instead of guessing.

Skills, tools and prompts

These get conflated constantly:

A tool is a function the agent can call. It executes code and returns a result.
A skill is knowledge about how to do something. It changes what the agent knows, not what it can execute.
A prompt template is a reusable message shape.

A skill often tells the agent how to use a set of tools. The two are complements, not alternatives.

Distribution

Because skills are files, they distribute like files — through repositories, registries and directories. That is a genuinely new dynamic: an agent capability can be shared as a text file, reviewed in a pull request, and adopted without installing anything.

It is also why the category is worth watching. The conventions are months old, so the vocabulary and the best practices are still being written.

Neura Market indexes agent skills, AGENTS.md and SOUL.md files by category, so you can start from a working example.

Browse the .md directory

Frequently asked questions

What is the difference between an agent skill and a tool?: A tool executes code and returns a result; a skill is instructions telling the agent how to accomplish something, often including how to use particular tools. A skill changes what the agent knows, a tool changes what it can do.
What is an AGENTS.md file?: A Markdown file placed in a project that tells an AI agent how to work in that codebase — build and test commands, conventions, and constraints. It is a convention rather than a formal standard, but it is widely recognised by coding agents.
Why are agent skills written in Markdown?: Because Markdown is readable by both humans and models, diffs cleanly in version control, and requires no parser or runtime. A skill is portable text, which is what makes it shareable.
How does an agent decide which skill to load?: From the skill description. The agent matches the task against short descriptions and loads the full instructions only for the ones that appear relevant, which is why a vague description means a skill never gets used.

AI agent: An LLM given tools, memory, and a goal, allowed to plan and execute multi-step work with limited supervision.
MCP (Model Context Protocol): An open protocol for connecting AI assistants to external tools and data sources through standardized servers.
System prompt: The hidden instruction that sets an AI assistant's behavior, tone, and rules before any user input arrives.
Context window: How much text (measured in tokens) a model can consider at once. Bigger windows fit more documents but cost more per call.
Prompt engineering: Systematically designing prompts — role framing, examples, output formats, constraints — to get reliable results from LLMs.