Load and Discover SKILL.md Content

SkillToolkit is a CAMEL-AI toolkit (camel.toolkits.skill_toolkit) that lets an agent discover and load SKILL.md-based skills from the filesystem on demand, instead of embedding every instruction set directly in the system prompt. On construction it takes an optional working_directory (defaults to the current working directory), an optional allowed_skills set that restricts which skill names are visible, and an optional timeout.

Skills are discovered by scanning three scope levels in priority order: repo (<working_directory>/.camel/skills and <working_directory>/.agents/skills), user (~/.camel/skills and ~/.config/camel/skills), and system (/etc/camel/skills). Each scope is searched recursively for SKILL.md files; hidden directories (starting with a dot) are skipped. If two skills share the same name, the one found in the earlier scope wins - repo overrides user, user overrides system. Each SKILL.md must start with a YAML frontmatter block containing string name and description fields; a file with no frontmatter, invalid YAML, a non-mapping frontmatter, or a missing name/description is skipped with a logged warning rather than raising.

The toolkit exposes two agent-callable tools via get_tools(): list_skills(), which returns each skill's name, description, path, and scope without loading its body; and load_skill(name), which accepts a single skill name or a list of names and returns the matching SKILL.md body content (multiple results are joined with a --- separator). A third method, list_skill_files(name), lists the files and subdirectories inside a given skill's folder. clear_cache() forces the internal skills cache to rescan on next access.

The load_skill tool's OpenAI-format schema description is generated dynamically by _build_description(): it lists every currently available skill (name, description, path, and sibling files) inside <available_skills>/<skill> XML-style tags, and appends a fixed usage guide covering when to trigger a skill, how to progressively load only the SKILL.md plus the specific referenced files/scripts/assets needed, how to sequence multiple applicable skills, and how to fall back gracefully when a named skill is missing or unreadable.

Use this toolkit when building a CAMEL-AI agent that should pull in specialized, file-based instruction sets on demand - keeping the base system prompt small while still giving the agent access to a growing library of skills organized across a repo-local, user-level, and system-wide directory hierarchy with clear override priority.

It is not useful if your skills already live inline in the prompt, if there is no SKILL.md-based skill library on disk to scan, or if you need skill content validated beyond frontmatter shape - the toolkit only checks that name and description are present strings; it does not validate the skill body itself.

Inputs: working_directory (path, optional), allowed_skills (set of skill-name strings, optional filter), timeout (float, optional) at construction; a skill name or list of names passed to load_skill() / list_skill_files().

Outputs: list_skills() returns a list of dicts (name, description, path, scope); load_skill() returns the raw SKILL.md body text (or an Error: Skill "<name>" not found string listing available names); list_skill_files() returns a formatted newline-joined listing of the skill folder's contents; get_tools() returns a list of two FunctionTool objects ready to attach to an agent's toolset.

Extends camel.toolkits.base.BaseToolkit and wraps its two tools as camel.toolkits.function_tool.FunctionTool instances with OpenAI-compatible tool schemas. Uses camel.logger.get_logger for warning-level logging on unreadable or malformed skill files, and PyYAML (yaml.safe_load) to parse each SKILL.md's frontmatter block. The module is released by CAMEL-AI.org under the Apache License, Version 2.0.

Developers building CAMEL-AI multi-agent applications who want agents to discover and load specialized skill instructions at runtime rather than hardcoding them into the system prompt, and teams that need skills organized across repo/user/system scopes with a defined override order (e.g. a project-specific skill taking priority over a shared user- or system-level one of the same name).