bundler-skills 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 04635fb1c4304775edc63ef734b4c3855f066f964474b117a3c4f254954f11bb
-  data.tar.gz: 1ff141f83d7eb3014c371edbb7525c0398c275034b4adcecc23a8ac7eeb1b1ae
+  metadata.gz: 30d4136893f0cc4bdead5248b1ee7d4df3768b536d67bf3cd243c1e91da454a2
+  data.tar.gz: 6e4739d9bc290347d3af00377e3bfee89ea6e293560b23019ee855feb781907c
 SHA512:
-  metadata.gz: 9615d8701afde7424fb3ebec7731ce64207e6ab41b6d47133c8de4e42d28196b8db6110f24ed3536dcca9d0889799946d99e3a7200e6fe2090ea7ed7e088cfc9
-  data.tar.gz: 49852c8f2db3a7d8ea1aae1fc78c494f58b605f480ffb06b03a767cb81404597a8e7dc7af0901b872303df365413f1925d1182100b12cb480f2ec4cc9434e6b1
+  metadata.gz: 70fe208a60b6b8f1168a4b8d554ed82ae659c87a3b38763d80c81b54e94f7821b45a640339ad421f84f2c17266cc673d4a769b3e29516f10c2308c0182f1102c
+  data.tar.gz: c16486c4b5ffd489a68f74ab7d2c4111c03790845bc08302ce925e58887fc3aa9d732250b1fd9146a521aedce4e2c99018ec6f6c867c8646713ff54d7d995a85

data/CHANGELOG.md

@@ -1,6 +1,22 @@
 # Changelog
 
-## [Unreleased]
+## [0.6.0] - 2026-07-03
+
+### Changed (breaking)
+
+- **Removed the RubyGems `post_install` hook entirely.** bundler-skills no
+  longer hooks into `bundle install`; skills are synced only when you run the
+  command (`bundle exec skills`). This removes the global side effect where the
+  hook was loaded and evaluated for every `bundle install` of every project
+  sharing the Ruby. Wire the command into a git hook (post-merge / post-checkout)
+  or a hook manager (husky / lefthook / overcommit) to run it automatically —
+  see the README.
+
+### Removed
+
+- `lib/rubygems_plugin.rb`, the `RubygemsHook` module, and the `Disabling`
+  module — including the `BUNDLER_SKILLS_DISABLED` environment variable (with no
+  hook there is nothing to disable).
 
 ## [0.5.0] - 2026-06-27
 

data/PROPOSAL.md

@@ -76,19 +76,27 @@ even for gems like `rails-html-sanitizer`.
   linked too (the directory is symlinked as a whole), so reference relative
   files normally.
 
-## 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.
+## Why an explicit command (not a Bundler plugin or a `post_install` hook)
+
+bundler-skills is a regular gem that ships a plain executable (`bundle exec
+skills`). Syncing happens only when you run that command — it hooks into nothing.
+
+Two earlier designs were tried and rejected:
+
+- **A Bundler plugin** that registered a `bundle skills` command via
+  `Bundler::Plugin::API.command`. 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.
+- **A RubyGems `post_install` hook** (`lib/rubygems_plugin.rb` +
+  `Gem.post_install`). RubyGems auto-loads any `rubygems_plugin.rb` on the load
+  path, so once bundler-skills is installed anywhere in a Ruby, its hook is
+  loaded and evaluated for **every** `bundle install` of **every** project
+  sharing that Ruby — a global side effect that is hard to scope cleanly.
+
+Providing only a command removes both problems: there is no command
+registration to conflict, and nothing runs unless the user invokes it. Wire it
+into a git hook or a hook manager to run it automatically — see
+[README.md](README.md) for consumer details.

data/README.md

@@ -1,29 +1,28 @@
 # bundler-skills
 
-A gem that auto-symlinks **AI agent skills bundled in your gems** into your
-project on `bundle install`. The Ruby/Bundler counterpart of
+A gem that symlinks **AI agent skills bundled in your gems** into your project.
+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
-directory so the skill version always matches the gem version, and your whole
-team gets them just by running `bundle install`.
+Gems ship `skills/<name>/SKILL.md`; running `bundle exec skills` links them into
+the right agent directory so the skill version always matches the gem version.
 
 ## How it works
 
-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:
+bundler-skills is a regular gem that ships a `bundle exec skills` command.
+**Nothing runs automatically** — there is no `bundle install` hook. Sync happens
+only when you run the command (manually, or from a git hook you set up). Each run:
 
-1. Scans **that gem** for `skills/*/SKILL.md`.
+1. Scans **all dependency gems** 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. 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.
+3. Prunes stale `gem-*--*` links (so a gem that renames, drops, or is removed
+   updates correctly).
 4. Adds the generated symlink patterns to `.gitignore` (they are machine-local).
 
-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).
+Run it whenever your dependencies change — right after `bundle install` /
+`bundle update` — either by hand or from a git hook (see
+[Running automatically](#running-automatically-git-hooks--hook-managers)).
 
 ### Supported agents
 
@@ -36,8 +35,8 @@ work — only freshly installed gems are processed. To re-sync everything at onc
 
 `.agents/skills/` is the cross-tool standard shared by Cursor / Codex / Copilot;
 Claude Code needs its own `.claude/skills/` because it does not read
-`.agents/skills/` yet. The plugin links into a directory only when that agent's
-marker exists, so nothing is created in projects that don't use these tools.
+`.agents/skills/` yet. It links into a directory only when that agent's marker
+exists, so nothing is created in projects that don't use these tools.
 
 ## Installation
 
@@ -55,13 +54,14 @@ end
 gem "some-gem-that-ships-skills"
 ```
 
-Then:
+Then install and run the command:
 
 ```sh
 bundle install
+bundle exec skills
 ```
 
-That's it. When a skill-bearing gem is installed you'll see something like:
+When a skill-bearing gem is present you'll see something like:
 
 ```
 [bundler-skills] 1 skill(s) discovered, 1 linked, 0 relinked, 0 pruned across 1 dir(s) (agents: claude)
@@ -70,9 +70,8 @@ That's it. When a skill-bearing gem is installed you'll see something like:
 ```
 
 > 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`.
+> group excluded (`bundle config set --local without development`), and you
+> simply don't run `bundle exec skills` there — nothing happens unless you invoke it.
 
 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;
@@ -80,23 +79,68 @@ 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.
 
+## Running automatically (git hooks / hook managers)
+
+Sync is manual by design, but you'll usually want it to run right after your
+dependencies change (`bundle install` / `bundle update`, i.e. whenever
+`Gemfile.lock` changes). Wire the one-liner into a git hook or hook manager:
+
+Plain git hook — create `.git/hooks/post-merge` (also useful as `post-checkout`
+/ `post-rewrite`) and `chmod +x` it. Note `.git/hooks` is not committed, so this
+is per-clone:
+
+```sh
+#!/bin/sh
+bundle exec skills
+```
+
+[lefthook](https://github.com/evilmartians/lefthook) — committed, shared with
+the team:
+
+```yaml
+# lefthook.yml
+post-merge:
+  commands:
+    skills: { run: bundle exec skills }
+post-checkout:
+  commands:
+    skills: { run: bundle exec skills }
+```
+
+[husky](https://typicode.github.io/husky/) — for JS-mixed projects, create
+`.husky/post-merge`:
+
+```sh
+#!/usr/bin/env sh
+bundle exec skills
+```
+
+[overcommit](https://github.com/sds/overcommit) — for Ruby projects:
+
+```yaml
+# .overcommit.yml
+PostCheckout:
+  BundlerSkills:
+    enabled: true
+    command: ['bundle', 'exec', 'skills']
+```
+
 ## The `bundle exec skills` command
 
-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:
+Sync happens only when you run this command. Run it after your dependencies
+change, or just to inspect / clean up:
 
 ```sh
-bundle exec skills          # (or: skills sync) re-scan ALL gems and (re)create symlinks
+bundle exec skills          # (sync) re-scan ALL gems and (re)create symlinks — the default
+bundle exec skills sync     # explicit form of the default
 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, `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.
+`sync` scans every resolved gem and prunes any stale `gem-*--*` link, so it also
+cleans up after a removed gem.
 
 ## Configuration
 
@@ -119,14 +163,8 @@ exclude:                    # exclude these (wins over include)
 Notes:
 
 - 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
-
-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.
+  gitignored and re-created on each machine (run `bundle exec skills` after
+  `bundle install`).
 
 ## Naming: `gem-<gem>--<skill>`
 
@@ -159,11 +197,10 @@ 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).
+- Syncing is not automatic. Run `bundle exec skills` after your dependencies
+  change (manually, or from a git hook — see above).
+- Removing a gem leaves its `gem-*--*` links until the next `bundle exec skills`,
+  which prunes them.
 
 ## Development
 

data/lib/bundler_skills/cli.rb

@@ -5,9 +5,8 @@ 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.
+  # The entry point (a plain executable, not a Bundler plugin command). Syncing
+  # happens only when this command is run — there is no automatic hook.
   class CLI
     INIT_TEMPLATE = <<~YAML
       # bundler-skills.yml — all keys are optional

data/lib/bundler_skills/config.rb

@@ -3,8 +3,8 @@
 module BundlerSkills
   # Loads bundler-skills.yml and merges it with defaults.
   #
-  # The file is optional: a missing file yields an all-defaults Config so the
-  # hook works out of the box. Supported keys:
+  # The file is optional: a missing file yields an all-defaults Config.
+  # Supported keys:
   #   agents     nil(auto-detect) | "*" | [keys] | "key"
   #   gitignore  bool (default true)
   #   cleanup    bool (default true) — prune stale gem-*--* links

data/lib/bundler_skills/synchronizer.rb

@@ -1,13 +1,12 @@
 # frozen_string_literal: true
 
 module BundlerSkills
-  # Orchestrates discovery -> linking across the resolved agents. Shared entry
-  # point for both the Hook (after-install-all) and the manual `bundle skills`
-  # command.
+  # Orchestrates discovery -> linking across the resolved agents. The entry
+  # point for the `bundle exec skills` command.
   #
   # Discovery runs once (agent-independent); linking runs once per distinct
-  # output directory (.claude/skills and/or .agents/skills). Phase 4 adds the
-  # .gitignore update.
+  # output directory (.claude/skills and/or .agents/skills), then the .gitignore
+  # is updated.
   class Synchronizer
     Result = Struct.new(:discovered, :agents, :links_by_dir, :gitignore_changed, keyword_init: true)
 
@@ -38,37 +37,8 @@ module BundlerSkills
       )
     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)
-
-      log_summary(skills, agents, links_by_dir)
-      Result.new(
-        discovered: skills, agents: agents,
-        links_by_dir: links_by_dir, gitignore_changed: gitignore_changed
-      )
-    end
-
     # Discover skills and the agents/dirs that would receive them, without
-    # touching the filesystem. Used by `bundle skills list`.
+    # touching the filesystem. Used by `bundle exec skills list`.
     def plan
       skills = Discoverer.new(specs: @specs, config: @config, logger: @logger).discover
       agents = AgentRegistry.resolve(@root, @config)
@@ -79,7 +49,7 @@ module BundlerSkills
     end
 
     # Remove every gem-*--* symlink we own across all known output dirs.
-    # Used by `bundle skills clean`. Returns { subdir => [removed names] }.
+    # Used by `bundle exec skills clean`. Returns { subdir => [removed names] }.
     def clean
       AgentRegistry.all.map(&:skills_subdir).uniq.to_h do |subdir|
         skills_dir = File.join(@root.to_s, subdir)
@@ -104,9 +74,9 @@ module BundlerSkills
     def log_summary(skills, agents, links_by_dir)
       return unless @logger
 
-      # Nothing discovered and nothing changed -> stay silent. The post_install
-      # hook fires for EVERY installed gem, most of which ship no skills;
-      # emitting a "0 skill(s) discovered, 0 linked ..." line for each is noise.
+      # Nothing discovered and nothing changed -> stay silent. Most dependency
+      # gems ship no skills, so emitting a "0 skill(s) discovered, 0 linked ..."
+      # line when there is nothing to report is just noise.
       changed = links_by_dir.values.any?(&:changed?)
       return if skills.empty? && !changed
 

data/lib/bundler_skills/version.rb

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

data/lib/bundler_skills.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require_relative "bundler_skills/version"
-require_relative "bundler_skills/disabling"
 require_relative "bundler_skills/config"
 require_relative "bundler_skills/discovered_skill"
 require_relative "bundler_skills/discoverer"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bundler-skills
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - aki77
@@ -11,8 +11,7 @@ date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
 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.
+  via the `bundle exec skills` command. The Ruby/Bundler counterpart of antfu/skills-npm.
 email:
 - aki77@users.noreply.github.com
 executables:
@@ -29,15 +28,12 @@ files:
 - lib/bundler_skills/agent_registry.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/linker.rb
-- lib/bundler_skills/rubygems_hook.rb
 - lib/bundler_skills/synchronizer.rb
 - lib/bundler_skills/version.rb
-- lib/rubygems_plugin.rb
 homepage: https://github.com/aki77/bundler-skills
 licenses:
 - MIT
@@ -60,7 +56,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.10
+rubygems_version: 4.0.15
 specification_version: 4
-summary: Auto-symlink AI agent skills bundled in your gems after bundle install.
+summary: Symlink AI agent skills bundled in your gems via the bundle exec skills command.
 test_files: []

data/lib/bundler_skills/disabling.rb

@@ -1,28 +0,0 @@
-# frozen_string_literal: true
-
-module BundlerSkills
-  # Decides whether the post_install hook should run.
-  #
-  # 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)
-    # @return [Boolean] true when the hook must not run
-    def disabled?(env: ENV)
-      truthy?(env["BUNDLER_SKILLS_DISABLED"])
-    end
-
-    def truthy?(value)
-      return false if value.nil?
-
-      TRUTHY.include?(value.to_s.strip.downcase)
-    end
-  end
-end

data/lib/bundler_skills/rubygems_hook.rb

@@ -1,51 +0,0 @@
-# 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/rubygems_plugin.rb

@@ -1,13 +0,0 @@
-# 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