ruby_llm-skills 0.3.0 → 0.5.0.pre1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '048ac6f6a76a7fd48994d208799b967754b25ecc3959acd56d44f5ab707f9f8d'
-  data.tar.gz: 268827da6d73359d9451b159b1abe68dea7881419df6b473cceeb2d8c74bc073
+  metadata.gz: 0cec1aca2ab163ce3eca337510effe09497b32a46992f0f5fe9f8ef5eb9ef629
+  data.tar.gz: 29c764164144d9fe80b7b77ba418a6f264202bc8ba6872f4d9e4e1640ca52615
 SHA512:
-  metadata.gz: febe501ab666f7e1cdf06e043ab44305ea065ffe561508b6fdcb9a959a90eabad8d2cb9fcc90384536eaf0871f73f2e52c3c9e93b8d883fbe8823274f547f0f3
-  data.tar.gz: 73226c3f1eb42ba6073dbfdcccb9f334896e078ca04ab1814260feb4218d432a83cf92817a32bb6c1abe847cf7fcd0098259aa2bab5886ce933d2c258d4ae8f1
+  metadata.gz: d125b1e44c94858c097cc4aaf24a81d019eb7d25fd9180c2957d2a5f9c43a6b541b6d4fbd46008b65017ea9de93f157609345e9918f597f97795fd816b5fe66c
+  data.tar.gz: 64aae5fd59daf2bf7500cee110a51fbd7a993cb9bf6f725a54df7934d2966ee07114a93fa1f7a32a99572a52f9394e1c1a8a721cdb78a0c8ac8c21fe03388c2e

data/CHANGELOG.md

@@ -5,6 +5,45 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.0.pre1] - 2026-09-18
+
+Prerelease, like the 0.4.0 line, while RubyLLM 2.0 is at `2.0.0.rc3`; RubyLLM 1.x users stay on 0.3.x.
+
+### Added
+
+- Plugin marketplaces as a skill source: `RubyLLM::Skills.marketplaces` returns a `Marketplace::Registry` that adds a Claude Code, Codex or Cursor marketplace from `owner/repo`, `owner/repo@ref`, a github.com or gitlab.com URL, a hosted `marketplace.json` URL or a local directory, lists its plugins, installs all or selected plugins under `vendor/skills/<marketplace>/<plugin>/`, updates and removes them
+- `skills.lock.json` records every marketplace (kind, locator, ref, resolved commit) and plugin (version, commit, tree sha256, source, skills); `Registry#install` with no arguments reproduces the lockfile at the recorded commits, and a marketplace pinned to a commit sha never moves on `update`
+- Plugin normalization: `skills/<name>/**` validated by the Agent Skills rules, `commands/*.md` as single-file skills, `agents/**/*.md` kept, plugin-level references relocated under `<skill>/.plugin/`, hooks, MCP, LSP, executables and workflows dropped, with caps on archive size, file size, file count and skill count
+- `RubyLLM::Skills.from_marketplaces` loader; `Chat#with_skills` and `Agent.skills` accept a registry as a source
+- `RubyLLM::Skills::Marketplace.configure` for the GitHub token, fetch caps and a `url_guard` hook for marketplace-author URLs
+- Rake tasks `skills:marketplaces:{add,list,plugins,install,update,remove}`, loaded by the Railtie or via `require "ruby_llm/skills/tasks"`
+
+## [0.4.0.pre2] - 2026-09-14
+
+### Changed
+
+- Updated the RubyLLM 2.0 dependency floor and development locks from `2.0.0.rc2` to `2.0.0.rc3`
+- Verified the Agent Skills integration against RubyLLM 2.0.0.rc3; its Agent, Chat, and Tool APIs remain compatible with the 0.4 port
+
+## [0.4.0.pre1] - 2026-09-10
+
+### Changed
+
+- **Breaking:** requires RubyLLM 2.0 (`ruby_llm >= 2.0.0.rc2, < 3`); 1.x users should stay on 0.3.x
+- `SkillTool` declares parameters with the 2.0 `parameter`/`description:` DSL, exposes `parameters_schema`, and sets its name through `tool_name`
+- `Chat#with_skills` registers the skill tool via `Chat#with_tools` (2.0 removed `Chat#with_tool`)
+- `AgentExtensions` hooks the 2.0 `Agent.apply_configuration(chat, input_values:, persist_instructions:)` signature and applies skills to the chat or `acts_as_chat` record it receives
+- Integration tests pin `openai_protocol = :chat_completions` and match VCR cassettes on method and URI so the recorded 1.x interactions replay under 2.0
+
+### Removed
+
+- Global `Module#delegate` fallback and its compatibility test (2.0's `Agent` uses `Forwardable`)
+- Dependency on the removed `Agent.llm_chat_for` hook
+
+### Fixed
+
+- StandardRB `Layout/EmptyLinesAroundModuleBody` offense in `chat_extensions.rb` that failed CI
+
 ## [0.3.0] - 2026-02-17
 
 ### Added

data/README.md

@@ -9,9 +9,12 @@ Agent Skills for [RubyLLM](https://github.com/crmne/ruby_llm). Teach your AI how
 ## Installation
 
 ```ruby
-gem "ruby_llm-skills"
+gem "ruby_llm", "2.0.0.rc3"
+gem "ruby_llm-skills", "0.5.0.pre1"
 ```
 
+Requires RubyLLM 2.0 (`>= 2.0.0.rc3`). If you are still on RubyLLM 1.x, stay on `ruby_llm-skills ~> 0.3.0` and follow the [RubyLLM 2.0 upgrade guide](https://rubyllm.com/next/upgrading/) before upgrading both gems together.
+
 ## Quick Start
 
 ```ruby
@@ -31,7 +34,7 @@ chat.with_skills("app/skills", "app/commands") # multiple paths
 chat.with_skills("app/skills", user.skills)   # with database records
 ```
 
-### With RubyLLM::Agent (v1.12+)
+### With RubyLLM::Agent
 
 ```ruby
 class SupportAgent < RubyLLM::Agent
@@ -89,6 +92,58 @@ chat.with_skills("app/skills", "app/commands")
 chat.ask "/write-poem about robots"
 ```
 
+## Marketplaces
+
+Instead of adding skills one by one, add a whole plugin marketplace. The gem reads Claude Code (`.claude-plugin/marketplace.json`), Codex (`.agents/plugins/marketplace.json`) and Cursor (`.cursor-plugin/marketplace.json`) marketplaces from a GitHub repository, a GitLab project, a hosted `marketplace.json` URL or a local directory, fetches plugins over HTTPS (never `git`), and normalizes each one into the `skills/` layout the loaders read.
+
+```ruby
+marketplaces = RubyLLM::Skills.marketplaces          # vendor/skills + skills.lock.json
+
+marketplaces.add("EveryInc/compound-writing")         # follows the default branch
+marketplaces.add("typesafe-ai/skills", ref: "v0.5.7") # pinned to a tag (or a commit sha)
+marketplaces.add("https://example.com/marketplace.json")
+
+marketplaces.plugins("compound-writing").map(&:name)  # what the marketplace lists
+marketplaces.install("compound-writing")              # every supported plugin
+marketplaces.install("typesafe-ai", only: ["typesafe"])
+
+marketplaces.update                                   # move unpinned marketplaces to their ref's head
+marketplaces.remove("typesafe-ai")
+
+chat.with_skills("app/skills", marketplaces)          # a registry is a skill source
+```
+
+Plugins land in `vendor/skills/<marketplace>/<plugin>/` with their `skills/` (directory skills plus `commands/*.md` as single-file skills) and `agents/`. Plugin-level files a skill references through `../../x` or `${CLAUDE_PLUGIN_ROOT}/x` are copied under `<skill>/.plugin/` so the skill tool can serve them. Hooks, MCP and LSP configuration, executables and workflows are never installed.
+
+`skills.lock.json` records every marketplace with its kind, locator, ref and resolved commit, and every plugin with its version (the plugin manifest's, else the entry's, else the commit), commit, tree hash, source and skill names. Commit both, and `RubyLLM::Skills.marketplaces.install` (no arguments) reproduces the same trees on another machine at the recorded commits. A marketplace added with a commit sha as `ref` never moves on `update`; a branch or tag ref does.
+
+```ruby
+RubyLLM::Skills.from_marketplaces                     # a loader over the installed plugins
+RubyLLM::Skills.marketplaces(root: "lib/skills/vendor", lockfile: "lib/skills/skills.lock.json")
+
+RubyLLM::Skills::Marketplace.configure do |config|
+  config.github_token = ENV["GITHUB_TOKEN"]           # the default; lifts the API rate limit
+  config.max_archive_bytes = 64 * 1024 * 1024         # per plugin archive; also max_file_bytes, max_files, max_skills
+  config.url_guard = ->(uri) { ... }                  # called per hop for URLs a marketplace author supplied
+end
+```
+
+`install` and `update` return a result with `installed`, `updated`, `unchanged`, `skipped` (unsupported sources, with the reason) and `errors` (per plugin); they raise only for an unknown marketplace or plugin name and for a marketplace that cannot be fetched at all.
+
+The same operations are Rake tasks, loaded by the Railtie or with `require "ruby_llm/skills/tasks"` in a plain Rakefile:
+
+```bash
+rake skills:marketplaces:add[EveryInc/compound-writing]
+rake skills:marketplaces:add[typesafe-ai/skills,v0.5.7]
+rake skills:marketplaces:list
+rake skills:marketplaces:plugins[compound-writing]
+rake skills:marketplaces:install[compound-writing]
+rake skills:marketplaces:install[compound-writing,cw-draft cw-line-edit]
+rake skills:marketplaces:install          # reproduce skills.lock.json
+rake skills:marketplaces:update
+rake skills:marketplaces:remove[compound-writing]
+```
+
 ## Database Skills
 
 Store skills or commands in your database:
@@ -127,7 +182,7 @@ bin/setup
 ### Running Tests
 
 ```bash
-bundle exec rake test        # Unit tests (151 tests)
+bundle exec rake test        # Unit tests (300+ tests)
 bundle exec rake test_rails  # Rails integration tests (25+ tests)
 bundle exec rake test_all    # Both
 bundle exec rake             # Tests + linting

data/lib/ruby_llm/skills/agent_extensions.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "source_detection"
+
 module RubyLLM
   module Skills
     # Extensions for RubyLLM::Agent to enable declarative skill configuration.
@@ -16,9 +18,11 @@ module RubyLLM
     #   end
     #
     module AgentExtensions
-      REQUIRED_AGENT_SINGLETON_METHODS = %i[apply_configuration runtime_context llm_chat_for].freeze
+      REQUIRED_AGENT_SINGLETON_METHODS = %i[apply_configuration runtime_context].freeze
 
       module ClassMethods
+        include SourceDetection
+
         def self.extended(base)
           base.instance_variable_set(:@skill_sources, nil)
           base.instance_variable_set(:@skill_only, nil)
@@ -59,20 +63,12 @@ module RubyLLM
         def flatten_skill_sources(source)
           return [] if source.nil?
           return [source] if source.is_a?(String)
-          return [source] if loader_source?(source)
-          return [source] if database_collection_source?(source)
+          return [source] if loader_source?(source) || marketplace_source?(source)
+          return source.empty? ? [] : [source] if database_collection_source?(source)
           return source.flat_map { |item| flatten_skill_sources(item) } if source.is_a?(Array)
 
           [source]
         end
-
-        def loader_source?(source)
-          source.respond_to?(:list) && source.respond_to?(:find)
-        end
-
-        def database_collection_source?(source)
-          source.respond_to?(:to_a) && source.first&.respond_to?(:name) && source.first.respond_to?(:content)
-        end
       end
 
       module InstanceMethods
@@ -88,16 +84,21 @@ module RubyLLM
       end
 
       module ConfigurationPatch
-        private
-
-        def apply_configuration(chat_object, **kwargs)
+        # RubyLLM 2.0 passes either a RubyLLM::Chat or an acts_as_chat record.
+        # Both respond to #with_skills (ChatExtensions / ActiveRecordExtensions),
+        # so skills apply directly to whatever the agent configured.
+        #
+        # apply_configuration is a :nodoc: hook; **options forwards any keyword a
+        # later 2.x release adds so the patch fails at super, not before it.
+        def apply_configuration(chat, input_values: {}, **options)
           super
-          input_values = kwargs[:input_values] || {}
-          runtime = runtime_context(chat: chat_object, inputs: input_values)
-          apply_skills(llm_chat_for(chat_object), runtime)
+          runtime = runtime_context(chat: chat, inputs: input_values)
+          apply_skills(chat, runtime)
         end
 
-        def apply_skills(llm_chat, runtime)
+        private
+
+        def apply_skills(chat, runtime)
           config = skills
           sources = config[:sources]
           return if sources.nil?
@@ -112,7 +113,7 @@ module RubyLLM
           return if normalized_sources.empty?
 
           validate_skill_sources!(normalized_sources)
-          llm_chat.with_skills(*normalized_sources, only: config[:only])
+          chat.with_skills(*normalized_sources, only: config[:only])
         end
 
         def validate_skill_sources!(sources)
@@ -121,11 +122,11 @@ module RubyLLM
 
           invalid_types = invalid_sources.map { |source| source.class.name || source.class.to_s }.uniq.join(", ")
           raise ArgumentError,
-            "Invalid skill source(s): #{invalid_types}. Expected String path, Loader, or record collection."
+            "Invalid skill source(s): #{invalid_types}. Expected String path, Loader, marketplace registry, or record collection."
         end
 
         def valid_skill_source?(source)
-          source.is_a?(String) || loader_source?(source) || database_collection_source?(source)
+          source.is_a?(String) || loader_source?(source) || marketplace_source?(source) || database_collection_source?(source)
         end
       end
 

data/lib/ruby_llm/skills/chat_extensions.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "source_detection"
 require_relative "skill_tool"
 
 module RubyLLM
@@ -19,6 +20,8 @@ module RubyLLM
     #   chat.with_skills(only: [:pdf_report])
     #
     module ChatExtensions
+      include SourceDetection
+
       # Add skills to this chat.
       #
       # @param sources [Array] skill sources - auto-detects type (directory, zip, collection)
@@ -32,7 +35,7 @@ module RubyLLM
         loader = FilteredLoader.new(loader, only) if only
 
         skill_tool = RubyLLM::Skills::SkillTool.new(loader)
-        with_tool(skill_tool)
+        with_tools(skill_tool)
       end
 
       private
@@ -41,23 +44,17 @@ module RubyLLM
         case source
         when String
           RubyLLM::Skills.from_directory(source)
+        when ->(s) { marketplace_source?(s) }
+          source.loader
         when ->(s) { database_collection_source?(s) }
           RubyLLM::Skills.from_database(source)
         when ->(s) { loader_source?(s) }
           source
         else
           raise ArgumentError,
-            "Invalid skill source: #{source.class}. Expected String path, Loader, or record collection."
+            "Invalid skill source: #{source.class}. Expected String path, Loader, marketplace registry, or record collection."
         end
       end
-
-      def loader_source?(source)
-        source.respond_to?(:list) && source.respond_to?(:find)
-      end
-
-      def database_collection_source?(source)
-        source.respond_to?(:to_a) && source.first&.respond_to?(:name) && source.first.respond_to?(:content)
-      end
     end
 
     # Simple wrapper that filters skills by name.

data/lib/ruby_llm/skills/marketplace/bundle.rb

@@ -0,0 +1,367 @@
+# frozen_string_literal: true
+
+require "json"
+require "yaml"
+require "pathname"
+
+module RubyLLM
+  module Skills
+    module Marketplace
+      # One plugin's root tree, normalized into what the loaders read:
+      # `skills/<name>/**` validated by the Agent Skills rules (frontmatter
+      # `name` matches the directory, `description` present), `commands/*.md`
+      # rewritten to `skills/<name>.md` (single-file skills), `agents/**/*.md`
+      # kept verbatim, and plugin-level files a skill reaches through
+      # `../../x` or `${CLAUDE_PLUGIN_ROOT}/x` copied under `<skill>/.plugin/`
+      # with the reference rewritten. Hooks, MCP and LSP configuration,
+      # executables and everything else are dropped. The tree's sha256 is the
+      # plugin's integrity pin.
+      #
+      class Bundle
+        MANIFEST_PATHS = %w[.claude-plugin/plugin.json .codex-plugin/plugin.json .cursor-plugin/plugin.json].freeze
+        AGENT_PLUGINS_SCHEMA = "https://agent-plugins.org/schemas/"
+        SUPPORT_ROOT = ".plugin"
+        # Marketplace-entry display fields that win over plugin.json (Claude Code's rule).
+        ENTRY_DISPLAY_FIELDS = %w[displayName description author homepage repository license keywords category tags].freeze
+        ROOT_REFERENCE = %r{(?:\$\{(?:CLAUDE_)?PLUGIN_ROOT\}|<plugin-root>)/(\w[\w./-]*)}
+        RELATIVE_REFERENCE = %r{(?<![\w./-])((?:\.\./)+\w[\w./-]*)}
+
+        # One skill the plugin contributes; +kind+ is "skill" or "command".
+        Skill = Data.define(:name, :description, :kind, :path, :frontmatter, :files) do
+          def command? = kind == "command"
+
+          # Where the skill lives in the normalized tree.
+          def tree_path
+            command? ? "skills/#{name}.md" : "skills/#{name}"
+          end
+        end
+
+        # +files+ is the input tree as given (paths without a leading "./"); +tree+ the normalized output.
+        attr_reader :files, :name, :manifest, :manifest_path, :manifest_version, :entry, :tree, :skills, :agents,
+          :unsupported, :unresolved_references, :tree_sha256
+
+        # @param files [Hash{String => String}] the plugin root as `{ path => bytes }`
+        # @param entry [Manifest::Entry, nil] the marketplace entry, when there is one
+        # @param plugin_name [String, nil] a name to use when neither manifest nor entry has one
+        # @raise [InvalidPluginError]
+        def initialize(files, entry: nil, plugin_name: nil)
+          @files = files.transform_keys { |path| path.to_s.delete_prefix("./") }
+          @entry = entry
+          @manifest, @manifest_path, @manifest_version = discover_manifest
+          @name = (plugin_name || entry&.name || manifest["name"]).to_s.strip
+          raise InvalidPluginError, "plugin has no name (no manifest, no marketplace entry)" if @name.empty?
+          raise InvalidPluginError, "plugin name #{@name.inspect} is not kebab-case" unless @name.match?(Manifest::NAME_PATTERN)
+
+          @tree = {}
+          @consumed = []
+          @unsupported = []
+          @unresolved_references = []
+          @skills = collect_skills + collect_commands
+          check_skill_names!
+          @agents = collect_agents
+          relocate_references
+          @tree_sha256 = Tarball.tree_sha256(@tree)
+        end
+
+        # The plugin manifest's `version`, else the marketplace entry's, else nil.
+        def version
+          manifest_version || entry&.version
+        end
+
+        # "manifest" or "entry" when a version is declared, else nil.
+        def version_kind
+          return "manifest" if manifest_version
+          "entry" if entry&.version
+        end
+
+        def display_name
+          Manifest.presence(manifest["displayName"])
+        end
+
+        def description
+          Manifest.presence(manifest["description"])
+        end
+
+        def skill_names
+          skills.map(&:name)
+        end
+
+        # Nothing the loaders could serve.
+        def empty?
+          skills.empty? && agents.empty?
+        end
+
+        # Input paths that did not make it into the tree.
+        def dropped
+          @files.keys - @consumed
+        end
+
+        # Writes the tree under +dir+, replacing whatever was there.
+        def write!(dir)
+          FileUtils.rm_rf(dir)
+          Tarball.write_directory(tree, dir)
+        end
+
+        private
+
+        # --- manifest -----------------------------------------------------------
+
+        # [manifest, path, version]: +version+ is the plugin manifest's own
+        # (nil for a strict:false entry, whose version is the entry's).
+        def discover_manifest
+          if entry && !entry.strict?
+            return [entry.raw.except("source", "strict").merge(entry.overrides), nil, nil]
+          end
+
+          root = json_file("plugin.json")
+          data, path = if root.is_a?(Hash) && root["$schema"].to_s.start_with?(AGENT_PLUGINS_SCHEMA)
+            [root, "plugin.json"]
+          else
+            found = MANIFEST_PATHS.find { |candidate| @files.key?(candidate) }
+            [found ? json_file(found) : {}, found]
+          end
+          raise InvalidPluginError, "#{path} is not a JSON object" unless data.is_a?(Hash)
+
+          [merge_entry(data), path, Manifest.presence(data["version"])]
+        end
+
+        def merge_entry(data)
+          return data unless entry
+
+          merged = data.merge(entry.raw.slice(*ENTRY_DISPLAY_FIELDS).reject { |_, value| blank?(value) })
+          merged["version"] = Manifest.presence(data["version"]) || entry.version if Manifest.presence(data["version"]) || entry.version
+          merged["skills"] = Array(data["skills"]) + Array(entry.overrides["skills"]) if entry.overrides.key?("skills")
+          %w[commands agents].each { |key| merged[key] = entry.overrides[key] if entry.overrides.key?(key) }
+          merged
+        end
+
+        def json_file(path)
+          raw = @files[path]
+          return nil if raw.nil?
+
+          JSON.parse(text!(raw, path))
+        rescue JSON::ParserError => e
+          raise InvalidPluginError, "#{path} is not valid JSON (#{e.message[0, 60]})"
+        end
+
+        def text!(raw, path)
+          text = raw.to_s.dup.force_encoding(Encoding::UTF_8)
+          raise InvalidPluginError, "#{path} is not UTF-8 text" unless text.valid_encoding?
+
+          text
+        end
+
+        # A manifest path ("./skills/", "./custom/x.md", ".") to tree-relative, or raises when it escapes.
+        def manifest_paths(value)
+          Array(value).filter_map do |raw|
+            cleaned = Manifest.normalize_relative(raw.to_s, allow_blank: true)
+            raise InvalidPluginError, "manifest path #{raw.inspect} escapes the plugin root" if cleaned.nil?
+
+            cleaned
+          end.uniq
+        end
+
+        # --- skills --------------------------------------------------------------
+
+        def collect_skills
+          locations = (["skills"] + manifest_paths(manifest["skills"])).uniq
+          skills = locations.flat_map { |location| skills_at(location) }
+          skills << root_skill if @files.key?("SKILL.md") && skills.none? { |skill| skill.path == "" }
+          skills.each do |skill|
+            skill.files.each { |rel, data| @tree["skills/#{skill.name}/#{rel}"] = data }
+            @consumed.concat(skill.files.keys.map { |rel| skill.path.empty? ? rel : "#{skill.path}/#{rel}" })
+          end
+          skills
+        end
+
+        def skills_at(location)
+          return [] if location.empty?
+          return [skill_from_dir(location)] if @files.key?("#{location}/SKILL.md")
+
+          dirs = @files.keys.filter_map do |path|
+            next unless path.start_with?("#{location}/") && path.count("/") >= location.count("/") + 2
+
+            path.delete_prefix("#{location}/").split("/").first
+          end
+          dirs.uniq.sort.filter_map { |dir| skill_from_dir("#{location}/#{dir}") if @files.key?("#{location}/#{dir}/SKILL.md") }
+        end
+
+        def skill_from_dir(dir)
+          files = @files.select { |path, _| path.start_with?("#{dir}/") }.transform_keys { |path| path.delete_prefix("#{dir}/") }
+          frontmatter = frontmatter!(files.fetch("SKILL.md"), "#{dir}/SKILL.md")
+          skill_name = frontmatter["name"].to_s.strip
+          directory = File.basename(dir)
+          unless normalize_directory(skill_name) == normalize_directory(directory)
+            raise InvalidPluginError, "#{dir}: frontmatter name #{skill_name.inspect} does not match its directory #{directory.inspect}"
+          end
+
+          build_skill(skill_name, frontmatter, files, kind: "skill", path: dir)
+        end
+
+        def root_skill
+          files = @files.select { |path, _| path == "SKILL.md" || path.start_with?("scripts/", "references/", "assets/") }
+          frontmatter = frontmatter!(files.fetch("SKILL.md"), "SKILL.md")
+          build_skill(Manifest.presence(frontmatter["name"]) || name, frontmatter, files, kind: "skill", path: "")
+        end
+
+        def build_skill(skill_name, frontmatter, files, kind:, path:)
+          validate_skill_name!(skill_name, path)
+          description = frontmatter["description"].to_s.strip
+          where = path.empty? ? "SKILL.md" : path
+          raise InvalidPluginError, "#{where}: description is required" if description.empty?
+          raise InvalidPluginError, "#{where}: description exceeds #{Validator::DESCRIPTION_MAX_LENGTH} characters" if description.length > Validator::DESCRIPTION_MAX_LENGTH
+
+          Skill.new(name: skill_name, description: description, kind: kind, path: path, frontmatter: frontmatter, files: files)
+        end
+
+        def validate_skill_name!(skill_name, where)
+          return if skill_name.match?(Validator::NAME_PATTERN) && skill_name.length <= Validator::NAME_MAX_LENGTH
+
+          raise InvalidPluginError, "#{where}: skill name #{skill_name.inspect} must be lowercase letters, digits and single hyphens (1-#{Validator::NAME_MAX_LENGTH} chars)"
+        end
+
+        # Over skills and the commands that became skills: the cap and the names are one set.
+        def check_skill_names!
+          max = Marketplace.config.max_skills
+          raise InvalidPluginError, "plugin has more than #{max} skills" if @skills.size > max
+
+          duplicates = @skills.map(&:name).tally.select { |_, count| count > 1 }.keys
+          raise InvalidPluginError, "duplicate skill names #{duplicates.inspect}" if duplicates.any?
+        end
+
+        # --- commands ------------------------------------------------------------
+
+        def collect_commands
+          markdown_files_at(manifest.key?("commands") ? manifest_paths(manifest["commands"]) : ["commands"]).filter_map do |path|
+            command_from_file(path)
+          end
+        end
+
+        def markdown_files_at(locations)
+          locations.flat_map do |location|
+            next [location] if @files.key?(location) && location.end_with?(".md")
+
+            @files.keys.select { |path| path.start_with?("#{location}/") && path.end_with?(".md") }.sort
+          end.uniq
+        end
+
+        # A command keeps its body; only `name` is pinned to the file name so
+        # `/name` resolves. Without frontmatter or a description the loaders
+        # cannot list it, so it is listed as unsupported and dropped.
+        def command_from_file(path)
+          command_name = path.delete_suffix(".md").split("/").drop(1).join("-").downcase.tr("_", "-")
+          command_name = File.basename(path, ".md").downcase.tr("_", "-") if command_name.empty?
+          text = text!(@files.fetch(path), path)
+          frontmatter, body = split_frontmatter(text)
+          if frontmatter.nil? || frontmatter["description"].to_s.strip.empty?
+            @unsupported << {"name" => command_name, "path" => path, "reason" => frontmatter.nil? ? "missing_frontmatter" : "missing_description"}
+            return nil
+          end
+
+          validate_skill_name!(command_name, path)
+          pinned = frontmatter.merge("name" => command_name)
+          rewritten = "---\n#{YAML.dump(pinned).delete_prefix("---\n")}---\n#{body}"
+          @tree["skills/#{command_name}.md"] = rewritten
+          @consumed << path
+          build_skill(command_name, pinned, {"#{command_name}.md" => rewritten}, kind: "command", path: path)
+        end
+
+        # --- agents --------------------------------------------------------------
+
+        def collect_agents
+          markdown_files_at(manifest.key?("agents") ? manifest_paths(manifest["agents"]) : ["agents"]).map do |path|
+            rel = "agents/#{path.split("/").drop(1).join("/")}"
+            rel = "agents/#{File.basename(path)}" if rel == "agents/"
+            @tree[rel] = @files.fetch(path)
+            @consumed << path
+            rel
+          end
+        end
+
+        # --- references ----------------------------------------------------------
+
+        # A skill that reads a plugin-level file (`../../references/x.md`,
+        # `${CLAUDE_PLUGIN_ROOT}/defaults/`) gets a copy under `.plugin/` and
+        # the text rewritten, so the skill tool (skill-root only, no `..`) can
+        # serve it. Anything that resolves to nothing is left as text and listed.
+        def relocate_references
+          @skills.each do |skill|
+            next if skill.command?
+
+            skill.files.each_key do |rel|
+              next unless rel.end_with?(".md")
+
+              tree_path = "skills/#{skill.name}/#{rel}"
+              text = text!(@tree.fetch(tree_path), tree_path)
+              rewritten = text.gsub(ROOT_REFERENCE) { relocate(skill, rel, Regexp.last_match(1)) || Regexp.last_match(0) }
+              rewritten = rewritten.gsub(RELATIVE_REFERENCE) { relocate_relative(skill, rel, Regexp.last_match(1)) || Regexp.last_match(0) }
+              @tree[tree_path] = rewritten if rewritten != text
+            end
+          end
+        end
+
+        def relocate_relative(skill, rel, reference)
+          return nil if skill.path.empty?
+
+          source_dir = File.dirname(File.join(skill.path, rel))
+          target = File.expand_path(reference, "/#{source_dir}").delete_prefix("/")
+          return nil if target.empty? || target == skill.path || target.start_with?("#{skill.path}/") || target.start_with?("../")
+
+          relocate(skill, rel, target)
+        end
+
+        # Copies +plugin_path+ (a file, or every file under it) into the skill's
+        # support root; returns the rewritten reference relative to +rel+'s directory.
+        def relocate(skill, rel, plugin_path)
+          trimmed = plugin_path.sub(/[.,;:)\]'"`]+\z/, "")
+          trailing = plugin_path[trimmed.length..]
+          segments = trimmed.split("/")
+          candidates = segments.length.downto(1).map { |n| segments.first(n).join("/") }
+          matched = candidates.find { |candidate| @files.key?(candidate) || @files.keys.any? { |path| path.start_with?("#{candidate}/") } }
+          if matched.nil?
+            @unresolved_references << {"skill" => skill.name, "reference" => plugin_path}
+            return nil
+          end
+
+          @files.select { |path, _| path == matched || path.start_with?("#{matched}/") }.each do |path, data|
+            @tree["skills/#{skill.name}/#{SUPPORT_ROOT}/#{path}"] = data
+            @consumed << path
+          end
+          rest = trimmed.delete_prefix(matched)
+          from = File.dirname(rel)
+          relative = Pathname.new("#{SUPPORT_ROOT}/#{matched}").relative_path_from(Pathname.new((from == ".") ? "" : from).cleanpath).to_s
+          "#{relative}#{rest}#{trailing}"
+        end
+
+        # --- frontmatter ---------------------------------------------------------
+
+        def frontmatter!(raw, path)
+          frontmatter, _body = split_frontmatter(text!(raw, path))
+          raise InvalidPluginError, "#{path}: missing YAML frontmatter" if frontmatter.nil?
+
+          frontmatter
+        end
+
+        # [hash, body] when the text opens with a frontmatter block, else [nil, text].
+        def split_frontmatter(text)
+          return [nil, text] unless text.match?(Parser::FRONTMATTER_REGEX)
+
+          data = Parser.parse_string(text)
+          return [nil, text] unless data.is_a?(Hash)
+
+          [data.transform_keys(&:to_s), Parser.extract_body(text)]
+        rescue ParseError => e
+          raise InvalidPluginError, "invalid YAML frontmatter (#{e.message[0, 60]})"
+        end
+
+        def normalize_directory(value)
+          value.to_s.strip.downcase.tr("_", "-")
+        end
+
+        def blank?(value)
+          value.nil? || (value.respond_to?(:empty?) && value.empty?)
+        end
+      end
+    end
+  end
+end