bundler-skills 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 439aafda99d985a5bd8da3676ad50a82f17d1e8bf01a895d193998ae1faf885d
-  data.tar.gz: 0050bcd8e99963aecc9b847bba9697e2b88b8d55ecee0f3c8d6a7340a6b0ad9c
+  metadata.gz: 962c265c0293c266b9fcca439681d9850cdac4332348dd2d1ffe11a4e5580111
+  data.tar.gz: 495a9a9f1f2a1c0da2cb02aa14b73c1902b0584e64647066a9da967615b0c4af
 SHA512:
-  metadata.gz: de83628fb2e88ab3388afd068d0c478eb901fac43df5858ca280af1012dfaa64363599a4e640874d3d8e392b4189dd7f3962420a0e44d458cb5c5893d6880409
-  data.tar.gz: 46029390766998a7ede9dc14546d6fbbff54810973196a8e8626ce653b905cbcd43dec302d63f1b21e88915c74703296d5ac22881dd9b3ac2e6930b14b3b29a0
+  metadata.gz: 4cad5c43044a98626b9fab90cb799c167e012f56d4c53c3839153648e3daef3f6c9cd10f1fa77771a2a0af8bedccbee77204054bcde6e48b2682fe9a36ca0c4c
+  data.tar.gz: 6ec0164595551b1710069fe015151462cee20b87f614ed7b8c5d87d21053e7374332fde34e670196b8b0e0a7e2d1a6491f56b8be22ba09bd2047a7341957ce33

data/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-06-27
+
+### Changed (breaking)
+
+- **bundler-skills is now a regular gem, not a Bundler plugin.** Install it as
+  `gem "bundler-skills"` (recommended: in the `development` group) instead of
+  `plugin "bundler-skills"`. This removes the `Bundler::Plugin::Index::CommandConflict`
+  that occurred (and recurred on every `bundle` run until `bundler plugin
+  uninstall`) whenever `bundle update` bumped bundler-skills itself.
+- Syncing now runs from a RubyGems `Gem.post_install` hook
+  (`lib/rubygems_plugin.rb`): when a gem is actually installed during
+  `bundle install` / `bundle update`, only **that gem's** skills are linked, and
+  only that gem's own stale links are pruned (other gems are untouched). A
+  cached `bundle install` that installs nothing does no work.
+- The manual command moved from the Bundler subcommand `bundle skills` to the
+  plain executable **`bundle exec skills`** (`sync` / `list` / `clean` / `init`,
+  with `--dry-run`). `skills sync` scans all gems and prunes all stale links.
+
+### Removed
+
+- Production / CI auto-detection (`RAILS_ENV`/`RACK_ENV=production`, `CI`) and the
+  `enabled:` config key / `BUNDLER_SKILLS_ENABLED` override. With a
+  development-group install the gem isn't present in production/CI anyway. The
+  only switch left is `BUNDLER_SKILLS_DISABLED`.
+
 ## [0.3.0] - 2026-06-21
 
 ### Changed

data/PROPOSAL.md

@@ -76,8 +76,19 @@ even for gems like `rails-html-sanitizer`.
   linked too (the directory is symlinked as a whole), so reference relative
   files normally.
 
-## Why a Bundler plugin (not RubyGems hooks)
-
-RubyGems' `post_install` hooks don't fire during `bundle install`, so a Bundler
-plugin using the `after-install-all` hook is the reliable place to do this. See
-[README.md](README.md) for the consumer-side details.
+## Why a RubyGems `post_install` hook (not a Bundler plugin)
+
+bundler-skills ships as a regular gem with a `lib/rubygems_plugin.rb` that
+registers a `Gem.post_install` hook. The hook **does** fire during
+`bundle install` for each gem that is actually installed (only `Gem.done_installing`
+is Bundler-skipped), so it is a reliable place to sync that gem's skills.
+
+An earlier version was a Bundler plugin that registered a `bundle skills`
+command via `Bundler::Plugin::API.command`. That had a fatal flaw: when
+`bundle update` bumped bundler-skills itself, Bundler re-registered the `skills`
+command while the previous registration was still in its plugin index, raising
+`Bundler::Plugin::Index::CommandConflict` — and it recurred on every subsequent
+`bundle` run until `bundler plugin uninstall`. This is unavoidable for any plugin
+that registers a command. Becoming a regular gem removes the command registration
+entirely (the manual command is now the plain executable `bundle exec skills`),
+so the conflict cannot happen. See [README.md](README.md) for consumer details.

data/README.md

@@ -1,7 +1,7 @@
 # bundler-skills
 
-A Bundler plugin that auto-symlinks **AI agent skills bundled in your gems**
-into your project after `bundle install`. The Ruby/Bundler counterpart of
+A gem that auto-symlinks **AI agent skills bundled in your gems** into your
+project on `bundle install`. The Ruby/Bundler counterpart of
 [antfu/skills-npm](https://github.com/antfu/skills-npm).
 
 Gems ship `skills/<name>/SKILL.md`; your project links them into the right agent
@@ -10,15 +10,20 @@ team gets them just by running `bundle install`.
 
 ## How it works
 
-After `bundle install` / `bundle update`, the plugin:
+bundler-skills ships a RubyGems `post_install` hook (via
+`lib/rubygems_plugin.rb`). Whenever a gem is **actually installed** during
+`bundle install` / `bundle update`, the hook runs for that gem and:
 
-1. Scans your resolved dependency gems for `skills/*/SKILL.md`.
+1. Scans **that gem** for `skills/*/SKILL.md`.
 2. Detects which agents you use (by marker directories) and symlinks each skill
    into the right place, named `gem-<gem>--<skill>`.
-3. Adds the generated symlink patterns to `.gitignore` (they are machine-local).
+3. Prunes that gem's own stale links (so a version that renames or drops a skill
+   updates correctly), leaving every other gem's links untouched.
+4. Adds the generated symlink patterns to `.gitignore` (they are machine-local).
 
-It is **disabled automatically in production/CI** — skills are a development-time
-concern.
+A `bundle install` that installs nothing (everything already cached) does no
+work — only freshly installed gems are processed. To re-sync everything at once
+(e.g. after removing a gem), run `bundle exec skills` (see below).
 
 ### Supported agents
 
@@ -36,13 +41,16 @@ marker exists, so nothing is created in projects that don't use these tools.
 
 ## Installation
 
-Add the plugin to your `Gemfile` (this is the recommended, team-wide way):
+Add the gem to your `Gemfile`, in the `development` group (skills are a
+development-time concern; this is the recommended, team-wide way):
 
 ```ruby
 # Gemfile
 source "https://rubygems.org"
 
-plugin "bundler-skills"
+group :development do
+  gem "bundler-skills"
+end
 
 gem "some-gem-that-ships-skills"
 ```
@@ -53,58 +61,53 @@ Then:
 bundle install
 ```
 
-That's it. On install you'll see something like:
+That's it. When a skill-bearing gem is installed you'll see something like:
 
 ```
-[bundler-skills] 3 skill(s) discovered, 3 linked, 0 relinked, 0 pruned across 1 dir(s) (agents: claude)
+[bundler-skills] 1 skill(s) discovered, 1 linked, 0 relinked, 0 pruned across 1 dir(s) (agents: claude)
+  created:
+    .claude/skills/gem-rubocop--style  ->  /path/to/gems/rubocop/skills/style
 ```
 
+> In production / CI you typically run `bundle install` with the `development`
+> group excluded (`bundle config set --local without development`), so the gem
+> isn't even present and nothing runs. You can also force it off anywhere with
+> `BUNDLER_SKILLS_DISABLED=1`.
+
 When a run actually changes something (links created, relinked after a gem
 update, or stale links pruned) the summary is printed in green so it stands out;
 a run with nothing to do prints the same line in plain text. A changed run also
 lists each affected skill, grouped by kind, with the path to its `SKILL.md` so
-you can review the (third-party) skill contents now linked into your project:
+you can review the (third-party) skill contents now linked into your project.
 
-```
-[bundler-skills] 3 skill(s) discovered, 2 linked, 1 relinked, 0 pruned across 1 dir(s) (agents: claude)
-  created:
-    .claude/skills/gem-rubocop--style  ->  /path/to/gems/rubocop/skills/style
-    .claude/skills/gem-rubocop--lint   ->  /path/to/gems/rubocop/skills/lint
-  relinked:
-    .claude/skills/gem-rspec--matchers  ->  /path/to/gems/rspec/skills/matchers
-```
-
-> Alternatively, install it globally with `bundle plugin install bundler-skills`.
-> The `Gemfile` approach is preferred because it propagates to the whole team.
-
-## The `bundle skills` command
+## The `bundle exec skills` command
 
-`bundle install` triggers syncing automatically, but `bundle lock` does **not**
-run plugin hooks ([rubygems#7542](https://github.com/ruby/rubygems/issues/7542)).
-Use the command to sync manually, or to inspect/clean:
+The `post_install` hook only fires for gems that are freshly installed. To
+re-sync everything at once — after removing a gem, after `bundle lock` (which
+installs nothing), or just to inspect/clean — run the command:
 
 ```sh
-bundle skills          # (or: bundle skills sync) re-create symlinks
-bundle skills list     # show discovered skills and target agents (no changes)
-bundle skills clean    # remove all gem-*--* symlinks this plugin created
-bundle skills init     # create a bundler-skills.yml config file with defaults
-bundle skills <cmd> --dry-run   # show what would change without writing
+bundle exec skills          # (or: skills sync) re-scan ALL gems and (re)create symlinks
+bundle exec skills list     # show discovered skills and target agents (no changes)
+bundle exec skills clean    # remove all gem-*--* symlinks this gem created
+bundle exec skills init     # create a bundler-skills.yml config file with defaults
+bundle exec skills <cmd> --dry-run   # show what would change without writing
 ```
 
-Unlike the automatic hook, the command always runs (it ignores the
-production/CI guard) since invoking it is an explicit action.
+Unlike the automatic hook, `skills sync` scans every resolved gem and prunes any
+stale `gem-*--*` link (so it also cleans up after a removed gem). It always runs
+and ignores `BUNDLER_SKILLS_DISABLED`, since invoking it is an explicit action.
 
 ## Configuration
 
 All optional. Create `bundler-skills.yml` in your project root:
 
 ```yaml
-enabled:                    # nil (auto) | false (off) | [development] (env list)
 agents:                     # omit = auto-detect; or list: [claude, cursor]; or "*"
   - claude
   - cursor
 gitignore: true             # manage .gitignore (default true)
-cleanup: true               # prune stale gem-*--* links when a gem is removed (default true)
+cleanup: true               # prune stale gem-*--* links (default true)
 recursive: false            # also scan skills/**/SKILL.md (default false)
 include:                    # only these gems (empty = all). fnmatch on "gem" or "gem/skill"
   - rubocop
@@ -115,24 +118,15 @@ exclude:                    # exclude these (wins over include)
 
 Notes:
 
-- Skills from `development`/`test` group gems are included by default — those are
-  exactly the gems (linters, test helpers) that ship skills. They are only
-  excluded when your environment sets `bundle config set without development`
-  (e.g. production), in which case skills aren't wanted anyway.
 - The link target is the gem's path on your machine; that's why the symlinks are
   gitignored and re-created on each machine's `bundle install`.
 
 ### Disabling
 
-The hook is off automatically when any of these hold:
-
-- `BUNDLER_SKILLS_DISABLED` is set to a truthy value
-- `RAILS_ENV` / `RACK_ENV` is `production`
-- `CI` is truthy
-- `bundler-skills.yml` has `enabled: false`, or `enabled: [..]` not listing the
-  current env
-
-Force it on with `BUNDLER_SKILLS_ENABLED=1` or `enabled: true`.
+Set `BUNDLER_SKILLS_DISABLED` to a truthy value (`1`/`true`/`yes`/`on`) to turn
+the `post_install` hook off. There is no production/CI auto-detection: with the
+recommended `development`-group install the gem isn't present in production/CI in
+the first place. The manual `bundle exec skills` command ignores this switch.
 
 ## Naming: `gem-<gem>--<skill>`
 
@@ -155,7 +149,7 @@ See [PROPOSAL.md](PROPOSAL.md) for the distribution convention. In short: put
 
 ## Trust boundary
 
-Skills bundled in third-party gems are third-party content. This plugin only
+Skills bundled in third-party gems are third-party content. This gem only
 **creates symlinks** to them — it never executes their contents. Reviewing what a
 skill instructs your agent to do is the user's responsibility, the same as
 reviewing any dependency.
@@ -165,6 +159,11 @@ reviewing any dependency.
 - POSIX symlinks are assumed; Windows is not supported yet.
 - Whether Cursor / Codex / Copilot follow symlinked `SKILL.md` during their own
   directory scans is not formally documented; verified working with Claude Code.
+- The `post_install` hook only fires for gems that are **actually installed**. A
+  cached `bundle install` (nothing to install) and `bundle lock` do no syncing —
+  run `bundle exec skills` to re-sync on demand.
+- When a gem is **removed**, no hook fires for it, so its `gem-*--*` links linger
+  until the next `bundle exec skills` (full sync prunes them).
 
 ## Development
 

data/exe/skills

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler_skills"
+require "bundler_skills/cli"
+
+exit BundlerSkills::CLI.new.run(ARGV)

data/lib/bundler_skills/cli.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module BundlerSkills
+  # `bundle exec skills [sync|list|clean|init] [--dry-run]`
+  #
+  # The manual entry point (a plain executable, not a Bundler plugin command).
+  # Unlike the post_install hook it ignores the disable switch — running it is an
+  # explicit user action — and it reuses the same Synchronizer logic.
+  class CLI
+    INIT_TEMPLATE = <<~YAML
+      # bundler-skills.yml — all keys are optional
+      #
+      # agents:                     # omit = auto-detect; or list: [claude, cursor]; or "*"
+      #   - claude
+      #   - cursor
+      # gitignore: true             # manage .gitignore (default true)
+      # cleanup: true               # prune stale gem-*--* links when a gem is removed (default true)
+      # recursive: false            # also scan skills/**/SKILL.md (default false)
+      # include:                    # only these gems (empty = all). fnmatch on "gem" or "gem/skill"
+      #   - rubocop
+      #   - "rails-*"
+      # exclude:                    # exclude these (wins over include)
+      #   - some-noisy-gem
+    YAML
+
+    USAGE = <<~HELP
+      Usage: bundle exec skills [SUBCOMMAND] [--dry-run]
+
+        sync   (default) discover skills and (re)create symlinks
+        list   show discovered skills and target agents (no changes)
+        clean  remove all gem-*--* symlinks this gem created
+        init   create a bundler-skills.yml config file with defaults
+
+      Options:
+        --dry-run   show what would change without writing
+        -h, --help  show this help
+    HELP
+
+    def initialize(logger: StdoutLogger.new)
+      @logger = logger
+    end
+
+    # @param argv [Array<String>]
+    # @return [Integer] process exit status
+    def run(argv)
+      args = argv.dup
+      opts = { dry_run: false }
+      parser = OptionParser.new do |o|
+        o.on("--dry-run") { opts[:dry_run] = true }
+        o.on("-h", "--help") { @logger.info(USAGE); return 0 }
+      end
+      parser.order!(args)
+
+      subcommand = args.shift || "sync"
+      case subcommand
+      when "sync" then run_sync(opts[:dry_run])
+      when "list" then run_list
+      when "clean" then run_clean(opts[:dry_run])
+      when "init" then run_init
+      when "help" then @logger.info(USAGE)
+      else
+        @logger.error("[bundler-skills] unknown subcommand: #{subcommand}")
+        @logger.info(USAGE)
+        return 1
+      end
+      0
+    rescue OptionParser::ParseError => e
+      @logger.error("[bundler-skills] #{e.message}")
+      @logger.info(USAGE)
+      1
+    end
+
+    private
+
+    def synchronizer(dry_run: false)
+      config = Config.load
+      config = OverrideDryRun.new(config) if dry_run
+      Synchronizer.new(config: config, logger: @logger)
+    end
+
+    def run_sync(dry_run)
+      synchronizer(dry_run: dry_run).sync
+    end
+
+    def run_list
+      result = synchronizer.plan
+      if result.discovered.empty?
+        @logger.info("[bundler-skills] no skills found in dependency gems")
+        return
+      end
+
+      agents = result.agents.map(&:key)
+      @logger.info("[bundler-skills] #{result.discovered.size} skill(s) " \
+                   "-> agents: #{agents.empty? ? '(none detected)' : agents.join(', ')}")
+      result.discovered.sort_by(&:link_name).each do |skill|
+        @logger.info("  #{skill.link_name}  ->  #{skill.source_path}")
+      end
+    end
+
+    def run_init
+      path = File.join(Bundler.root.to_s, Config::CONFIG_FILENAME)
+      if File.exist?(path)
+        @logger.warn("[bundler-skills] #{Config::CONFIG_FILENAME} already exists")
+        return
+      end
+
+      File.write(path, INIT_TEMPLATE)
+      @logger.info("[bundler-skills] created #{Config::CONFIG_FILENAME}")
+    end
+
+    def run_clean(dry_run)
+      removed = synchronizer(dry_run: dry_run).clean
+      total = removed.values.sum(&:size)
+      verb = dry_run ? "would remove" : "removed"
+      @logger.info("[bundler-skills] #{verb} #{total} link(s)")
+      removed.each do |subdir, names|
+        names.each { |n| @logger.info("  #{subdir}/#{n}") }
+      end
+    end
+
+    # Minimal logger matching the subset of Bundler.ui that Synchronizer/Linker
+    # use (info/warn/error/confirm), writing to stdout/stderr.
+    class StdoutLogger
+      def info(message)    = $stdout.puts(message)
+      def confirm(message) = $stdout.puts(message)
+      def warn(message)    = $stderr.puts(message)
+      def error(message)   = $stderr.puts(message)
+    end
+
+    # Wraps a Config to force dry_run? true without mutating the original.
+    class OverrideDryRun
+      def initialize(config)
+        @config = config
+      end
+
+      def dry_run?
+        true
+      end
+
+      def respond_to_missing?(name, include_private = false)
+        @config.respond_to?(name, include_private) || super
+      end
+
+      def method_missing(name, *args, &block)
+        @config.send(name, *args, &block)
+      end
+    end
+  end
+end

data/lib/bundler_skills/config.rb

@@ -5,7 +5,6 @@ module BundlerSkills
   #
   # The file is optional: a missing file yields an all-defaults Config so the
   # hook works out of the box. Supported keys:
-  #   enabled    nil(auto) | true | false | [env names]
   #   agents     nil(auto-detect) | "*" | [keys] | "key"
   #   gitignore  bool (default true)
   #   cleanup    bool (default true) — prune stale gem-*--* links
@@ -17,7 +16,6 @@ module BundlerSkills
     CONFIG_FILENAME = "bundler-skills.yml"
 
     DEFAULTS = {
-      "enabled" => nil,
       "agents" => nil,
       "gitignore" => true,
       "cleanup" => true,
@@ -49,13 +47,6 @@ module BundlerSkills
       @data = data
     end
 
-    # nil | true | false | Array<String>. A bare string env name is normalized
-    # to a one-element array so `enabled: development` behaves like a list.
-    def enabled
-      value = @data["enabled"]
-      value.is_a?(String) ? [value] : value
-    end
-
     # nil (auto-detect) | Array<String>. A bare string key is wrapped so
     # `agents: claude` works as well as a YAML list.
     def agents

data/lib/bundler_skills/disabling.rb

@@ -1,36 +1,22 @@
 # frozen_string_literal: true
 
 module BundlerSkills
-  # Decides whether the plugin should run in the current environment.
+  # Decides whether the post_install hook should run.
   #
-  # Skills are a development-time concern, so the hook is silently disabled in
-  # production / CI. All inputs are injected (env hash + config) so the logic is
-  # a pure function and easy to test. The manual `bundle skills` command does
-  # NOT consult this — an explicit user action always runs.
+  # The hook only fires when a gem is actually installed, and in the
+  # recommended development-group setup the gem isn't even present in
+  # production / CI — so there is no environment auto-detection here. The single
+  # escape hatch is the BUNDLER_SKILLS_DISABLED env var. The manual CLI ignores
+  # this entirely (running it is an explicit user action).
   module Disabling
     TRUTHY = %w[1 true yes on].freeze
 
     module_function
 
     # @param env [Hash] environment variables (defaults to ENV)
-    # @param config [BundlerSkills::Config, nil] loaded config (optional)
-    # @return [Boolean] true when the plugin must not run
-    def disabled?(env: ENV, config: nil)
-      # Explicit overrides win over everything else.
-      return true if truthy?(env["BUNDLER_SKILLS_DISABLED"])
-      return false if truthy?(env["BUNDLER_SKILLS_ENABLED"])
-
-      enabled = config&.enabled
-      case enabled
-      when false
-        return true
-      when Array
-        return true unless enabled.map(&:to_s).include?(current_environment(env))
-      when true
-        return false
-      end
-
-      production?(env) || ci?(env)
+    # @return [Boolean] true when the hook must not run
+    def disabled?(env: ENV)
+      truthy?(env["BUNDLER_SKILLS_DISABLED"])
     end
 
     def truthy?(value)
@@ -38,19 +24,5 @@ module BundlerSkills
 
       TRUTHY.include?(value.to_s.strip.downcase)
     end
-
-    def production?(env)
-      %w[RAILS_ENV RACK_ENV].any? { |key| env[key].to_s.strip.downcase == "production" }
-    end
-
-    def ci?(env)
-      truthy?(env["CI"])
-    end
-
-    # Best-effort current environment name for `enabled:` list matching.
-    def current_environment(env)
-      value = env["RAILS_ENV"] || env["RACK_ENV"]
-      value.to_s.strip.empty? ? "development" : value.strip.downcase
-    end
   end
 end

data/lib/bundler_skills/linker.rb

@@ -36,14 +36,20 @@ module BundlerSkills
     end
 
     # @param skills [Array<DiscoveredSkill>]
+    # @param prune_scope [Symbol, Array<String>, nil] which stale links to prune:
+    #   :all (default)         -> every gem-*--* link we own (full sync)
+    #   [prefix, ...]          -> only links whose basename starts with one of the
+    #                             given prefixes, e.g. "gem-<name>--" (single-gem sync)
+    #   nil                    -> prune nothing
+    #   Pruning still honors @config.cleanup? — when cleanup is off nothing is pruned.
     # @return [Result]
-    def link(skills)
+    def link(skills, prune_scope: :all)
       result = Result.new
       link_names = skills.map(&:link_name)
 
       ensure_dir
       skills.each { |skill| link_one(skill, result) }
-      prune_stale(link_names, result) if @config.cleanup?
+      prune_stale(link_names, result, prune_scope) if @config.cleanup? && prune_scope
       result
     end
 
@@ -97,10 +103,13 @@ module BundlerSkills
 
     # Remove gem-*--* symlinks we own that are no longer in the discovery set.
     # Real directories, other prefixes, and unmanaged symlinks are left alone.
-    def prune_stale(valid_link_names, result)
+    # When +scope+ is an array of prefixes, only links whose basename starts with
+    # one of them are considered (so a single-gem sync never touches other gems).
+    def prune_stale(valid_link_names, result, scope = :all)
       Dir.glob(File.join(@skills_dir, STALE_GLOB)).each do |path|
         name = File.basename(path)
         next if valid_link_names.include?(name)
+        next unless in_scope?(name, scope)
         next unless File.symlink?(path) # only prune our own symlinks
 
         remove(path)
@@ -108,6 +117,12 @@ module BundlerSkills
       end
     end
 
+    def in_scope?(name, scope)
+      return true if scope == :all
+
+      Array(scope).any? { |prefix| name.start_with?(prefix) }
+    end
+
     def replace_symlink(link_path, target)
       remove(link_path)
       create_symlink(link_path, target)

data/lib/bundler_skills/rubygems_hook.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module BundlerSkills
+  # Entry point for the RubyGems `Gem.post_install` hook (registered in
+  # lib/rubygems_plugin.rb). Fires once per gem actually installed during a
+  # `bundle install` / `bundle update`, and syncs THAT gem's skills only.
+  #
+  # Like the old Bundler hook, it holds no real logic: it guards on context and
+  # the disable switch, then delegates to Synchronizer#sync_gem. Any error is
+  # swallowed as a warning so it never aborts the user's install.
+  module RubygemsHook
+    module_function
+
+    # @param installer [#spec] a Gem::Installer (or anything exposing #spec)
+    def install(installer)
+      spec = installer.spec
+      return unless bundle_context?
+      return if Disabling.disabled?
+
+      Synchronizer.new(config: Config.load).sync_gem(spec)
+    rescue StandardError => e
+      warn("[bundler-skills] skipped #{safe_name(installer)}: #{e.class}: #{e.message}")
+    end
+
+    # Only act inside a `bundle install` for a project with a Gemfile. This
+    # keeps a plain `gem install foo` (no project context) from creating
+    # symlinks in whatever directory the user happens to be in.
+    def bundle_context?
+      return false unless defined?(Bundler)
+
+      root = Bundler.root
+      root.join("Gemfile").file? || root.join("gems.rb").file?
+    rescue StandardError
+      false
+    end
+
+    def safe_name(installer)
+      installer.spec.name
+    rescue StandardError
+      "(unknown gem)"
+    end
+
+    def warn(message)
+      if defined?(Bundler)
+        Bundler.ui.warn(message)
+      else
+        Kernel.warn(message)
+      end
+    end
+  end
+end

data/lib/bundler_skills/synchronizer.rb

@@ -25,7 +25,37 @@ module BundlerSkills
 
       links_by_dir = subdirs.to_h do |subdir|
         skills_dir = File.join(@root.to_s, subdir)
-        [subdir, Linker.new(skills_dir: skills_dir, config: @config, logger: @logger).link(skills)]
+        linker = Linker.new(skills_dir: skills_dir, config: @config, logger: @logger)
+        [subdir, linker.link(skills, prune_scope: :all)]
+      end
+
+      gitignore_changed = update_gitignore(subdirs)
+
+      log_summary(skills, agents, links_by_dir)
+      Result.new(
+        discovered: skills, agents: agents,
+        links_by_dir: links_by_dir, gitignore_changed: gitignore_changed
+      )
+    end
+
+    # Sync the skills of a SINGLE gem (used by the RubyGems post_install hook).
+    #
+    # Only links belonging to this gem (gem-<name>--*) are added/updated, and
+    # only this gem's stale links are pruned — every other gem's links are left
+    # untouched. So when a gem's new version drops or renames a skill, its old
+    # link is removed, but unrelated gems are never disturbed.
+    #
+    # @param spec [#name, #full_gem_path] a Gem::Specification (or compatible)
+    def sync_gem(spec)
+      skills = Discoverer.new(specs: [spec], config: @config, logger: @logger).discover
+      agents = AgentRegistry.resolve(@root, @config)
+      subdirs = AgentRegistry.output_subdirs(agents)
+      scope = ["#{DiscoveredSkill::LINK_PREFIX}#{spec.name}#{DiscoveredSkill::BOUNDARY}"]
+
+      links_by_dir = subdirs.to_h do |subdir|
+        skills_dir = File.join(@root.to_s, subdir)
+        linker = Linker.new(skills_dir: skills_dir, config: @config, logger: @logger)
+        [subdir, linker.link(skills, prune_scope: scope)]
       end
 
       gitignore_changed = update_gitignore(subdirs)

data/lib/bundler_skills/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module BundlerSkills
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

data/lib/bundler_skills.rb

@@ -9,7 +9,6 @@ require_relative "bundler_skills/agent_registry"
 require_relative "bundler_skills/linker"
 require_relative "bundler_skills/gitignore_updater"
 require_relative "bundler_skills/synchronizer"
-require_relative "bundler_skills/hook"
 
 module BundlerSkills
 end

data/lib/rubygems_plugin.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+# RubyGems loads this file automatically (it is on the require path and named
+# by the rubygems_plugin convention) during `bundle install` / `gem install`.
+# We register a post_install hook that syncs each freshly installed gem's
+# skills. This replaces the old Bundler plugin (`command "skills"` caused a
+# CommandConflict whenever the plugin updated itself).
+require_relative "bundler_skills"
+require_relative "bundler_skills/rubygems_hook"
+
+Gem.post_install do |installer|
+  BundlerSkills::RubygemsHook.install(installer)
+end

metadata

@@ -1,20 +1,22 @@
 --- !ruby/object:Gem::Specification
 name: bundler-skills
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - aki77
-bindir: bin
+bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
-description: A Bundler plugin that discovers skills/ directories bundled in your dependency
-  gems and symlinks them into your project's agent skill directories (.claude/skills,
-  .agents/skills) on bundle install. The Ruby/Bundler counterpart of antfu/skills-npm.
+description: A gem that discovers skills/ directories bundled in your dependency gems
+  and symlinks them into your project's agent skill directories (.claude/skills, .agents/skills)
+  on bundle install, via a RubyGems post_install hook. The Ruby/Bundler counterpart
+  of antfu/skills-npm.
 email:
 - aki77@users.noreply.github.com
-executables: []
+executables:
+- skills
 extensions: []
 extra_rdoc_files: []
 files:
@@ -22,19 +24,20 @@ files:
 - LICENSE.txt
 - PROPOSAL.md
 - README.md
+- exe/skills
 - lib/bundler_skills.rb
 - lib/bundler_skills/agent_registry.rb
-- lib/bundler_skills/command.rb
+- lib/bundler_skills/cli.rb
 - lib/bundler_skills/config.rb
 - lib/bundler_skills/disabling.rb
 - lib/bundler_skills/discovered_skill.rb
 - lib/bundler_skills/discoverer.rb
 - lib/bundler_skills/gitignore_updater.rb
-- lib/bundler_skills/hook.rb
 - lib/bundler_skills/linker.rb
+- lib/bundler_skills/rubygems_hook.rb
 - lib/bundler_skills/synchronizer.rb
 - lib/bundler_skills/version.rb
-- plugins.rb
+- lib/rubygems_plugin.rb
 homepage: https://github.com/aki77/bundler-skills
 licenses:
 - MIT

data/lib/bundler_skills/command.rb

@@ -1,126 +0,0 @@
-# frozen_string_literal: true
-
-module BundlerSkills
-  # `bundle skills [sync|list|clean] [--dry-run]`
-  #
-  # The manual entry point. Unlike the hook, it ignores the production/CI
-  # disabling guard — running it is an explicit user action. It reuses the
-  # same Synchronizer logic the hook uses.
-  class Command < Bundler::Plugin::API
-    command "skills"
-
-    INIT_TEMPLATE = <<~YAML
-      # bundler-skills.yml — all keys are optional
-      #
-      # enabled:                    # nil (auto) | false (off) | [development] (env list)
-      # agents:                     # omit = auto-detect; or list: [claude, cursor]; or "*"
-      #   - claude
-      #   - cursor
-      # gitignore: true             # manage .gitignore (default true)
-      # cleanup: true               # prune stale gem-*--* links when a gem is removed (default true)
-      # recursive: false            # also scan skills/**/SKILL.md (default false)
-      # include:                    # only these gems (empty = all). fnmatch on "gem" or "gem/skill"
-      #   - rubocop
-      #   - "rails-*"
-      # exclude:                    # exclude these (wins over include)
-      #   - some-noisy-gem
-    YAML
-
-    def exec(_command_name, args)
-      dry_run = !!args.delete("--dry-run")
-      subcommand = args.shift || "sync"
-
-      case subcommand
-      when "sync" then run_sync(dry_run)
-      when "list" then run_list
-      when "clean" then run_clean(dry_run)
-      when "init" then run_init
-      when "help", "-h", "--help" then print_help
-      else
-        Bundler.ui.error("[bundler-skills] unknown subcommand: #{subcommand}")
-        print_help
-      end
-    end
-
-    private
-
-    def synchronizer(dry_run: false)
-      config = Config.load
-      config = OverrideDryRun.new(config) if dry_run
-      Synchronizer.new(config: config)
-    end
-
-    def run_sync(dry_run)
-      synchronizer(dry_run: dry_run).sync
-    end
-
-    def run_list
-      result = synchronizer.plan
-      if result.discovered.empty?
-        Bundler.ui.info("[bundler-skills] no skills found in dependency gems")
-        return
-      end
-
-      agents = result.agents.map(&:key)
-      Bundler.ui.info("[bundler-skills] #{result.discovered.size} skill(s) " \
-                      "-> agents: #{agents.empty? ? '(none detected)' : agents.join(', ')}")
-      result.discovered.sort_by(&:link_name).each do |skill|
-        Bundler.ui.info("  #{skill.link_name}  ->  #{skill.source_path}")
-      end
-    end
-
-    def run_init
-      path = Bundler.root / Config::CONFIG_FILENAME
-      if File.exist?(path)
-        Bundler.ui.warn("[bundler-skills] #{Config::CONFIG_FILENAME} already exists")
-        return
-      end
-
-      File.write(path, INIT_TEMPLATE)
-      Bundler.ui.info("[bundler-skills] created #{Config::CONFIG_FILENAME}")
-    end
-
-    def run_clean(dry_run)
-      removed = synchronizer(dry_run: dry_run).clean
-      total = removed.values.sum(&:size)
-      verb = dry_run ? "would remove" : "removed"
-      Bundler.ui.info("[bundler-skills] #{verb} #{total} link(s)")
-      removed.each do |subdir, names|
-        names.each { |n| Bundler.ui.info("  #{subdir}/#{n}") }
-      end
-    end
-
-    def print_help
-      Bundler.ui.info(<<~HELP)
-        Usage: bundle skills [SUBCOMMAND] [--dry-run]
-
-          sync   (default) discover skills and (re)create symlinks
-          list   show discovered skills and target agents (no changes)
-          clean  remove all gem-*--* symlinks this plugin created
-          init   create a bundler-skills.yml config file with defaults
-
-        Options:
-          --dry-run   show what would change without writing
-      HELP
-    end
-
-    # Wraps a Config to force dry_run? true without mutating the original.
-    class OverrideDryRun
-      def initialize(config)
-        @config = config
-      end
-
-      def dry_run?
-        true
-      end
-
-      def respond_to_missing?(name, include_private = false)
-        @config.respond_to?(name, include_private) || super
-      end
-
-      def method_missing(name, *args, &block)
-        @config.send(name, *args, &block)
-      end
-    end
-  end
-end

data/lib/bundler_skills/hook.rb

@@ -1,31 +0,0 @@
-# frozen_string_literal: true
-
-module BundlerSkills
-  # Registers the after-install-all hook.
-  #
-  # The hook itself holds no logic: it guards on Disabling (skip in
-  # production/CI), then delegates to Synchronizer. Any error is logged as a
-  # warning so it never aborts the user's `bundle install`.
-  #
-  # NOTE: the block argument of after-install-all is an Array<Bundler::Dependency>,
-  # NOT specs. We intentionally ignore it and read Bundler.load.specs inside
-  # the Synchronizer instead.
-  module Hook
-    module_function
-
-    def register
-      Bundler::Plugin.add_hook("after-install-all") do |_dependencies|
-        call
-      end
-    end
-
-    def call
-      config = Config.load
-      return if Disabling.disabled?(config: config)
-
-      Synchronizer.new(config: config).sync
-    rescue StandardError => e
-      Bundler.ui.warn("[bundler-skills] skipped: #{e.class}: #{e.message}")
-    end
-  end
-end

data/plugins.rb

@@ -1,6 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "lib/bundler_skills"
-require_relative "lib/bundler_skills/command"
-
-BundlerSkills::Hook.register