Skip to main content
For the complete documentation index for agents and LLMs, see llms.txt.

Agent SkillsBeta

Beta
This is coming — this page describes a feature that's still being rolled out and may not be available to you yet.

Skills give the Agent access to specific instructions and resources it can read while it runs. A skill packages instructions and supporting material, like reference documents, examples, or scripts, that help the Agent do a specific job the way you want. When you add a skill to an Agent, the Agent can open and read those files during a run.

What a Skill Contains​

A skill is a folder of files. Each skill folder has a SKILL.md file at its root that describes the skill and tells the Agent how to use it. The SKILL.md file starts with a short block that defines the skill's name and description:

---
name: Web Research
description: What the skill does and when the Agent should use it.
---

# Web Research

Step-by-step instructions the Agent follows when it uses this skill.

Besides SKILL.md, a skill folder can hold any supporting files the Agent might need, such as reference documents, templates, examples, images, or scripts. You can add text files, images (PNG, JPEG, and GIF), and PDFs.

The name and description are important. The Agent uses them to decide when a skill is relevant, so keep them clear and specific.

Skills and Versions​

Every skill keeps a version history. Each time someone saves a change to a skill, the platform creates a new version. When you attach a skill to an Agent, you pin it to a specific version. The Agent always reads that exact version, even if the skill changes later. This keeps your Agent's behavior stable. To pick up newer changes, attach the updated version to the Agent.

Security Check​

When you add a skill to an Agent, the platform checks the skill for security risks and malicious patterns. A badge on the skill card indicates the security status of the skill.

Skill status badge on the skill card

Where Skills Come From​

You browse and manage skills on the Skills page under Resources. Haystack Platform offers a collection of ready-to-use skills for common tasks. You can also create your own skills and scope them to your workspace or organization. If you store your skills in a GitHub repository, you can connect it to the platform. You can connect only one repository at a time. Skills from that repository appear on the Skills page and when you add a skill to an Agent.

Skills and Tools​

Skills and tools both extend what an Agent can do, but they work differently:

  • Tools let the Agent take actions, like running a pipeline, calling custom code, or reaching an external service through MCP. A tool does something and returns a result.
  • Skills give the Agent knowledge and instructions to read. A skill doesn't run code or call a service. It provides files the Agent reads to work through a task the way you want.

Use a skill when you want to guide how the Agent approaches a task and give it reference material to follow. Use a tool when you want the Agent to perform an action or fetch live data. You can attach both skills and tools to the same Agent.

For details on tools, see Agent Tools.