SkillsManager

Overview

SkillsManager implements Agent Skills: SKILL.md files on disk, discovered and rendered into a prompt section the agent sends to the model. It supports the tiered loading model — name/description metadata kept in memory for context-aware activation (Tier 1), and a skill’s full body pulled on demand (Tier 2). Every Agent builds one automatically as agent.skills. It is also usable standalone.

from swarms import Agent

agent = Agent(agent_name="Analyst", model_name="gpt-5.4", skills_dir="./skills")
agent.run("Build a DCF model")  # relevant skills are sent with each LLM call

Import

from swarms import SkillsManager

Design

The manager never mutates the agent. It returns prompt text and the caller decides what to do with it, which keeps the class testable on its own:

# Agent.handle_skills stores the section; it does not touch system_prompt
self._skills_prompt = self.skills.prompt_for_task(task)

Agent.call_llm then sends that section with every LLM call: as a leading system message when the call carries messages, otherwise in front of the task string. The tool-summary call gets it too. agent.system_prompt never changes, so repeated runs do not stack copies of the skills.

Constructor

SkillsManager(skills_dir=None, similarity_threshold=0.3)

Union[str, List[str]]

A directory, or a list of directories, containing skill folders. Each folder holds a SKILL.md file with YAML frontmatter. Directories are read in order. When two directories hold a skill with the same name, the later directory wins and a warning is logged. None disables skills entirely.

float

default:"0.3"

Minimum task/skill similarity for a skill to be selected during dynamic loading.

Attributes

Optional[Union[str, List[str]]]

The configured skills directory or directories.

float

The threshold passed to the dynamic loader.

List[Dict[str, str]]

Metadata for the skills loaded so far.

bool

Read-only. True when at least one configured directory exists on disk.

Skill format

Each skill is a folder containing a SKILL.md with YAML frontmatter:

skills/
├── financial-analysis/
│   └── SKILL.md
└── code-review/
    └── SKILL.md

SKILL.md

---
name: financial-analysis
description: DCF modeling, ratio analysis, and valuation techniques
---

When performing financial analysis, always start by identifying the
company's revenue drivers, then build a three-statement model...

Malformed skills are skipped, never fatal — a file with no frontmatter, unterminated frontmatter, invalid YAML, or one that cannot be read is logged and passed over. A skill with no name in its frontmatter falls back to its folder name.

Methods

prompt_for_task

def prompt_for_task(task: Optional[str] = None) -> str

Build the skills prompt section. The task argument selects the loading strategy:

str

When provided, only skills whose description is similar to the task are loaded (dynamic). When None, every skill is loaded (static).

Returns the formatted prompt section, or "" when nothing loaded. Populates metadata as a side effect.

Dynamic
Static

skills = SkillsManager(skills_dir="./skills")
section = skills.prompt_for_task("Build a DCF valuation model")
# only financial-analysis is selected

Uses DynamicSkillsLoader, which scores each skill’s description against the task by cosine similarity and keeps those at or above similarity_threshold. The loader is built lazily on first use and reused afterwards, so it reads the skill directories once. Call set_skills_dir() to make it re-read them.

section = skills.prompt_for_task(None)
# every skill in the directory is included

load_metadata

def load_metadata(
    skills_dir: Optional[Union[str, List[str]]] = None,
) -> List[Dict[str, str]]

Tier 1 loading — scan one or more directories and return one dict per skill with name, description, path, and content. Defaults to the configured directories. A missing directory is logged and contributes nothing, so the result is [] when none exist. Within a directory, skill folders are read in sorted order. Across directories, a later skill replaces an earlier one with the same name.

load_metadata() returns metadata without assigning it to self.metadata. Only prompt_for_task() populates that attribute — and load_full_skill() reads from it. Calling load_metadata() alone and then load_full_skill() will always return None.

build_prompt

def build_prompt(skills: List[Dict[str, str]]) -> str

Render skill metadata as a prompt section. Returns "" for an empty list. The # Available Skills header is emitted exactly once, followed by each skill’s name, description, and body.

load_full_skill

def load_full_skill(skill_name: str) -> Optional[str]

Tier 2 loading — the complete markdown below the frontmatter for one skill, found by name in metadata. Returns None when the skill is unknown or the file has since become unreadable.

set_skills_dir

def set_skills_dir(skills_dir: Optional[Union[str, List[str]]]) -> None

Point the manager at a different directory or list of directories, discarding cached metadata and the dynamic loader.

Agent integration

`Agent` member	Behavior
`agent.skills`	The `SkillsManager` instance
`agent.skills_dir`	Property reading through to `skills.skills_dir` (settable)
`agent.skills_metadata`	Property reading through to `skills.metadata` (settable)
`agent.handle_skills(task=None)`	Stores `prompt_for_task(task)`; `call_llm` sends it with every LLM call
`agent.load_skills_metadata(skills_dir=None)`	Delegates to `load_metadata()`
`agent.load_full_skill(name)`	Delegates to `load_full_skill()`

Skills are selected at run() time, not construction. Each run(task) calls handle_skills(task) when skills_dir is set, so the selection follows the current task and replaces the previous one. agent.system_prompt never includes the skills.

Several directories

Pass a list to combine skill sets, for example your own skills and a shared team folder:

from swarms import Agent

agent = Agent(
    agent_name="Reviewer",
    model_name="gpt-5.4",
    skills_dir=["./team_skills", "./my_skills"],
)

If both folders define code-review, the one in ./my_skills is used and a warning names the overridden file.

Standalone use

from swarms import SkillsManager

skills = SkillsManager(skills_dir="./skills")

print(skills.enabled)                        # True
print([s["name"] for s in skills.load_metadata()])
print(skills.prompt_for_task("review this Python code"))
print(skills.load_full_skill("code-review"))

Agent Skills

Guide to authoring and using skills

Agent

The class that owns the manager

Core Classes

Multi-Agent Harnesses

Tools & Utilities

Deployment

Overview

Import

Design

Constructor

Attributes

Skill format

Methods

prompt_for_task

load_metadata

build_prompt

load_full_skill

set_skills_dir

Agent integration

Several directories

Standalone use

Agent Skills

Agent

​Overview

​Import

​Design

​Constructor

​Attributes

​Skill format

​Methods

​prompt_for_task

​load_metadata

​build_prompt

​load_full_skill

​set_skills_dir

​Agent integration

​Several directories

​Standalone use

​Related

Agent Skills

Agent

Overview

Import

Design

Constructor

Attributes

Skill format

Methods

prompt_for_task

load_metadata

build_prompt

load_full_skill

set_skills_dir

Agent integration

Several directories

Standalone use

Related