ruby-skills 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7280b4bcc88be0ead80c3553f82357e294dff35ea86d6c9ac6d8887d3191bd5c
+  data.tar.gz: e69af730461bdeadf3f11778f5dfd208b5d2288c70ec2edcee3db226f561b449
+SHA512:
+  metadata.gz: 51aab53ad414ea98a590a0cfc458d6a34b525501c70fa27eefb17e09d51e4a168b7dc5a6926910c366ebf031635d2e79235f7ad3ec6011353965b120ce891a56
+  data.tar.gz: 9c4d8b9776bda7309d9500e2c4223e09792338d221eae62d89e789b98b61845cc2b0a0254d5c0cf687658d0e9e65990f99be2d8788e6ad297fad1cd0260252b4

data/.rspec

@@ -0,0 +1,3 @@
+--require spec_helper
+--format documentation
+--color

data/.rubocop.yml

@@ -0,0 +1,46 @@
+plugins:
+  - rubocop-performance
+  - rubocop-rspec
+
+AllCops:
+  NewCops: enable
+  TargetRubyVersion: 3.1
+  SuggestExtensions: false
+  Exclude:
+    - "bin/*"
+    - "tmp/**/*"
+    - "vendor/**/*"
+    - "doc/**/*"
+
+Layout/LineLength:
+  Max: 100
+
+Metrics/AbcSize:
+  Enabled: false
+
+Metrics/MethodLength:
+  Enabled: false
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes
+
+Style/BlockDelimiters:
+  EnforcedStyle: semantic
+
+Style/OptionalBooleanParameter:
+  Enabled: false
+
+Gemspec/DevelopmentDependencies:
+  Enabled: false
+
+RSpec/ExampleLength:
+  Max: 40
+
+RSpec/MultipleExpectations:
+  Max: 8
+
+RSpec/MultipleDescribes:
+  Enabled: false

data/.yardopts

@@ -0,0 +1,5 @@
+--title "Ruby Skills"
+--markup markdown
+--no-private
+--output-dir doc
+lib/**/*.rb

data/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,110 @@
+PATH
+  remote: .
+  specs:
+    ruby-skills (0.1.0)
+      thor (~> 1.3)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ast (2.4.3)
+    diff-lcs (1.6.2)
+    json (2.21.2)
+    language_server-protocol (3.17.0.6)
+    lint_roller (1.1.0)
+    parallel (2.1.0)
+    parser (3.3.12.0)
+      ast (~> 2.4.1)
+      racc
+    prism (1.9.0)
+    racc (1.8.1)
+    rainbow (3.1.1)
+    rake (13.4.2)
+    regexp_parser (2.12.0)
+    rspec (3.13.2)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.6)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.8)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.7)
+    rubocop (1.89.0)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      parallel (>= 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.50.0)
+      parser (>= 3.3.7.2)
+      prism (~> 1.7)
+    rubocop-performance (1.27.0)
+      lint_roller (~> 1.1)
+      rubocop (>= 1.89.0, < 2.0)
+      rubocop-ast (>= 1.47.1, < 2.0)
+    rubocop-rspec (3.10.2)
+      lint_roller (~> 1.1)
+      regexp_parser (>= 2.0)
+      rubocop (~> 1.86, >= 1.86.2)
+    ruby-progressbar (1.13.0)
+    thor (1.5.0)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.2.0)
+    yard (0.9.45)
+
+PLATFORMS
+  ruby
+  x86_64-linux
+
+DEPENDENCIES
+  rake (~> 13.0)
+  rspec (~> 3.12)
+  rubocop (~> 1.58)
+  rubocop-performance (~> 1.20)
+  rubocop-rspec (~> 3.0)
+  ruby-skills!
+  yard (~> 0.9)
+
+CHECKSUMS
+  ast (2.4.3) sha256=954615157c1d6a382bc27d690d973195e79db7f55e9765ac7c481c60bdb4d383
+  bundler (4.0.17) sha256=214e21431b5665dd2f99df8a5511c6b151d7a72e8015c8b38f8b775b61cbb6c1
+  diff-lcs (1.6.2) sha256=9ae0d2cba7d4df3075fe8cd8602a8604993efc0dfa934cff568969efb1909962
+  json (2.21.2) sha256=1f1d3b7cf2b3ba1a69beca0bb6db13d5438b80bff3cd54cdaaa620b9b07c1c6a
+  language_server-protocol (3.17.0.6) sha256=5ef2c0c138f8267e1bc631d3328347d354f96724b0af22f2c79516120443b7f0
+  lint_roller (1.1.0) sha256=2c0c845b632a7d172cb849cc90c1bce937a28c5c8ccccb50dfd46a485003cc87
+  parallel (2.1.0) sha256=b35258865c2e31134c5ecb708beaaf6772adf9d5efae28e93e99260877b09356
+  parser (3.3.12.0) sha256=21a6d7f755d5a24dfbdc6e6b772e4e879a52e7631a88bc5a3a134606052c9828
+  prism (1.9.0) sha256=7b530c6a9f92c24300014919c9dcbc055bf4cdf51ec30aed099b06cd6674ef85
+  racc (1.8.1) sha256=4a7f6929691dbec8b5209a0b373bc2614882b55fc5d2e447a21aaa691303d62f
+  rainbow (3.1.1) sha256=039491aa3a89f42efa1d6dec2fc4e62ede96eb6acd95e52f1ad581182b79bc6a
+  rake (13.4.2) sha256=cb825b2bd5f1f8e91ca37bddb4b9aaf345551b4731da62949be002fa89283701
+  regexp_parser (2.12.0) sha256=35a916a1d63190ab5c9009457136ae5f3c0c7512d60291d0d1378ba18ce08ebb
+  rspec (3.13.2) sha256=206284a08ad798e61f86d7ca3e376718d52c0bc944626b2349266f239f820587
+  rspec-core (3.13.6) sha256=a8823c6411667b60a8bca135364351dda34cd55e44ff94c4be4633b37d828b2d
+  rspec-expectations (3.13.5) sha256=33a4d3a1d95060aea4c94e9f237030a8f9eae5615e9bd85718fe3a09e4b58836
+  rspec-mocks (3.13.8) sha256=086ad3d3d17533f4237643de0b5c42f04b66348c28bf6b9c2d3f4a3b01af1d47
+  rspec-support (3.13.7) sha256=0640e5570872aafefd79867901deeeeb40b0c9875a36b983d85f54fb7381c47c
+  rubocop (1.89.0) sha256=4dee8e3ee9c45e474834efd9e8d6fd031e8331c8dacdff0de4ad65ae0a6faae7
+  rubocop-ast (1.50.0) sha256=b9ca88300da0803ee222ad20cdb30494c0a784eed06fdc35d254b06d662788db
+  rubocop-performance (1.27.0) sha256=eeeb1374d062a368ee1c787b70eb0b0cc4b184cb1f8565f424760946146d61ce
+  rubocop-rspec (3.10.2) sha256=0b3e2ecc592cd10ecbf0095bb58d1e357905276e069643523cc19eb7495f65e2
+  ruby-progressbar (1.13.0) sha256=80fc9c47a9b640d6834e0dc7b3c94c9df37f08cb072b7761e4a71e22cff29b33
+  ruby-skills (0.1.0)
+  thor (1.5.0) sha256=e3a9e55fe857e44859ce104a84675ab6e8cd59c650a49106a05f55f136425e73
+  unicode-display_width (3.2.0) sha256=0cdd96b5681a5949cdbc2c55e7b420facae74c4aaf9a9815eee1087cb1853c42
+  unicode-emoji (4.2.0) sha256=519e69150f75652e40bf736106cfbc8f0f73aa3fb6a65afe62fefa7f80b0f80f
+  yard (0.9.45) sha256=52e211493f7cb8a3ebf7e104a25a1e73937a3103092545d34cb88fafebb3dc51
+
+BUNDLED WITH
+  4.0.17

data/README.md

@@ -0,0 +1,120 @@
+# ruby-skills
+
+Package manager for installing, updating, removing, and sharing AI development skills in Ruby and Rails projects.
+
+Skills are declared in a `Skillfile`, copied into `.ruby-skills/`, recorded in `Skills.lock`, and exposed to editors through adapters (Claude, Codex, Cursor, VS Code).
+
+## Requirements
+
+- Ruby 3.2 or later
+- [Thor](https://github.com/rails/thor) `~> 1.3` (pulled in by the gem)
+
+## Install
+
+From a checkout:
+
+```bash
+bundle install
+ruby -Ilib bin/ruby-skills version
+```
+
+Once published:
+
+```bash
+gem install ruby-skills
+```
+
+## Quick start
+
+```bash
+ruby-skills init
+```
+
+That creates a `Skillfile` and a `.ruby-skills/` directory. Declare skills in the Skillfile:
+
+```ruby
+# Skillfile
+
+skill "rails-performance",
+  github: "username/rails-performance"
+
+skill "local-review",
+  path: "../skills/local-review",
+  version: "0.1.0"
+```
+
+Each `skill` needs exactly one source: `github:` (`owner/repo`) or `path:`. `version:` is optional.
+
+Then install:
+
+```bash
+ruby-skills install
+ruby-skills install rails-performance
+```
+
+## Commands
+
+| Command | Description |
+| --- | --- |
+| `ruby-skills init` | Create `Skillfile` and `.ruby-skills/` |
+| `ruby-skills install [SKILL]` | Install one skill, or every skill in the Skillfile |
+| `ruby-skills list` | Print installed skills from `Skills.lock` |
+| `ruby-skills list --json` | Same data as JSON (`-j`) |
+| `ruby-skills update [SKILL]` | Update one skill, or every installed skill |
+| `ruby-skills remove SKILL` | Remove an installed skill |
+| `ruby-skills version` | Print the gem version |
+| `ruby-skills help [COMMAND]` | Command help |
+
+Human-readable list:
+
+```
+Installed skills:
+
+rails-performance                   0.1.0
+rails-security                      0.2.0
+```
+
+Machine-readable list (`ruby-skills list --json`):
+
+```json
+{
+  "skills": [
+    {
+      "name": "rails-performance",
+      "version": "0.1.0",
+      "source": "github:username/rails-performance"
+    }
+  ]
+}
+```
+
+An empty lockfile prints `{"skills":[]}`. Editors should consume `--json` instead of parsing the table.
+
+## Project files
+
+| Path | Role |
+| --- | --- |
+| `Skillfile` | Declared skills (Ruby DSL) |
+| `Skills.lock` | Installed name, version, and source |
+| `.ruby-skills/` | Local copies of installed skills |
+
+`Skillfile` and `Skills.lock` are gitignored in this repo because they are per-project workspace files created by `init` / `install`.
+
+## Editor plugins
+
+Install still notifies Claude, Codex, Cursor, and VS Code adapters so the skill is visible in those tools.
+
+The VS Code extension lives in [`rubyskills-plugins/rubyskills-vscode`](../rubyskills-plugins/rubyskills-vscode). It wraps this CLI and loads the sidebar from `ruby-skills list --json`.
+
+## Development
+
+```bash
+bundle install
+ruby -Ilib bin/ruby-skills help
+```
+
+Library code is under `lib/ruby_skills/`. The executable is `bin/ruby-skills`.
+
+## License
+
+MIT

data/Rakefile

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "rubocop/rake_task"
+require "yard"
+
+RSpec::Core::RakeTask.new(:spec)
+RuboCop::RakeTask.new
+
+YARD::Rake::YardocTask.new do |t|
+  t.files = ["lib/**/*.rb"]
+  t.stats_options = ["--list-undoc"]
+end
+
+task default: :spec
+task docs: :yard

data/bin/ruby-skills

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "ruby_skills"
+
+RubySkills::CLI.start(ARGV)

data/lib/ruby_skills/adapters/base.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module RubySkills
+  module Adapters
+    # Base implementation for skill adapters.
+    #
+    # Subclasses must define an ADAPTER_INFO constant containing:
+    #
+    # - :adapter   — tool directory under the project root
+    # - :directory — directory containing skills
+    #
+    # @abstract
+    # @since 0.1.0
+    class Base
+      # @param root [String, Pathname] project root
+      def initialize(root: Dir.pwd)
+        @root = Pathname.new(root)
+      end
+
+      # Install a skill into the adapter destination.
+      #
+      # @param name [String] skill identifier
+      # @param source [String, Pathname] source skill path
+      # @return [void]
+      def install(name, source)
+        link(source, destination_for(name))
+      end
+
+      # Remove an installed skill.
+      #
+      # @param name [String] skill identifier
+      # @return [void]
+      def remove(name)
+        FileUtils.rm_rf(destination_for(name))
+      end
+
+      private
+
+      attr_reader :root
+
+      # @return [Hash{Symbol => String}]
+      def adapter_info
+        self.class::ADAPTER_INFO
+      end
+
+      # @param name [String]
+      # @return [Pathname]
+      def destination_for(name)
+        root.join(
+          adapter_info.fetch(:adapter),
+          adapter_info.fetch(:directory),
+          name
+        )
+      end
+    end
+  end
+end

data/lib/ruby_skills/adapters/claude.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module RubySkills
+  module Adapters
+    # Exposes skills to Claude Code under +.claude/skills+.
+    #
+    # @see RubySkills::Adapters::Base
+    # @since 0.1.0
+    class Claude < Base
+      # Path fragments that locate Claude skills.
+      #
+      # @return [Hash{Symbol => String}]
+      ADAPTER_INFO = {
+        adapter: ".claude",
+        directory: "skills"
+      }.freeze
+    end
+  end
+end

data/lib/ruby_skills/adapters/codex.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module RubySkills
+  module Adapters
+    # Exposes skills to Codex under +.codex/skills+.
+    #
+    # @see RubySkills::Adapters::Base
+    # @since 0.1.0
+    class Codex < Base
+      # Path fragments that locate Codex skills.
+      #
+      # @return [Hash{Symbol => String}]
+      ADAPTER_INFO = {
+        adapter: ".codex",
+        directory: "skills"
+      }.freeze
+    end
+  end
+end

data/lib/ruby_skills/adapters/cursor.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module RubySkills
+  module Adapters
+    # Exposes skills to Cursor under +.cursor/skills+.
+    #
+    # @see RubySkills::Adapters::Base
+    # @since 0.1.0
+    class Cursor < Base
+      # Path fragments that locate Cursor skills.
+      #
+      # @return [Hash{Symbol => String}]
+      ADAPTER_INFO = {
+        adapter: ".cursor",
+        directory: "skills"
+      }.freeze
+    end
+  end
+end

data/lib/ruby_skills/adapters/vscode.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module RubySkills
+  module Adapters
+    # Exposes skills to VS Code under +.vscode/skills+.
+    #
+    # @see RubySkills::Adapters::Base
+    # @since 0.1.0
+    class Vscode < Base
+      # Path fragments that locate VS Code skills.
+      #
+      # @return [Hash{Symbol => String}]
+      ADAPTER_INFO = {
+        adapter: ".vscode",
+        directory: "skills"
+      }.freeze
+    end
+  end
+end

data/lib/ruby_skills/cli.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require "json"
+require "thor"
+
+module RubySkills
+  # Thor-based command-line interface for Ruby Skills.
+  #
+  # The default command is {#help}. +-h+ and +--help+ are aliases for it.
+  #
+  # @example Initialize a project
+  #   RubySkills::CLI.start(["init"])
+  #
+  # @since 0.1.0
+  class CLI < Thor
+    # Display name used in Thor help banners.
+    package_name "ruby-skills"
+
+    # Show {#help} when no command is given.
+    default_command :help
+
+    # Accept +-h+ and +--help+ as aliases for {#help}.
+    map %w[-h --help] => :help
+
+    desc "help [COMMAND]", "List all commands or show help for one command"
+    # List every available command, or describe a single command.
+    #
+    # @param command [String, nil] command to describe, or +nil+ to list all
+    # @param subcommand [Boolean] whether +command+ is a subcommand
+    # @return [void]
+    def help(command = nil, subcommand = false)
+      super
+    end
+
+    desc "init", "Initialize Ruby Skills in the current project"
+    # Create a Skillfile and +.ruby-skills+ directory in the current project.
+    #
+    # @return [void]
+    # @raise [SystemExit] when initialization fails
+    def init
+      config = Config.new
+
+      config.initialize_project!
+
+      say "Ruby Skills initialized"
+      say " Skillfile created"
+      say " .ruby-skills directory created"
+    rescue RubySkills::Error => e
+      say "Error: #{e.message}", :red
+      exit 1
+    end
+
+    desc "install [Skill]", "Install one skill or all skills from Skillfile"
+    # Install one skill or every skill declared in the Skillfile.
+    #
+    # @param skill [String, nil] skill name to install, or +nil+ to install all
+    # @return [void]
+    # @raise [SystemExit] when installation fails
+    def install(skill = nil)
+      Installer.new.install(skill)
+    rescue RubySkills::Error => e
+      say "Error: #{e.message}", :red
+      exit 1
+    end
+
+    desc "list", "List installed skills"
+    option :json, type: :boolean, default: false, aliases: "-j",
+                  desc: "Output installed skills as JSON"
+    # Print installed skills from the lockfile.
+    #
+    # With +--json+, emit a machine-readable payload instead of a table.
+    #
+    # @return [void]
+    def list
+      skills = Lockfile.new.skills
+
+      if options[:json]
+        puts JSON.generate(list_payload(skills))
+        return
+      end
+
+      if skills.empty?
+        say "No skills installed."
+        return
+      end
+
+      say "Installed skills:"
+      say ""
+
+      skills.each do |name, data|
+        say "#{name.ljust(35)} #{data["version"]}"
+      end
+    end
+
+    desc "remove SKILL", "Remove an installed skill"
+    # Remove an installed skill from the project.
+    #
+    # @param skill [String] name of the skill to remove
+    # @return [void]
+    # @raise [SystemExit] when removal fails
+    def remove(skill)
+      Remover.new.remove(skill)
+    rescue RubySkills::Error => e
+      say "Error: #{e.message}", :red
+      exit 1
+    end
+
+    desc "update [SKILL]", "Update one skill or all installed skills"
+    # Update one skill or every installed skill.
+    #
+    # @param skill [String, nil] skill name to update, or +nil+ to update all
+    # @return [void]
+    # @raise [SystemExit] when the update fails
+    def update(skill = nil)
+      Updater.new.update(skill)
+    rescue RubySkills::Error => e
+      say "Error: #{e.message}", :red
+      exit 1
+    end
+
+    desc "version", "Display Ruby Skills version"
+    # Print the installed gem version.
+    #
+    # @return [void]
+    def version
+      say "ruby-skills #{RubySkills::VERSION}"
+    end
+
+    no_commands do
+      # @api private
+      # @param skills [Hash{String => Hash}] lockfile skill map
+      # @return [Hash] JSON-serializable list payload
+      def list_payload(skills)
+        {
+          "skills" => skills.map do |name, data|
+            {
+              "name" => name,
+              "version" => data["version"],
+              "source" => data["source"]
+            }
+          end
+        }
+      end
+    end
+  end
+end

data/lib/ruby_skills/config.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module RubySkills
+  # Resolves project paths and bootstraps a Ruby Skills workspace.
+  #
+  # Paths for +Skillfile+, +Skills.lock+ and the local skills directory
+  # are derived from a project root.
+  #
+  # @example Initialize the current directory
+  #   RubySkills::Config.new.initialize_project!
+  #
+  # @since 0.1.0
+  class Config
+    # Filename of the project skill manifest.
+    SKILLFILE = "Skillfile"
+
+    # Filename of the installed-skills lockfile.
+    LOCKFILE = "Skills.lock"
+
+    # Directory where installed skills are stored.
+    SKILLS_DIRECTORY = ".ruby-skills"
+
+    # @param root [String, Pathname] project root used to resolve skill paths
+    def initialize(root: Dir.pwd)
+      @root = Pathname.new(root)
+    end
+
+    # Create the skills directory and a starter Skillfile when missing.
+    #
+    # @return [void]
+    def initialize_project!
+      create_skills_directory
+      create_skillfile
+    end
+
+    # @return [Pathname] absolute path to the project Skillfile
+    def skillfile_path
+      @root.join(SKILLFILE)
+    end
+
+    # @return [Pathname] absolute path to the project lockfile
+    def lockfile_path
+      @root.join(LOCKFILE)
+    end
+
+    # @return [Pathname] absolute path to the local skills directory
+    def skills_path
+      @root.join(SKILLS_DIRECTORY)
+    end
+
+    private
+
+    # @api private
+    # @return [void]
+    def create_skills_directory
+      FileUtils.mkdir_p(skills_path)
+    end
+
+    # @api private
+    # @return [void]
+    def create_skillfile
+      return if skillfile_path.exist?
+
+      skillfile_path.write(<<~RUBY)
+        # Ruby Skills
+
+        # skill "rails-performance",
+        #   github: "username/rails-performance"
+      RUBY
+    end
+  end
+end