skill 0.1.0

data/lib/skill/targets.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+module Skill
+  # Decides which folders a command installs to, lists, or updates: the
+  # folders of the agents named with +--agent+, the folders named with
+  # +--dir+, or else the ones the project or home folder shows signs of.
+  class Targets
+    # One folder skills are installed into, and the agents that read it.
+    Target = Struct.new(:path, :label, :agents, keyword_init: true)
+
+    # Files and folders in a project that show it uses an agent, beyond the
+    # agent's own skills folder.
+    PROJECT_SIGNS = {
+      'claude-code' => %w[.claude CLAUDE.md],
+      'codex' => %w[.codex AGENTS.md],
+      'cursor' => %w[.cursor .cursorrules],
+      'gemini-cli' => %w[.gemini GEMINI.md],
+      'github-copilot' => %w[.github/copilot-instructions.md],
+      'windsurf' => %w[.windsurf .windsurfrules]
+    }.freeze
+
+    # Folders in the home folder that show an agent is installed, for agents
+    # whose global skills folder is shared with others.
+    GLOBAL_SIGNS = {
+      'codex' => ['CODEX_HOME', '~/.codex'],
+      'cline' => [nil, '~/.cline'],
+      'zed' => [nil, '~/.config/zed'],
+      'warp' => [nil, '~/.warp']
+    }.freeze
+
+    SHARED_GLOBAL_DIRS = %w[~/.agents/skills {config}/agents/skills].freeze
+    FALLBACK = 'universal'
+
+    attr_reader :root, :home, :env
+
+    # +root+ is the project folder, ignored with +global+.
+    def initialize(root:, home:, env:, global: false)
+      @root = File.expand_path(root)
+      @home = File.expand_path(home)
+      @env = env
+      @global = global
+    end
+
+    def global?
+      @global
+    end
+
+    # Returns the Targets for +agents+ and +dirs+, or the detected ones when
+    # both are empty. Folders several agents share are returned once.
+    def resolve(agents: [], dirs: [])
+      chosen = agents_named(agents)
+      list = chosen.empty? && dirs.empty? ? detected : chosen.filter_map { |agent| target_for(agent, strict: true) }
+      list += dirs.map { |dir| Target.new(path: File.expand_path(dir, base), label: dir, agents: []) }
+      merge(list)
+    end
+
+    # Returns the Targets of every agent whose folder exists, for listing.
+    def existing
+      merge(Agents.all.filter_map { |agent| target_for(agent) }.select { |target| File.directory?(target.path) })
+    end
+
+    # Returns the agents the project or home folder shows signs of, or the
+    # shared +.agents/skills+ folder when it shows none.
+    def detected_agents
+      found = Agents.all.select { |agent| global? ? installed?(agent) : used_in_project?(agent) }
+      found.empty? ? [Agents.fetch(FALLBACK)] : found
+    end
+
+    # Returns +path+ as the lockfile records it: relative to the project, or
+    # starting with +~+ in the home folder.
+    def display(path)
+      expanded = File.expand_path(path)
+      if !global? && inside?(expanded, root)
+        expanded == root ? '.' : expanded.delete_prefix("#{root}/")
+      elsif inside?(expanded, home)
+        expanded == home ? '~' : "~/#{expanded.delete_prefix("#{home}/")}"
+      else
+        expanded
+      end
+    end
+
+    # Returns the absolute path of a folder the lockfile recorded.
+    def expand(path)
+      File.expand_path(path.to_s.sub(%r{\A~(?=/|\z)}, home), base)
+    end
+
+    # Returns the Boundary skills install inside: the project, or with
+    # +global+ the home folder and any global agent folder the environment
+    # moved elsewhere.
+    def boundary
+      @boundary ||= if global?
+                      folders = Agents.all.filter_map { |agent| Agents.global_path(agent, env: env, home: home) }
+                      Boundary.new([home, *folders], name: 'your home folder')
+                    else
+                      Boundary.new([root], name: 'the project')
+                    end
+    end
+
+    private
+
+    def base
+      global? ? home : root
+    end
+
+    def agents_named(names)
+      return Agents.all.select { |agent| global? ? agent.global? : true } if names.include?('*')
+
+      names.map { |name| Agents.fetch(name) }.uniq
+    end
+
+    def detected
+      detected_agents.filter_map { |agent| target_for(agent) }
+    end
+
+    def target_for(agent, strict: false)
+      path = global? ? Agents.global_path(agent, env: env, home: home) : File.join(root, agent.project_dir)
+      if path.nil?
+        raise UsageError, "#{agent.name} has no global skills folder; install it in a project" if strict
+
+        return
+      end
+      Target.new(path: path, label: display(path), agents: [agent.name])
+    end
+
+    def merge(targets)
+      targets.group_by(&:path).map do |path, group|
+        Target.new(path: path, label: display(path), agents: group.flat_map(&:agents).uniq)
+      end
+    end
+
+    def used_in_project?(agent)
+      return ruby_llm? if agent.key == 'rubyllm'
+      return File.directory?(File.join(root, agent.project_dir)) if agent.key == FALLBACK
+
+      (PROJECT_SIGNS.fetch(agent.key, []) + own_signs(agent)).any? { |sign| File.exist?(File.join(root, sign)) }
+    end
+
+    # An agent's own folder shows it is used, unless other tools share it
+    # (+.agents+) or it is too common a name to mean anything (+skills+).
+    def own_signs(agent)
+      dir = agent.project_dir
+      return [] if dir.start_with?('.agents/') || !dir.include?('/')
+
+      dir.start_with?('.') ? [dir.split('/').first] : [dir]
+    end
+
+    def ruby_llm?
+      return true if File.directory?(File.join(root, 'app/skills'))
+
+      %w[Gemfile.lock gems.locked Gemfile gems.rb].any? do |file|
+        path = File.join(root, file)
+        File.file?(path) && File.read(path, 256 * 1024).match?(/^\s*(?:gem\s+["']ruby_llm["']|ruby_llm \()/)
+      end
+    end
+
+    def installed?(agent)
+      return false unless agent.global?
+
+      if GLOBAL_SIGNS.key?(agent.key)
+        variable, default = GLOBAL_SIGNS[agent.key]
+        dir = variable && !env[variable].to_s.empty? ? env[variable] : default
+        return File.directory?(expand(dir))
+      end
+      return false if SHARED_GLOBAL_DIRS.include?(agent.global_dir)
+
+      File.directory?(File.dirname(Agents.global_path(agent, env: env, home: home)))
+    end
+
+    def inside?(path, folder)
+      path == folder || path.start_with?("#{folder}/")
+    end
+  end
+end

data/lib/skill/tree.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'find'
+
+module Skill
+  # The files of one skill folder: their paths, contents' SHA-256, and
+  # whether they are executable. Comparing two Trees shows what an update
+  # changes; a Tree's digest shows whether an installed skill was edited.
+  class Tree
+    Entry = Struct.new(:sha256, :bytes, :executable, keyword_init: true)
+    Diff = Struct.new(:added, :changed, :removed, keyword_init: true) do
+      def empty?
+        added.empty? && changed.empty? && removed.empty?
+      end
+    end
+
+    attr_reader :root, :entries
+
+    # Reads the folder at +root+. Raises UnsafeError when it holds a link,
+    # anything other than files and folders, or more than +limits+ allow.
+    def self.read(root, limits: Limits.new)
+      new(root, scan(root.to_s, limits))
+    end
+
+    def self.scan(root, limits)
+      raise UnsafeError, "#{root} is a link" if File.symlink?(root)
+
+      entries = {}
+      total = 0
+      Find.find(root) do |path|
+        next if path == root
+
+        relative = path.delete_prefix("#{root}/")
+        stat = File.lstat(path)
+        raise UnsafeError, "#{relative} in #{File.basename(root)} is a link; skills may not hold links" if stat.symlink?
+        next if stat.directory?
+        raise UnsafeError, "#{relative} in #{File.basename(root)} is not a regular file" unless stat.file?
+
+        total += stat.size
+        too_large!(root, limits) if entries.size >= limits.skill_files || total > limits.skill_bytes
+
+        entries[relative] = Entry.new(sha256: Digest::SHA256.file(path).hexdigest, bytes: stat.size,
+                                      executable: stat.mode.anybits?(0o111)).freeze
+      end
+      entries.sort.to_h.freeze
+    end
+
+    def self.too_large!(root, limits)
+      raise UnsafeError,
+            "#{File.basename(root)} is larger than #{limits.skill_files} files or #{limits.skill_bytes} bytes. " \
+            'Set SKILL_MAX_SKILL_FILES or SKILL_MAX_SKILL_BYTES higher for a source you trust'
+    end
+    private_class_method :scan, :too_large!
+
+    def initialize(root, entries)
+      @root = root.to_s
+      @entries = entries
+    end
+
+    # Returns the digest of the files and their modes, as
+    # "sha256-<hex>". +executable+ false ignores modes, for a copy that
+    # dropped them.
+    def digest(executable: true)
+      lines = entries.map { |path, entry| "#{path}\0#{executable && entry.executable ? 'x' : '-'}\0#{entry.sha256}\n" }
+      "sha256-#{Digest::SHA256.hexdigest(lines.join)}"
+    end
+
+    # Returns the paths of executable files.
+    def executables
+      entries.select { |_path, entry| entry.executable }.keys
+    end
+
+    # Returns the size of every file together.
+    def bytes
+      entries.values.sum(&:bytes)
+    end
+
+    # Returns what changes from +before+ to this Tree. Mode changes count
+    # only when +executable+ is true.
+    def diff_from(before, executable: true)
+      old = before ? before.entries : {}
+      changed = entries.select do |path, entry|
+        previous = old[path]
+        previous && (previous.sha256 != entry.sha256 || (executable && previous.executable != entry.executable))
+      end
+      Diff.new(added: (entries.keys - old.keys), changed: changed.keys, removed: (old.keys - entries.keys))
+    end
+  end
+end

data/lib/skill/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Skill
+  VERSION = '0.1.0'
+end

data/lib/skill/workspace.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+module Skill
+  # Where a command works: a project (found from the current folder) or the
+  # home folder, with its Targets and its Lockfile. Knows whether a folder
+  # it would replace or delete is still what it installed.
+  class Workspace
+    ROOT_MARKERS = %w[skills.lock Gemfile gems.rb .git package.json].freeze
+    AGENT_MARKERS = %w[.agents .claude .codex .cursor .gemini .windsurf AGENTS.md CLAUDE.md GEMINI.md].freeze
+
+    attr_reader :root, :targets, :lock
+
+    # Opens the project around +cwd+, or the home folder with +global+.
+    # With +global+ +nil+, uses the home folder when +cwd+ is in no
+    # project, the way a person running it there expects.
+    def self.open(cwd:, home:, env:, global:, limits:)
+      project = project_root(cwd, home)
+      global = project.nil? if global.nil?
+      root = global ? home : project || cwd
+      lock = global ? Lockfile.global_path(env: env, home: home) : File.join(root, Lockfile::NAME)
+      new(root: root, targets: Targets.new(root: root, home: home, env: env, global: global),
+          lock: Lockfile.new(lock), limits: limits)
+    end
+
+    # Returns the nearest folder from +cwd+ up holding a lockfile, a
+    # Gemfile, a git repository, or a package.json, else the nearest
+    # holding an agent's folder or instructions (+.claude+, +AGENTS.md+...),
+    # else +nil+. The home folder, where agents keep their global folders,
+    # is never a project, and the search stops there.
+    def self.project_root(cwd, home)
+      agent_folder = nil
+      directory = cwd
+      until directory == home
+        return directory if ROOT_MARKERS.any? { |marker| File.exist?(File.join(directory, marker)) }
+
+        agent_folder ||= directory if AGENT_MARKERS.any? { |marker| File.exist?(File.join(directory, marker)) }
+        parent = File.dirname(directory)
+        break if parent == directory
+
+        directory = parent
+      end
+      agent_folder
+    end
+
+    # Returns whether this is the home folder rather than a project.
+    def global?
+      targets.global?
+    end
+
+    def initialize(root:, targets:, lock:, limits:)
+      @root = root
+      @targets = targets
+      @lock = lock
+      @limits = limits
+    end
+
+    # Returns +path+ as people read it: relative to the project, or from +~+.
+    def display(path)
+      targets.display(path)
+    end
+
+    # Returns how the lockfile records +source+: +owner/repo+, or a path
+    # starting with +./+, +../+, +~/+, or +/+.
+    def source_label(source)
+      return source.name if source.github?
+
+      path = display(source.path)
+      path.start_with?('/', '~', '.') ? path : "./#{path}"
+    end
+
+    # Returns the Source a lockfile +entry+ came from.
+    def source_of(entry)
+      Source.parse(entry['source'], root: root, ref: entry['ref'])
+    end
+
+    # Returns the absolute target folders a lockfile +entry+ records,
+    # without checking where they lead.
+    def recorded_folders(entry)
+      Array(entry['targets']).map { |path| targets.expand(path) }
+    end
+
+    # Returns the absolute target folders a lockfile +entry+ records. Raises
+    # UnsafeError when one leads outside the project, or with +global+
+    # outside the home folder.
+    def folders(entry)
+      recorded_folders(entry).each do |folder|
+        next if targets.boundary.include?(folder)
+
+        raise UnsafeError, "#{display(lock.path)} installs into #{display(folder)}, outside " \
+                           "#{targets.boundary.name}. Fix or delete that entry"
+      end
+    end
+
+    # Returns the target folders for +agents+ and +dirs+, or the detected
+    # ones. Raises UnsafeError when one leads outside the project, or with
+    # +global+ outside the home folder.
+    def resolve(agents: [], dirs: [])
+      targets.resolve(agents: agents, dirs: dirs).map(&:path).each do |folder|
+        next if targets.boundary.include?(folder)
+
+        raise UnsafeError, "#{display(folder)} leads outside #{targets.boundary.name}. Skills install only inside it"
+      end
+    end
+
+    # Returns whether the skill folder at +path+ still holds what +entry+
+    # recorded.
+    def unchanged?(path, entry)
+      return false unless entry && File.directory?(path)
+
+      Tree.read(path, limits: @limits).digest(executable: entry['executable'] ? true : false) == entry['digest']
+    rescue UnsafeError
+      false
+    end
+
+    # Raises ConflictError when the skill +name+ in +folder+ was edited
+    # since it was installed, unless +force+.
+    def ensure_unedited(name, folder, force)
+      destination = Installer.destination(folder, name)
+      return if !File.exist?(destination) || force || unchanged?(destination, lock[name])
+
+      raise ConflictError, "#{display(destination)} was edited since it was installed. Pass --force to replace it"
+    end
+
+    # Raises ConflictError when installing +name+ into +folder+ would
+    # replace something this command did not install, or edited since.
+    def ensure_replaceable(name, folder, force)
+      destination = Installer.destination(folder, name)
+      return if force || !(File.exist?(destination) || File.symlink?(destination))
+
+      entry = lock[name]
+      unless entry && folders(entry).include?(File.expand_path(folder))
+        raise ConflictError, "#{display(destination)} exists and was not installed by skill. Pass --force to replace it"
+      end
+
+      ensure_unedited(name, folder, false)
+    end
+
+    # Returns the state of an installed skill: ok, edited, missing, partly
+    # missing, or outside the project (or home folder) when the lockfile
+    # points elsewhere.
+    def status(name, entry)
+      boundary = targets.boundary
+      return "outside #{boundary.name}" unless recorded_folders(entry).all? { |folder| boundary.include?(folder) }
+
+      paths = folders(entry).map { |folder| Installer.destination(folder, name) }
+      present = paths.select { |path| File.directory?(path) }
+      return 'missing' if present.empty?
+      return 'partly missing' if present.size < paths.size
+
+      paths.all? { |path| unchanged?(path, entry) } ? 'ok' : 'edited'
+    end
+
+    # Returns one line saying where a lockfile +entry+ came from.
+    def self.describe(entry)
+      text = entry['source'].dup
+      text << "##{entry['ref']}" if entry['ref']
+      text << " (#{entry['ref_type']} at #{entry['commit'][0, 12]})" if entry['commit']
+      text
+    end
+  end
+end

data/lib/skill.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require_relative 'skill/version'
+
+# Installs Agent Skills, folders holding a +SKILL.md+, from GitHub
+# repositories, plugin marketplaces, and local directories into the folders
+# RubyLLM and coding agents read them from.
+#
+# The command line is the main interface:
+#
+#   gem exec skill add anthropics/skills@pdf
+#
+# Everything loads on first use, so the command starts fast.
+module Skill
+  # Raised for every problem the command reports to the person running it.
+  class Error < StandardError; end
+
+  # Raised when a command line is malformed.
+  class UsageError < Error; end
+
+  # Raised when a +SKILL.md+ breaks the Agent Skills specification.
+  class InvalidSkillError < Error; end
+
+  # Raised when a repository, ref, or skill does not exist.
+  class NotFoundError < Error; end
+
+  # Raised when an archive or a skill folder holds something unsafe: a path
+  # leaving its folder, a link, or more data than the limits allow.
+  class UnsafeError < Error; end
+
+  # Raised when installing would overwrite something the command does not own.
+  class ConflictError < Error; end
+
+  # Raised when a download fails.
+  class NetworkError < Error; end
+
+  # Raised when a download is larger than its limit.
+  class TooLargeError < NetworkError; end
+
+  autoload :Agents, 'skill/agents'
+  autoload :Archive, 'skill/archive'
+  autoload :Boundary, 'skill/boundary'
+  autoload :CLI, 'skill/cli'
+  autoload :Commands, 'skill/commands'
+  autoload :Directory, 'skill/directory'
+  autoload :Discovery, 'skill/discovery'
+  autoload :Fetcher, 'skill/fetcher'
+  autoload :GitHub, 'skill/github'
+  autoload :HTTP, 'skill/http'
+  autoload :Installer, 'skill/installer'
+  autoload :Limits, 'skill/limits'
+  autoload :Lockfile, 'skill/lockfile'
+  autoload :Manifest, 'skill/manifest'
+  autoload :Session, 'skill/session'
+  autoload :Source, 'skill/source'
+  autoload :Style, 'skill/style'
+  autoload :Targets, 'skill/targets'
+  autoload :Tree, 'skill/tree'
+  autoload :Workspace, 'skill/workspace'
+end

metadata

@@ -0,0 +1,84 @@
+--- !ruby/object:Gem::Specification
+name: skill
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Carmine Paolino
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Installs Agent Skills, folders holding a SKILL.md, from GitHub repositories,
+  plugin marketplaces, and local folders into RubyLLM's app/skills and the folders
+  Claude Code, Codex, Cursor, and other agents read. Records each skill's source and
+  commit in skills.lock, shows what changes before an update, and refuses unsafe archives.
+  Run it with `gem exec skill add owner/repo`.
+email:
+- carmine@paolino.me
+executables:
+- skill
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- exe/skill
+- lib/skill.rb
+- lib/skill/agents.rb
+- lib/skill/archive.rb
+- lib/skill/boundary.rb
+- lib/skill/cli.rb
+- lib/skill/commands.rb
+- lib/skill/commands/add.rb
+- lib/skill/commands/agents.rb
+- lib/skill/commands/command.rb
+- lib/skill/commands/find.rb
+- lib/skill/commands/list.rb
+- lib/skill/commands/remove.rb
+- lib/skill/commands/selection.rb
+- lib/skill/commands/update.rb
+- lib/skill/directory.rb
+- lib/skill/discovery.rb
+- lib/skill/fetcher.rb
+- lib/skill/github.rb
+- lib/skill/http.rb
+- lib/skill/installer.rb
+- lib/skill/limits.rb
+- lib/skill/lockfile.rb
+- lib/skill/manifest.rb
+- lib/skill/session.rb
+- lib/skill/source.rb
+- lib/skill/style.rb
+- lib/skill/targets.rb
+- lib/skill/tree.rb
+- lib/skill/version.rb
+- lib/skill/workspace.rb
+homepage: https://github.com/crmne/skill
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/crmne/skill
+  source_code_uri: https://github.com/crmne/skill
+  changelog_uri: https://github.com/crmne/skill/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/crmne/skill/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: Install Agent Skills into RubyLLM apps and coding agents.
+test_files: []