Module: SwarmSDK::V3::Skills::Loader

Defined in:
lib/swarm_sdk/v3/skills/loader.rb

Overview

Stateless utility for discovering skills and generating XML metadata

Skills are directories containing a SKILL.md file with YAML frontmatter. The loader scans configured directories, parses frontmatter, and produces XML metadata for injection into agent system prompts.

Examples:

Scan and format skills

manifests = Loader.scan(["/path/to/skills"])
xml = Loader.format_xml(manifests)
# => "<available_skills>\n  <skill>..."

Constant Summary collapse

SKILL_FILENAME = 
"SKILL.md"

Class Method Summary collapse

Class Method Details

.format_xml(manifests) ⇒ String

Format manifests as XML for system prompt injection

Produces an ‘<available_skills>` XML block following the agentskills.io standard. Values are HTML-escaped for safety.

Examples:

xml = Loader.format_xml(manifests)
# => "<available_skills>\n  <skill>\n    <name>..."

Parameters:

  • manifests (Array<Manifest>) —

    Skill manifests to format

Returns:

  • (String) —

    XML string, or empty string if no manifests



58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
 
# File 'lib/swarm_sdk/v3/skills/loader.rb', line 58

def format_xml(manifests)
  return "" if manifests.empty?

  entries = manifests.map { |m| format_skill_entry(m) }
  skills_block = "<available_skills>\n#{entries.join("\n")}\n</available_skills>"

  <<~PROMPT.strip
    # Skills

    You have skills available. Each skill has a name, description, and a SKILL.md file location.
    When a user's task matches a skill description, activate the skill by reading its SKILL.md file to get full instructions. Do NOT read SKILL.md files unless you are actually activating a skill to perform a task. The name and description below are sufficient for listing or discussing available skills.

    #{skills_block}
  PROMPT
end

.scan(directories) ⇒ Array<Manifest>

Scan directories recursively for SKILL.md files and return parsed manifests

SKILL.md is the definitive marker for a skill directory per the agentskills.io spec. Uses Dir.glob with ‘**/SKILL.md` for fast recursive discovery. Skips missing directories and invalid YAML silently via DebugLog. Deduplicates by absolute SKILL.md path.

Examples:

manifests = Loader.scan(["/skills", "/more-skills"])
manifests.each { |m| puts "#{m.name}: #{m.description}" }

Parameters:

  • directories (Array<String>) —

    Root paths to scan

Returns:

  • (Array<Manifest>) —

    Discovered skill manifests



33
34
35
36
37
38
39
40
41
42
43
44
45
 
# File 'lib/swarm_sdk/v3/skills/loader.rb', line 33

def scan(directories)
  seen = {}

  Array(directories).each do |dir|
    next unless File.directory?(dir)

    Dir.glob(File.join(dir, "**", SKILL_FILENAME)).sort.each do |skill_path|
      parse_and_register(skill_path, seen)
    end
  end

  seen.values
end