bundler-skills 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: efdb922b385805d47a3b9d255b160810300f0b6e98157213f6a4587d1d2475dc
+  data.tar.gz: da6868ab55f898967fe52c7699512898c4a4df2e5ccb7e278cd5882b6c0219f1
+SHA512:
+  metadata.gz: f931afeb29f6d9e263b6f9d39ddbbd0ae157fed3bdc9aa45ccacefd6c64d4e0ca3d14732619f91d964dd81c4e5f88c7367bb26a5ebe11da93b82ae91274843d1
+  data.tar.gz: cacd1cf9954366a41d0edfeecb13fee38ba865ad4ac8c7b9ae45eb966e44ca8982f5a8e8e1e443c18395475a44ca06b1c1899466b5e5ee7c5aa0c2ee6fff5262

data/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+## [Unreleased]
+
+## [0.1.0] - 2026-06-18
+
+### Added
+
+- Initial release of `bundler-skills`.
+- `after-install-all` hook that discovers `skills/*/SKILL.md` in dependency gems
+  and symlinks them into agent skill directories after `bundle install`.
+- Multi-agent support: Claude Code (`.claude/skills`), Cursor / Codex / GitHub
+  Copilot (`.agents/skills`), detected by marker directories.
+- `gem-<gem>--<skill>` double-hyphen link naming (unambiguous for hyphenated gem
+  names).
+- Idempotent linking, stale prune, and `.gitignore` management.
+- Automatic disabling in production / CI (`RAILS_ENV`/`RACK_ENV=production`,
+  `CI`, `BUNDLER_SKILLS_DISABLED`); override with `BUNDLER_SKILLS_ENABLED`.
+- `bundle skills` command (`sync` / `list` / `clean`, with `--dry-run`).
+- `bundler-skills.yml` configuration (`enabled`, `agents`, `gitignore`,
+  `cleanup`, `recursive`, `include`, `exclude`).

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 aki77
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/PROPOSAL.md

@@ -0,0 +1,83 @@
+# Distributing Agent Skills in gems
+
+This document describes how a gem author ships **AI agent skills** so that
+[bundler-skills](README.md) (and, by convention, any compatible tool) can
+discover and link them.
+
+## Convention
+
+Put a `skills/` directory at the root of your gem. Each immediate subdirectory
+is one skill and must contain a `SKILL.md` following the
+[Agent Skills](https://code.claude.com/docs/en/skills) format (YAML frontmatter
+with at least `name` and `description`, then Markdown body):
+
+```
+my-gem/
+├── my-gem.gemspec
+├── lib/
+│   └── my_gem.rb
+└── skills/
+    └── my-gem-helper/
+        └── SKILL.md
+```
+
+```markdown
+---
+name: my-gem-helper
+description: How to use my-gem's DSL correctly, with common patterns.
+---
+
+# my-gem helper
+
+... instructions for the agent ...
+```
+
+## Package the skills
+
+The `skills/` directory must be part of the published gem, so include it in the
+gemspec `files`:
+
+```ruby
+# my-gem.gemspec
+Gem::Specification.new do |spec|
+  # ...
+  spec.files += Dir["skills/**/*"]
+end
+```
+
+If your gemspec builds `files` from `git ls-files`, committed skill files are
+included automatically — just make sure they aren't gitignored.
+
+## What consumers get
+
+When a project depends on your gem and uses bundler-skills, each skill is
+symlinked into the project's agent directory as:
+
+```
+gem-<your-gem-name>--<skill-name>
+```
+
+For example `skills/my-gem-helper/SKILL.md` in `my-gem` becomes
+`.claude/skills/gem-my-gem--my-gem-helper` (and/or `.agents/skills/...`).
+
+The double-hyphen `--` separates the gem name from the skill name. Because
+RubyGems names cannot contain consecutive hyphens, the boundary is unambiguous
+even for gems like `rails-html-sanitizer`.
+
+## Guidelines
+
+- **One concern per skill.** Keep each `skills/<name>/` focused; the `name` and
+  `description` frontmatter is what an agent uses to decide relevance.
+- **Skill name = directory name.** The subdirectory name becomes the skill name
+  in the symlink, so keep it stable and descriptive.
+- **Version together.** The whole point is that skills ship and update with the
+  exact version of your gem — treat `SKILL.md` as part of your public surface.
+- **Assets / scripts.** Anything alongside `SKILL.md` in the skill directory is
+  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.

data/README.md

@@ -0,0 +1,165 @@
+# 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
+[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`.
+
+## How it works
+
+After `bundle install` / `bundle update`, the plugin:
+
+1. Scans your resolved 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. Adds the generated symlink patterns to `.gitignore` (they are machine-local).
+
+It is **disabled automatically in production/CI** — skills are a development-time
+concern.
+
+### Supported agents
+
+| Agent          | Output directory  | Detected when present |
+| -------------- | ----------------- | --------------------- |
+| Claude Code    | `.claude/skills/` | `.claude/`            |
+| Cursor         | `.agents/skills/` | `.cursor/`            |
+| Codex          | `.agents/skills/` | `.codex/` or `AGENTS.md` |
+| GitHub Copilot | `.agents/skills/` | `.github/`            |
+
+`.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.
+
+## Installation
+
+Add the plugin to your `Gemfile` (this is the recommended, team-wide way):
+
+```ruby
+# Gemfile
+source "https://rubygems.org"
+
+plugin "bundler-skills"
+
+gem "some-gem-that-ships-skills"
+```
+
+Then:
+
+```sh
+bundle install
+```
+
+That's it. On install you'll see something like:
+
+```
+[bundler-skills] 3 skill(s) discovered, 3 linked, 0 pruned across 1 dir(s) (agents: claude)
+```
+
+> 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
+
+`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:
+
+```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 <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.
+
+## 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)
+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
+```
+
+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`.
+
+## Naming: `gem-<gem>--<skill>`
+
+The boundary between gem name and skill name is a **double hyphen** (`--`) so a
+gem name that itself contains hyphens stays unambiguous:
+
+```
+gem-rails-html-sanitizer--escaping
+    └── gem: rails-html-sanitizer ──┘└ skill: escaping
+```
+
+RubyGems names cannot contain consecutive hyphens, so `--` is always a safe
+delimiter. (This is an intentional improvement over skills-npm's `npm-` naming.)
+
+## For gem authors
+
+See [PROPOSAL.md](PROPOSAL.md) for the distribution convention. In short: put
+`skills/<name>/SKILL.md` in your gem and include `skills/` in your gemspec
+`files`.
+
+## Trust boundary
+
+Skills bundled in third-party gems are third-party content. This plugin 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.
+
+## Limitations
+
+- 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.
+
+## Development
+
+```sh
+bundle install
+bundle exec rake test          # unit tests
+bundle exec rake integration   # real bundle install end-to-end
+```
+
+See [CHANGELOG.md](CHANGELOG.md) for release notes.
+
+## License
+
+MIT. See [LICENSE.txt](LICENSE.txt).

data/lib/bundler_skills/agent_registry.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module BundlerSkills
+  # Knows where each supported agent reads project-level skills and how to
+  # detect that the agent is in use. Dependency-free: a small internal table,
+  # the single place to edit when an agent's convention changes.
+  #
+  # Output dirs collapse to two in practice:
+  #   .claude/skills  — Claude Code only (does not read .agents/skills yet)
+  #   .agents/skills  — cross-tool standard, shared by Cursor / Codex / Copilot
+  module AgentRegistry
+    # key          : config name (`agents:` entries match this)
+    # skills_subdir: output directory relative to the project root
+    # markers       : any of these existing means "this agent is in use"
+    Agent = Struct.new(:key, :skills_subdir, :markers, keyword_init: true)
+
+    ALL = [
+      Agent.new(key: "claude",  skills_subdir: ".claude/skills",  markers: [".claude"]),
+      Agent.new(key: "cursor",  skills_subdir: ".agents/skills",  markers: [".cursor"]),
+      Agent.new(key: "codex",   skills_subdir: ".agents/skills",  markers: [".codex", "AGENTS.md"]),
+      Agent.new(key: "copilot", skills_subdir: ".agents/skills",  markers: [".github"])
+    ].freeze
+
+    module_function
+
+    def all
+      ALL
+    end
+
+    def find(key)
+      ALL.find { |a| a.key == key.to_s }
+    end
+
+    # Agents whose marker exists under root.
+    def detect(root)
+      ALL.select { |agent| present?(root, agent) }
+    end
+
+    # Resolve the agents to target:
+    #   config.agents nil      -> auto-detect by markers
+    #   config.agents ["*"]    -> all agents
+    #   config.agents [keys..] -> those keys (unknown keys ignored)
+    def resolve(root, config)
+      requested = config.agents
+      return detect(root) if requested.nil? || requested.empty?
+
+      keys = Array(requested).map(&:to_s)
+      return all if keys.include?("*")
+
+      keys.filter_map { |key| find(key) }
+    end
+
+    # Distinct output subdirs for the given agents, preserving order.
+    def output_subdirs(agents)
+      agents.map(&:skills_subdir).uniq
+    end
+
+    def present?(root, agent)
+      agent.markers.any? { |m| File.exist?(File.join(root.to_s, m)) }
+    end
+  end
+end

data/lib/bundler_skills/command.rb

@@ -0,0 +1,96 @@
+# 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"
+
+    def exec(_command_name, args)
+      dry_run = args.delete("--dry-run") ? true : false
+      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 "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_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
+
+        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/config.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+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:
+  #   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
+  #   recursive  bool (default false) — scan skills/**/SKILL.md
+  #   include    [patterns]  — fnmatch on gem name or "gem/skill"
+  #   exclude    [patterns]  — same, wins over include
+  #   dry_run / force  bool
+  class Config
+    CONFIG_FILENAME = "bundler-skills.yml"
+
+    DEFAULTS = {
+      "enabled" => nil,
+      "agents" => nil,
+      "gitignore" => true,
+      "cleanup" => true,
+      "recursive" => false,
+      "dry_run" => false,
+      "force" => false,
+      "include" => [],
+      "exclude" => []
+    }.freeze
+
+    def self.load(root: Bundler.root)
+      path = File.join(root.to_s, CONFIG_FILENAME)
+      data = read_yaml(path)
+      new(DEFAULTS.merge(data))
+    end
+
+    def self.read_yaml(path)
+      return {} unless File.file?(path)
+
+      require "yaml"
+      loaded = YAML.safe_load_file(path)
+      loaded.is_a?(Hash) ? loaded : {}
+    rescue StandardError => e
+      Bundler.ui.warn("[bundler-skills] failed to read #{path}: #{e.message}") if defined?(Bundler)
+      {}
+    end
+
+    def initialize(data)
+      @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
+      value = @data["agents"]
+      return nil if value.nil?
+
+      Array(value).map(&:to_s)
+    end
+
+    def gitignore?
+      @data["gitignore"] != false
+    end
+
+    def cleanup?
+      @data["cleanup"] != false
+    end
+
+    def recursive?
+      @data["recursive"] == true
+    end
+
+    def dry_run?
+      @data["dry_run"] == true
+    end
+
+    def force?
+      @data["force"] == true
+    end
+
+    def include_patterns
+      Array(@data["include"]).map(&:to_s)
+    end
+
+    def exclude_patterns
+      Array(@data["exclude"]).map(&:to_s)
+    end
+
+    # include/exclude are matched against the gem name (and "gem/skill") using
+    # File.fnmatch wildcards. Empty include = allow all; exclude wins.
+    def included?(gem_name, skill_name)
+      return false if matches_any?(exclude_patterns, gem_name, skill_name)
+      return true if include_patterns.empty?
+
+      matches_any?(include_patterns, gem_name, skill_name)
+    end
+
+    private
+
+    def matches_any?(patterns, gem_name, skill_name)
+      candidates = [gem_name, "#{gem_name}/#{skill_name}"]
+      patterns.any? do |pattern|
+        candidates.any? { |c| File.fnmatch?(pattern, c, File::FNM_EXTGLOB) }
+      end
+    end
+  end
+end

data/lib/bundler_skills/disabling.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module BundlerSkills
+  # Decides whether the plugin should run in the current environment.
+  #
+  # 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.
+  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)
+    end
+
+    def truthy?(value)
+      return false if value.nil?
+
+      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/discovered_skill.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module BundlerSkills
+  # One skill found inside a dependency gem.
+  #
+  # source_path : absolute path to the directory containing SKILL.md
+  # link_name   : symlink basename, "gem-<gem>--<skill>" (double-hyphen boundary
+  #               so a gem name containing single hyphens stays unambiguous)
+  class DiscoveredSkill
+    LINK_PREFIX = "gem-"
+    BOUNDARY = "--"
+
+    attr_reader :gem_name, :skill_name, :source_path
+
+    def initialize(gem_name:, skill_name:, source_path:)
+      @gem_name = gem_name
+      @skill_name = skill_name
+      @source_path = source_path
+    end
+
+    def link_name
+      "#{LINK_PREFIX}#{gem_name}#{BOUNDARY}#{skill_name}"
+    end
+
+    def ==(other)
+      other.is_a?(DiscoveredSkill) &&
+        gem_name == other.gem_name &&
+        skill_name == other.skill_name &&
+        source_path == other.source_path
+    end
+    alias eql? ==
+
+    def hash
+      [gem_name, skill_name, source_path].hash
+    end
+  end
+end

data/lib/bundler_skills/discoverer.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require_relative "discovered_skill"
+
+module BundlerSkills
+  # Finds skills bundled in the resolved dependency gems.
+  #
+  # This is the ONLY place that touches the Bundler spec API. The default
+  # `specs` come from Bundler.load.specs, which reflects the current
+  # environment's resolved gems (includes development/test groups unless
+  # `without` excludes them). Each spec exposes full_gem_path / name / version
+  # and works for rubygems, path and git sources alike.
+  class Discoverer
+    SKILL_FILE = "SKILL.md"
+
+    def initialize(specs: nil, config: Config.new(Config::DEFAULTS), logger: nil)
+      @specs = specs
+      @config = config
+      @logger = logger
+    end
+
+    # @return [Array<DiscoveredSkill>]
+    def discover
+      specs.flat_map { |spec| skills_in(spec) }.compact
+    end
+
+    private
+
+    def specs
+      @specs ||= Bundler.load.specs
+    end
+
+    def skills_in(spec)
+      gem_path = spec.full_gem_path
+      return [] unless gem_path && File.directory?(gem_path)
+
+      pattern = @config.recursive? ? "skills/**/#{SKILL_FILE}" : "skills/*/#{SKILL_FILE}"
+      Dir.glob(File.join(gem_path, pattern)).filter_map do |skill_md|
+        skill_dir = File.dirname(skill_md)
+        skill_name = File.basename(skill_dir)
+        next unless @config.included?(spec.name, skill_name)
+
+        DiscoveredSkill.new(
+          gem_name: spec.name,
+          skill_name: skill_name,
+          source_path: File.expand_path(skill_dir)
+        )
+      end
+    rescue StandardError => e
+      warn_skip(spec, e)
+      []
+    end
+
+    def warn_skip(spec, error)
+      message = "[bundler-skills] skipped #{spec.name}: #{error.class}: #{error.message}"
+      if @logger
+        @logger.warn(message)
+      elsif defined?(Bundler)
+        Bundler.ui.warn(message)
+      end
+    end
+  end
+end

data/lib/bundler_skills/gitignore_updater.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module BundlerSkills
+  # Keeps a managed block in .gitignore listing the generated symlink patterns
+  # (e.g. .claude/skills/gem-*, .agents/skills/gem-*). The block is delimited by
+  # marker comments so it can be detected and rewritten without touching the
+  # rest of the file. Idempotent: re-running with the same patterns is a no-op.
+  class GitignoreUpdater
+    BEGIN_MARKER = "# >>> bundler-skills managed >>>"
+    END_MARKER = "# <<< bundler-skills managed <<<"
+
+    def initialize(gitignore_path:, dry_run: false)
+      @gitignore_path = gitignore_path
+      @dry_run = dry_run
+    end
+
+    # @param patterns [Array<String>] e.g. [".claude/skills/gem-*"]
+    # @return [Boolean] true when the file was changed (or would be, in dry-run)
+    def ensure_patterns(patterns)
+      patterns = patterns.uniq
+      return false if patterns.empty?
+
+      existing = File.exist?(@gitignore_path) ? File.read(@gitignore_path) : nil
+      updated = rewrite(existing, patterns)
+      return false if updated == existing
+
+      File.write(@gitignore_path, updated) unless @dry_run
+      true
+    end
+
+    private
+
+    def rewrite(existing, patterns)
+      block = build_block(patterns)
+      return block if existing.nil? || existing.empty?
+
+      if existing.include?(BEGIN_MARKER) && existing.include?(END_MARKER)
+        replace_block(existing, block)
+      else
+        separator = existing.end_with?("\n") ? "\n" : "\n\n"
+        "#{existing}#{separator}#{block}"
+      end
+    end
+
+    def build_block(patterns)
+      lines = [BEGIN_MARKER, *patterns, END_MARKER]
+      "#{lines.join("\n")}\n"
+    end
+
+    def replace_block(existing, block)
+      pattern = /#{Regexp.escape(BEGIN_MARKER)}.*?#{Regexp.escape(END_MARKER)}\n?/m
+      existing.sub(pattern, block)
+    end
+  end
+end

data/lib/bundler_skills/hook.rb

@@ -0,0 +1,31 @@
+# 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/lib/bundler_skills/linker.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module BundlerSkills
+  # Creates idempotent absolute symlinks for discovered skills into a single
+  # output directory, and prunes stale ones we previously created.
+  #
+  # Pure filesystem operations — no Bundler dependency, so it is fully unit
+  # testable against a tmpdir. One Linker instance == one output directory
+  # (e.g. .claude/skills or .agents/skills).
+  class Linker
+    STALE_GLOB = "#{DiscoveredSkill::LINK_PREFIX}*#{DiscoveredSkill::BOUNDARY}*"
+
+    class Result
+      attr_reader :created, :kept, :relinked, :skipped, :pruned
+
+      def initialize
+        @created = []
+        @kept = []
+        @relinked = []
+        @skipped = []
+        @pruned = []
+      end
+    end
+
+    def initialize(skills_dir:, config: Config.new(Config::DEFAULTS), logger: nil)
+      @skills_dir = skills_dir
+      @config = config
+      @logger = logger
+    end
+
+    # @param skills [Array<DiscoveredSkill>]
+    # @return [Result]
+    def link(skills)
+      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?
+      result
+    end
+
+    # Remove every gem-*--* symlink we own (for `bundle skills clean`).
+    # @return [Array<String>] removed link names
+    def clean_all
+      removed = []
+      Dir.glob(File.join(@skills_dir, STALE_GLOB)).each do |path|
+        next unless File.symlink?(path)
+
+        remove(path)
+        removed << File.basename(path)
+      end
+      removed
+    end
+
+    private
+
+    def ensure_dir
+      return if @config.dry_run?
+
+      FileUtils.mkdir_p(@skills_dir)
+    end
+
+    def link_one(skill, result)
+      link_path = File.join(@skills_dir, skill.link_name)
+      target = skill.source_path
+
+      if File.symlink?(link_path)
+        if File.readlink(link_path) == target
+          result.kept << skill.link_name
+        else
+          replace_symlink(link_path, target)
+          result.relinked << skill.link_name
+        end
+      elsif File.exist?(link_path)
+        # A real file/dir the user created — never clobber it (unless force).
+        if @config.force?
+          remove(link_path)
+          create_symlink(link_path, target)
+          result.relinked << skill.link_name
+        else
+          warn("refusing to overwrite non-symlink #{link_path}")
+          result.skipped << skill.link_name
+        end
+      else
+        create_symlink(link_path, target)
+        result.created << skill.link_name
+      end
+    end
+
+    # 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)
+      Dir.glob(File.join(@skills_dir, STALE_GLOB)).each do |path|
+        name = File.basename(path)
+        next if valid_link_names.include?(name)
+        next unless File.symlink?(path) # only prune our own symlinks
+
+        remove(path)
+        result.pruned << name
+      end
+    end
+
+    def replace_symlink(link_path, target)
+      remove(link_path)
+      create_symlink(link_path, target)
+    end
+
+    def create_symlink(link_path, target)
+      return if @config.dry_run?
+
+      File.symlink(target, link_path)
+    end
+
+    def remove(path)
+      return if @config.dry_run?
+
+      if File.symlink?(path)
+        File.delete(path)
+      else
+        FileUtils.remove_entry(path)
+      end
+    end
+
+    def warn(message)
+      full = "[bundler-skills] #{message}"
+      if @logger
+        @logger.warn(full)
+      elsif defined?(Bundler)
+        Bundler.ui.warn(full)
+      end
+    end
+  end
+end

data/lib/bundler_skills/synchronizer.rb

@@ -0,0 +1,94 @@
+# 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.
+  #
+  # Discovery runs once (agent-independent); linking runs once per distinct
+  # output directory (.claude/skills and/or .agents/skills). Phase 4 adds the
+  # .gitignore update.
+  class Synchronizer
+    Result = Struct.new(:discovered, :agents, :links_by_dir, :gitignore_changed, keyword_init: true)
+
+    def initialize(root: Bundler.root, config: Config.load, logger: Bundler.ui, specs: nil)
+      @root = root
+      @config = config
+      @logger = logger
+      @specs = specs
+    end
+
+    def sync
+      skills = Discoverer.new(specs: @specs, config: @config, logger: @logger).discover
+      agents = AgentRegistry.resolve(@root, @config)
+      subdirs = AgentRegistry.output_subdirs(agents)
+
+      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)]
+      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`.
+    def plan
+      skills = Discoverer.new(specs: @specs, config: @config, logger: @logger).discover
+      agents = AgentRegistry.resolve(@root, @config)
+      Result.new(
+        discovered: skills, agents: agents,
+        links_by_dir: {}, gitignore_changed: false
+      )
+    end
+
+    # Remove every gem-*--* symlink we own across all known output dirs.
+    # Used by `bundle 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)
+        linker = Linker.new(skills_dir: skills_dir, config: @config, logger: @logger)
+        [subdir, linker.clean_all]
+      end
+    end
+
+    private
+
+    def update_gitignore(subdirs)
+      return false unless @config.gitignore?
+      return false if subdirs.empty?
+
+      patterns = subdirs.map { |subdir| "#{subdir}/#{DiscoveredSkill::LINK_PREFIX}*" }
+      GitignoreUpdater.new(
+        gitignore_path: File.join(@root.to_s, ".gitignore"),
+        dry_run: @config.dry_run?
+      ).ensure_patterns(patterns)
+    end
+
+    def log_summary(skills, agents, links_by_dir)
+      return unless @logger
+
+      if agents.empty?
+        @logger.info(
+          "[bundler-skills] #{skills.size} skill(s) discovered but no agent detected " \
+          "(.claude/.cursor/.codex/AGENTS.md/.github) — nothing linked"
+        )
+        return
+      end
+
+      created = links_by_dir.values.sum { |r| r.created.size }
+      pruned = links_by_dir.values.sum { |r| r.pruned.size }
+      @logger.info(
+        "[bundler-skills] #{skills.size} skill(s) discovered, " \
+        "#{created} linked, #{pruned} pruned across #{links_by_dir.size} dir(s) " \
+        "(agents: #{agents.map(&:key).join(', ')})"
+      )
+    end
+  end
+end

data/lib/bundler_skills/version.rb

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

data/lib/bundler_skills.rb

@@ -0,0 +1,15 @@
+# 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"
+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/plugins.rb

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

metadata

@@ -0,0 +1,63 @@
+--- !ruby/object:Gem::Specification
+name: bundler-skills
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- aki77
+bindir: bin
+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.
+email:
+- aki77@users.noreply.github.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- PROPOSAL.md
+- README.md
+- lib/bundler_skills.rb
+- lib/bundler_skills/agent_registry.rb
+- lib/bundler_skills/command.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/synchronizer.rb
+- lib/bundler_skills/version.rb
+- plugins.rb
+homepage: https://github.com/aki77/bundler-skills
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/aki77/bundler-skills
+  source_code_uri: https://github.com/aki77/bundler-skills.git
+  changelog_uri: https://github.com/aki77/bundler-skills/blob/main/CHANGELOG.md
+  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.10
+specification_version: 4
+summary: Auto-symlink AI agent skills bundled in your gems after bundle install.
+test_files: []