deepset-ai--haystack/docs-website/reference/haystack-api/skill_stores_api.md

title, id, description, slug

title	id	description	slug
Skill Stores	skill-stores-api	Storage layers that discover skills and serve their content on demand.	/skill-stores-api

file_system/skill_store

FileSystemSkillStore

SkillStore backed by a directory of skill sub-directories on the local filesystem.

Expected layout:

skills/
  pdf-forms/
    SKILL.md            # frontmatter (name, description) + markdown instructions
    reference/forms.md  # optional bundled file

The skill catalog is built by reading the frontmatter of each SKILL.md on warm_up; bodies and bundled files are read lazily when the agent calls the corresponding tool.

init

__init__(skills_dir: str | Path) -> None

Initialize the store with the root directory to scan.

No filesystem access happens here; the directory is scanned lazily on first use (see warm_up), so the store can be constructed cheaply.

Parameters:

• skills_dir (str | Path) – Root directory that contains one sub-directory per skill.

warm_up

warm_up() -> None

Scan skills_dir and build the skill catalog by reading each skill's SKILL.md frontmatter.

Only the frontmatter is read here; bodies and bundled files are read lazily when the corresponding method is called. Idempotent: repeated calls after the first are no-ops.

Raises:

• ValueError – If skills_dir does not exist, is not a directory, a skill's frontmatter is missing, malformed, or missing a required field, or two skills share the same name.

list_skills

list_skills() -> dict[str, SkillInfo]

Return all skills discovered on disk, warming up the store first if needed.

Returns:

• dict[str, SkillInfo] – Mapping of skill name to its metadata.

Raises:

• ValueError – If the skills directory is invalid or a skill's frontmatter is malformed.

load_skill

load_skill(name: str) -> tuple[str, list[str]]

Read the named skill's instruction body and the manifest of its bundled files.

Parameters:

• name (str) – Skill name as returned by list_skills.

Returns:

• tuple[str, list[str]] – A tuple of (markdown body of the skill's SKILL.md with frontmatter stripped, sorted list of POSIX-style paths relative to the skill directory for any bundled files). The file list is empty when the skill bundles no extras.

Raises:

• KeyError – If no skill with name exists.

read_skill_file

read_skill_file(name: str, path: str) -> str | ImageContent | FileContent

Read a file bundled with the named skill, preventing path traversal outside the skill directory.

The return type depends on the file: text files are returned as a str, image files (PNG, JPEG, ...) as an ImageContent, and PDFs as a FileContent, so a multimodal agent can pass them straight to the model.

Parameters:

• name (str) – Skill name as returned by list_skills.
• path (str) – Path of the file relative to the skill directory (e.g. "reference/forms.md").

Returns:

• str | ImageContent | FileContent – The file's text content (str), an ImageContent for images, or a FileContent for PDFs.

Raises:

• KeyError – If no skill with name exists.
• PermissionError – If path resolves outside the skill's directory (path-traversal attempt). The message lists the readable files so the caller can retry with a valid path.
• FileNotFoundError – If the file does not exist within the skill. The message lists the readable files so the caller can retry with a valid path.
• ValueError – If the file is binary but not a supported image or PDF (i.e. not UTF-8 text either).

to_dict

to_dict() -> dict[str, Any]

Serialize this store to a dictionary for use with from_dict.

Returns:

• dict[str, Any] – Dictionary representation of the store.

from_dict

from_dict(data: dict[str, Any]) -> FileSystemSkillStore

Deserialize a FileSystemSkillStore from its dictionary representation.

Parameters:

• data (dict[str, Any]) – Dictionary representation of the store, as produced by to_dict.

Returns:

• FileSystemSkillStore – A new FileSystemSkillStore instance.

types/protocol

SkillStore

Bases: Protocol

Protocol for a skill storage layer.

A SkillStore is responsible for discovering available skills and providing their content on demand. Implement this protocol to back a haystack.tools.SkillToolset with any storage system — a local directory, a database, a remote API, or an in-memory fixture.

Skills are identified by their name, which must be unique within a store. The name is the lookup key for every method below; implementations resolve it to their own internal locator (a directory, a row id, an object key, ...).

Implementations may defer all I/O (filesystem reads, database connections, ...) until a method is actually called, so a store can be constructed cheaply and only touch its backend on first use.

Skill content is text: instruction bodies and bundled files are returned as strings. Binary assets (images, fonts, ...) are not supported.

list_skills

list_skills() -> dict[str, SkillInfo]

Discover and return all available skills.

Returns:

• dict[str, SkillInfo] – Mapping of skill name to its metadata.

load_skill

load_skill(name: str) -> tuple[str, list[str]]

Return the named skill's instruction body and the manifest of its bundled files.

Parameters:

• name (str) – Skill name as returned by list_skills.

Returns:

• tuple[str, list[str]] – A tuple of (markdown body with frontmatter stripped, sorted list of POSIX-style paths relative to the skill root for any bundled files). The file list is empty when the skill bundles no extras.

Raises:

• KeyError – If no skill with name exists.

read_skill_file

read_skill_file(name: str, path: str) -> str | ImageContent | FileContent

Read a file bundled with the named skill.

Implementations should return text files as a str, image files as an ImageContent, and PDFs as a FileContent, so a multimodal agent can pass binary assets straight to the model.

Parameters:

• name (str) – Skill name as returned by list_skills.
• path (str) – Path of the file relative to the skill root (e.g. "reference/forms.md").

Returns:

• str | ImageContent | FileContent – The file's text content (str), an ImageContent for images, or a FileContent for PDFs.

Raises:

• KeyError – If no skill with name exists.
• FileNotFoundError – If the file does not exist within the skill.

to_dict

to_dict() -> dict[str, Any]

Serialize this store to a dictionary for use with from_dict.

Implement both this method and from_dict to make your custom store serializable.

from_dict

from_dict(data: dict[str, Any]) -> SkillStore

Deserialize a store from a dictionary produced by to_dict.

Implement both this method and to_dict to make your custom store serializable.

Parameters:

• data (dict[str, Any]) – Dictionary as produced by to_dict.