gem-skill 0.1.1 → 0.1.3

data/lib/gem/skill/generator.rb

@@ -21,7 +21,9 @@ module Gem::Skill
       Output raw Markdown directly. Do NOT wrap the output in a code fence or any
       other container — the file is Markdown, so no ```markdown wrapper.
 
-      Begin immediately with the first section heading. Use exactly these sections:
+      Begin with a top-level heading identifying the gem and version, then use exactly these sections:
+
+      # %<gem_name>s v%<version>s
 
       ## Overview
       One paragraph: what the gem does and when to reach for it.

data/lib/gem/skill/linker.rb

@@ -4,26 +4,28 @@ require "fileutils"
 
 module Gem::Skill
   # Manages .claude/skills/ symlinks in a project, pointing to ~/.gem/skills cache.
+  # Each symlink is a directory link: <gem_name> -> ~/.gem/skills/<gem>/<version>/
+  # Claude Code discovers skills by reading SKILL.md inside each linked directory.
   module Linker
     def self.skills_dir(project_root = Dir.pwd)
       File.join(project_root, ".claude", "skills")
     end
 
     def self.link(gem_name, version, project_root = Dir.pwd)
-      target = Cache.skill_path(gem_name, version)
+      target_dir = File.dirname(Cache.skill_path(gem_name, version))
       raise Error, "No cached skill for #{gem_name} #{version}. Run: gem skill install #{gem_name}" \
-        unless File.exist?(target)
+        unless File.exist?(Cache.skill_path(gem_name, version))
 
       dir = skills_dir(project_root)
       FileUtils.mkdir_p(dir)
 
-      link_path = File.join(dir, "#{gem_name}.md")
+      link_path = File.join(dir, gem_name)
       File.unlink(link_path) if File.symlink?(link_path)
-      File.symlink(target, link_path)
+      File.symlink(target_dir, link_path)
     end
 
     def self.unlink(gem_name, project_root = Dir.pwd)
-      link_path = File.join(skills_dir(project_root), "#{gem_name}.md")
+      link_path = File.join(skills_dir(project_root), gem_name)
       File.unlink(link_path) if File.symlink?(link_path)
     end
 
@@ -31,13 +33,14 @@ module Gem::Skill
       dir = skills_dir(project_root)
       return [] unless Dir.exist?(dir)
 
-      Dir.glob(File.join(dir, "*.md")).filter_map do |path|
+      Dir.glob(File.join(dir, "*")).filter_map do |path|
         next unless File.symlink?(path)
 
-        gem_name = File.basename(path, ".md")
-        target   = File.readlink(path)
-        version  = target.match(%r{/([^/]+)/SKILL\.md$})&.captures&.first
-        { gem_name: gem_name, version: version, target: target, valid: File.exist?(target) }
+        gem_name   = File.basename(path)
+        target_dir = File.readlink(path)
+        version    = target_dir.match(%r{/([^/]+)$})&.captures&.first
+        skill_file = File.join(target_dir, "SKILL.md")
+        { gem_name: gem_name, version: version, target: target_dir, valid: File.exist?(skill_file) }
       end
     end
 

data/lib/gem/skill/lockfile.rb

@@ -11,9 +11,9 @@ module Gem::Skill
     end
 
     def self.parse(content)
-      specs   = parse_specs(content)
-      direct  = parse_direct_names(content)
-      direct.each_with_object({}) do |name, hash|
+      specs  = parse_specs(content)
+      direct = parse_direct_names(content) + parse_path_dep_names(content)
+      direct.uniq.each_with_object({}) do |name, hash|
         hash[name] = specs[name] if specs.key?(name)
       end
     end
@@ -36,6 +36,33 @@ module Gem::Skill
       specs
     end
 
+    def self.parse_path_dep_names(content)
+      in_path  = false
+      in_specs = false
+      in_gem   = false
+      names    = []
+
+      content.each_line do |line|
+        if line.strip == "PATH"
+          in_path = true
+          in_specs = false
+          in_gem   = false
+        elsif in_path && line.strip == "specs:"
+          in_specs = true
+        elsif in_path && in_specs && line =~ /\A {4}\S/
+          in_gem = true
+        elsif in_path && in_specs && in_gem && line =~ /\A {6}(\S+)/
+          names << Regexp.last_match(1)
+        elsif in_path && !line.start_with?(" ") && !line.strip.empty?
+          in_path  = false
+          in_specs = false
+          in_gem   = false
+        end
+      end
+
+      names
+    end
+
     def self.parse_direct_names(content)
       in_deps = false
       names   = []

data/lib/gem/skill/runner.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Gem::Skill
+  # Core install logic shared by gem_command and bundle_command.
+  # Callers are responsible for spinner.auto_spin and title setup before calling.
+  module Runner
+    # Generate + cache + link one skill.
+    # Returns nil on success, error message string on failure.
+    def self.install_skill(gem_name, version, spinner, force:, model:)
+      if Cache.cached?(gem_name, version) && !force
+        Linker.link(gem_name, version)
+        spinner.success("already cached")
+        return nil
+      end
+      Generator.new(gem_name, version, model: model).generate(force: force)
+      Linker.link(gem_name, version)
+      spinner.success("done")
+      nil
+    rescue => e
+      spinner.error("failed")
+      e.message
+    end
+  end
+end

data/lib/gem/skill/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Gem::Skill
-  VERSION = "0.1.1"
+  VERSION = "0.1.3"
 end

data/lib/gem/skill.rb

@@ -6,6 +6,7 @@ require_relative "skill/fetcher"
 require_relative "skill/generator"
 require_relative "skill/linker"
 require_relative "skill/lockfile"
+require_relative "skill/runner"
 
 module Gem::Skill
   class Error < StandardError; end

data/mkdocs.yml

@@ -0,0 +1,115 @@
+site_name: gem-skill
+site_description: Generate and manage Claude Code AI skills from Ruby gem documentation
+site_author: Dewayne VanHoozer
+site_url: https://madbomber.github.io/gem-skill
+copyright: Copyright © 2026 Dewayne VanHoozer
+
+repo_name: madbomber/gem-skill
+repo_url: https://github.com/madbomber/gem-skill
+edit_uri: edit/main/docs/
+
+theme:
+  name: material
+
+  palette:
+    - scheme: default
+      primary: deep purple
+      accent: purple
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    - scheme: slate
+      primary: deep purple
+      accent: purple
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+
+  font:
+    text: Roboto
+    code: Roboto Mono
+
+  features:
+    - navigation.instant
+    - navigation.tracking
+    - navigation.tabs
+    - navigation.tabs.sticky
+    - navigation.sections
+    - navigation.path
+    - navigation.indexes
+    - navigation.top
+    - toc.follow
+    - search.suggest
+    - search.highlight
+    - search.share
+    - header.autohide
+    - content.code.copy
+    - content.code.annotate
+    - content.tabs.link
+    - content.tooltips
+    - content.action.edit
+    - content.action.view
+
+plugins:
+  - search:
+      separator: '[\s\-,:!=\[\]()"`/]+|\.(?!\d)|&[lg]t;|(?!\b)(?=[A-Z][a-z])'
+
+markdown_extensions:
+  - abbr
+  - admonition
+  - attr_list
+  - def_list
+  - footnotes
+  - md_in_html
+  - toc:
+      permalink: true
+      title: On this page
+  - pymdownx.betterem:
+      smart_enable: all
+  - pymdownx.caret
+  - pymdownx.details
+  - pymdownx.emoji:
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.keys
+  - pymdownx.magiclink:
+      repo_url_shorthand: true
+      user: madbomber
+      repo: gem-skill
+  - pymdownx.mark
+  - pymdownx.smartsymbols
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+  - pymdownx.tabbed:
+      alternate_style: true
+  - pymdownx.tasklist:
+      custom_checkbox: true
+  - pymdownx.tilde
+
+extra:
+  social:
+    - icon: fontawesome/brands/github
+      link: https://github.com/madbomber/gem-skill
+      name: gem-skill on GitHub
+    - icon: fontawesome/solid/gem
+      link: https://rubygems.org/gems/gem-skill
+      name: gem-skill on RubyGems
+
+nav:
+  - Home: index.md
+  - Installation: installation.md
+  - Configuration: configuration.md
+  - Commands:
+    - gem skill: commands/gem-skill.md
+    - bundle skill: commands/bundle-skill.md
+  - How It Works: how-it-works.md
+  - Cache: cache.md
+  - Skill Files: skill-files.md

data/scripts/e2e_test

@@ -1,16 +1,20 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-# End-to-end test: fetch docs for a gem and generate a SKILL.md
-# Usage: bundle exec ruby bin/e2e_test [GEM_NAME [VERSION]]
+# End-to-end test: full pipeline for one gem — fetch, generate, cache, link.
+# Usage: bundle exec ruby scripts/e2e_test [GEM_NAME [VERSION [MODEL]]]
 
 $LOAD_PATH.unshift File.expand_path("../lib", __dir__)
 require "gem/skill"
-require "ruby_llm"
+require "gem/skill/runner"
+require "gem/skill/linker"
+require "async"
+require "tty-spinner"
+require "tmpdir"
 
 GEM_NAME = ARGV[0] || "zeitwerk"
 VERSION  = ARGV[1] || Gem::Specification.find_by_name(GEM_NAME)&.version&.to_s
-MODEL    = ARGV[2] || "gpt-4o-mini"
+MODEL    = ARGV[2] || Gem::Skill::Generator::DEFAULT_MODEL
 
 abort "Gem '#{GEM_NAME}' not installed. Run: gem install #{GEM_NAME}" unless VERSION
 
@@ -29,43 +33,73 @@ puts ""
 puts "[ FETCH ]"
 fetcher = Gem::Skill::Fetcher.new(GEM_NAME, VERSION)
 sources = fetcher.fetch_all
+abort "No sources found — nothing to generate from." if sources.empty?
 
-if sources.empty?
-  abort "No sources found — nothing to generate from."
-end
-
-sources.each do |name, content|
-  puts "  %-12s %d chars" % [name, content.length]
-end
+sources.each { |name, content| puts "  %-12s %d chars" % [name, content.length] }
 puts ""
 
-# --- Phase 2: Generate ---
-
-puts "[ GENERATE ]  streaming output below"
-puts "-" * 60
-
-skill_content = ""
-generator = Gem::Skill::Generator.new(GEM_NAME, VERSION, model: MODEL)
-skill_content = generator.generate(force: true) do |chunk|
-  print chunk
-  $stdout.flush
+# --- Phase 2: Runner.install_skill via async fiber ---
+
+puts "[ RUNNER ]  (via Async fiber + TTY spinner)"
+multi = TTY::Spinner::Multi.new("[:spinner] Installing skill", format: :dots, output: $stderr)
+sp    = multi.register("  [:spinner] :title")
+sp.update(title: "#{GEM_NAME} #{VERSION}")
+
+err = nil
+Async do
+  barrier = Async::Barrier.new
+  barrier.async do
+    sp.auto_spin
+    err = Gem::Skill::Runner.install_skill(GEM_NAME, VERSION, sp, force: true, model: MODEL)
+  end
+  barrier.wait
+ensure
+  barrier.stop
 end
 
-puts ""
-puts "-" * 60
+if err
+  abort "\nRunner failed: #{err}"
+end
 puts ""
 
 # --- Phase 3: Verify cache ---
 
 puts "[ CACHE ]"
 cached_path = Gem::Skill::Cache.skill_path(GEM_NAME, VERSION)
-if File.exist?(cached_path)
-  puts "  Written: #{cached_path}"
-  puts "  Size:    #{File.size(cached_path)} bytes"
-else
-  puts "  ERROR: cache file not found at #{cached_path}"
-  exit 1
+abort "  ERROR: cache file not found at #{cached_path}" unless File.exist?(cached_path)
+
+metadata_path = Gem::Skill::Cache.metadata_path(GEM_NAME, VERSION)
+puts "  SKILL.md:  #{cached_path} (#{File.size(cached_path)} bytes)"
+puts "  metadata:  #{metadata_path} (#{File.exist?(metadata_path) ? "present" : "MISSING"})"
+puts ""
+
+# --- Phase 4: Linker ---
+
+puts "[ LINKER ]"
+project_dir = Dir.mktmpdir("gem-skill-e2e")
+begin
+  Gem::Skill::Linker.link(GEM_NAME, VERSION, project_dir)
+
+  link_path  = File.join(project_dir, ".claude", "skills", GEM_NAME)
+  skill_via_link = File.join(link_path, "SKILL.md")
+
+  abort "  ERROR: symlink not created at #{link_path}" unless File.symlink?(link_path)
+  abort "  ERROR: symlink does not resolve to a directory" unless File.directory?(link_path)
+  abort "  ERROR: SKILL.md not accessible through symlink" unless File.exist?(skill_via_link)
+
+  puts "  symlink:   #{link_path}"
+  puts "  -> target: #{File.readlink(link_path)}"
+  puts "  SKILL.md accessible through symlink: yes"
+
+  entries = Gem::Skill::Linker.linked_gems(project_dir)
+  entry   = entries.find { |e| e[:gem_name] == GEM_NAME }
+  abort "  ERROR: linked_gems did not return #{GEM_NAME}" unless entry
+  puts "  linked_gems reports: #{entry.inspect}"
+ensure
+  FileUtils.rm_rf(project_dir)
 end
 
 puts ""
-puts "Done."
+puts "=" * 60
+puts "All phases passed."
+puts "=" * 60

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gem-skill
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.3
 platform: ruby
 authors:
 - Dewayne VanHoozer
@@ -10,21 +10,21 @@ cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: ruby_llm
+  name: async
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '2.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '2.0'
 - !ruby/object:Gem::Dependency
-  name: thor
+  name: ruby_llm
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
@@ -62,10 +62,21 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".envrc"
+- ".github/workflows/deploy-github-pages.yml"
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
 - Rakefile
+- docs/assets/images/gem-skill.jpg
+- docs/cache.md
+- docs/commands/bundle-skill.md
+- docs/commands/gem-skill.md
+- docs/configuration.md
+- docs/how-it-works.md
+- docs/index.md
+- docs/installation.md
+- docs/skill-files.md
 - lib/gem/skill.rb
 - lib/gem/skill/cache.rb
 - lib/gem/skill/cli/bundle_command.rb
@@ -74,8 +85,10 @@ files:
 - lib/gem/skill/generator.rb
 - lib/gem/skill/linker.rb
 - lib/gem/skill/lockfile.rb
+- lib/gem/skill/runner.rb
 - lib/gem/skill/version.rb
 - lib/rubygems_plugin.rb
+- mkdocs.yml
 - plugins.rb
 - scripts/e2e_test
 - sig/gem/skill.rbs
@@ -85,7 +98,18 @@ licenses:
 metadata:
   homepage_uri: https://github.com/madbomber/gem-skill
   source_code_uri: https://github.com/madbomber/gem-skill
-  changelog_uri: https://github.com/madbomber/gem-skill/blob/master/CHANGELOG.md
+  changelog_uri: https://github.com/madbomber/gem-skill/blob/main/CHANGELOG.md
+post_install_message: |
+  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    gem-skill installed!
+
+    'gem skill install GEM_NAME' is ready to use.
+
+    To enable 'bundle skill' in your projects, run:
+
+      gem skill setup
+
+  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 rdoc_options: []
 require_paths:
 - lib