agent_skills_configurations 0.1.0

data/doc/AgentSkillsConfigurations/Registry.md

@@ -0,0 +1,278 @@
+# Class: AgentSkillsConfigurations::Registry
+**Inherits:** Object
+    
+
+Loads agent configurations, resolves paths, and exposes query helpers.
+
+The Registry is the internal implementation class that handles:
+
+*   Loading and parsing the YAML configuration file
+*   Resolving environment variables to absolute paths
+*   Handling fallback paths for missing directories
+*   Detecting which agents are installed on the system
+*   Caching results for performance
+
+This class is typically used through the public API methods in the
+{AgentSkillsConfigurations} module, but can also be used directly for advanced
+use cases.
+
+## Path Resolution
+
+The Registry uses a sophisticated path resolution system that respects
+environment variables and provides fallback locations. The resolution process
+works as follows:
+
+1.  Check if the configured environment variable is set and non-empty
+2.  If set, use that value as the base path
+3.  If not set, use the configured fallback path (often relative to home)
+4.  Expand relative paths using the user's home directory
+
+Example resolution flow for XDG_CONFIG_HOME:
+
+    # Configuration in YAML:
+    base_paths:
+      xdg_config:
+        env_var: XDG_CONFIG_HOME
+        fallback: ".config"
+
+    # With environment variable set:
+    ENV["XDG_CONFIG_HOME"] = "/custom/xdg"
+    # => resolves to "/custom/xdg"
+
+    # Without environment variable:
+    ENV["XDG_CONFIG_HOME"] = nil
+    # => resolves to "/Users/username/.config"
+
+    # Empty environment variable treated as unset:
+    ENV["XDG_CONFIG_HOME"] = ""
+    # => resolves to "/Users/username/.config"
+
+## Global Skills Path Resolution
+
+Global skills paths are resolved relative to the agent's base path and support
+multiple fallbacks. The Registry checks each candidate path in order and
+returns the first one that exists:
+
+    # Configuration in YAML:
+    agents:
+      - name: moltbot
+        base_path: home
+        global_skills_path: ".moltbot/skills"
+        global_skills_path_fallbacks:
+          - ".clawdbot/skills"
+          - ".moltbot/skills"
+
+    # Resolution order:
+    # 1. Check ~/.moltbot/skills
+    # 2. Check ~/.clawdbot/skills
+    # 3. Check ~/.moltbot/skills (fallback)
+    # 4. Return first existing path, or primary path if none exist
+
+## Installation Detection
+
+The Registry determines whether an agent is installed by checking the paths
+configured in the agent's `detect_paths` array. Each path spec can be one of
+several types:
+
+*   **String**: Check if the path exists relative to the user's home directory
+*   *Hash with `cwd`*: Check if the path exists relative to the current
+    working directory
+*   *Hash with `base` and `path`*: Check if the path exists relative to a
+    configured base path
+*   *Hash with `absolute`*: Check if the absolute path exists
+
+An agent is considered installed if **any** of its detect paths exists.
+
+Examples of detect paths:
+
+    agents:
+      - name: cursor
+        detect_paths:
+          - ".cursor"  # Check ~/.cursor exists
+
+      - name: antigravity
+        detect_paths:
+          - { cwd: ".agent" }  # Check .agent exists in current dir
+          - { base: home, path: ".gemini/antigravity" }  # Check ~/.gemini/antigravity exists
+
+      - name: codex
+        detect_paths:
+          - ""  # Always considered installed (empty string matches)
+          - { absolute: "/etc/codex" }  # Check /etc/codex exists
+
+## Caching
+
+The Registry caches the results of {all} and {installed} to avoid repeatedly
+parsing the YAML file and checking file system paths. The cache can be cleared
+using {reset}.
+
+Use {reset} when:
+
+*   Environment variables that affect path resolution have changed
+*   Agents have been installed or uninstalled
+*   The YAML configuration file has been modified
+
+**@see** [] Public API module that uses this class
+
+**@see** [] Path to the configuration file
+
+**@since** [] 0.1.0
+
+
+
+# Instance Methods
+## all() [](#method-i-all)
+Return all configured agents.
+
+Returns a frozen array of all {Agent} objects defined in the configuration.
+The result is cached on first call for performance. Path resolution happens
+once during caching and the results are reused on subsequent calls.
+
+Use {reset} to clear the cache and force re-resolution when needed.
+
+**@raise** [Psych::SyntaxError] when the YAML is invalid (only on first call)
+
+**@return** [Array<Agent>] frozen array of all agents with resolved paths
+
+**@see** [] Clear the cache
+
+**@see** [] Get only installed agents
+
+**@since** [] 0.1.0
+
+
+**@example**
+```ruby
+registry = AgentSkillsConfigurations::Registry.new
+all = registry.all
+all.map(&:name)
+# => ["amp", "claude-code", "cursor", "codex", ...]
+```
+**@example**
+```ruby
+registry = AgentSkillsConfigurations::Registry.new
+first_call = registry.all
+second_call = registry.all
+first_call.equal?(second_call)  # => true (same object)
+first_call.frozen?              # => true
+```## find(name) [](#method-i-find)
+Find an agent by name.
+
+Looks up an agent configuration by its canonical name and returns an {Agent}
+value object with resolved paths. This method performs path resolution each
+time it's called, so it reflects the current environment variables and file
+system state.
+
+**@param** [String] the canonical agent name from agents.yml
+
+**@raise** [Error] when the agent name is unknown
+
+**@return** [Agent] the resolved agent configuration with absolute paths
+
+**@since** [] 0.1.0
+
+
+**@example**
+```ruby
+registry = AgentSkillsConfigurations::Registry.new
+agent = registry.find("cursor")
+agent.name              # => "cursor"
+agent.global_skills_dir # => "/Users/username/.cursor/skills"
+```
+**@example**
+```ruby
+registry.find("unknown-agent")
+# => raises AgentSkillsConfigurations::Error: Unknown agent: unknown-agent
+```## initialize() [](#method-i-initialize)
+Create a registry from the YAML configuration.
+
+Loads the agents.yml file and parses it into a data structure that can be
+queried for agent information. The YAML is loaded safely with permitted
+classes for security.
+
+**@raise** [Psych::SyntaxError] when the YAML is invalid or malformed
+
+**@return** [Registry] a new registry instance with loaded configuration
+
+**@since** [] 0.1.0
+
+
+**@example**
+```ruby
+registry = AgentSkillsConfigurations::Registry.new
+registry.find("cursor").name  # => "cursor"
+```## installed() [](#method-i-installed)
+Return agents detected as installed on this machine.
+
+Filters the list of all agents to those that are detected as installed.
+Installation detection uses the paths configured in each agent's
+`detect_paths` configuration. An agent is considered installed if **any** of
+its detect paths exists.
+
+Detection strategies:
+
+*   String: Check if path exists relative to user's home directory
+*   Hash with `cwd`: Check relative to current working directory
+*   Hash with `base` and `path`: Check relative to configured base path
+*   Hash with `absolute`: Check absolute path directly
+
+The result is cached on first call. Use {reset} to clear the cache.
+
+**@raise** [Psych::SyntaxError] when the YAML is invalid (only on first call)
+
+**@return** [Array<Agent>] frozen array of installed agents with resolved paths
+
+**@see** [] Get all configured agents
+
+**@see** [] Clear the cache
+
+**@since** [] 0.1.0
+
+
+**@example**
+```ruby
+registry = AgentSkillsConfigurations::Registry.new
+installed = registry.installed
+installed.map(&:name)
+# => ["cursor", "claude-code"]
+```
+**@example**
+```ruby
+registry = AgentSkillsConfigurations::Registry.new
+installed_names = registry.installed.map(&:name)
+installed_names.include?("cursor")  # => true (if installed)
+installed_names.include?("unknown") # => false
+```## reset() [](#method-i-reset)
+Clear cached agent lists.
+
+Clears the internal caches for {all} and {installed} results. This forces path
+resolution to be re-executed on the next call, which is useful when:
+
+*   Environment variables affecting path resolution have changed
+*   Agents have been installed or uninstalled
+*   The YAML configuration file has been modified
+
+**@return** [void] 
+
+**@see** [] Get all agents
+
+**@see** [] Get installed agents
+
+**@since** [] 0.1.0
+
+
+**@example**
+```ruby
+registry = AgentSkillsConfigurations::Registry.new
+ENV["XDG_CONFIG_HOME"] = "/new/path"
+registry.reset
+agent = registry.find("amp")
+agent.global_skills_dir # => "/new/path/agents/skills"
+```
+**@example**
+```ruby
+registry = AgentSkillsConfigurations::Registry.new
+# Install an agent...
+registry.reset
+registry.installed # => includes newly installed agent
+```

data/doc/AgentSkillsConfigurations.md

@@ -0,0 +1,297 @@
+# Module: AgentSkillsConfigurations
+    
+
+AgentSkillsConfigurations provides a unified interface for discovering and
+accessing skill configuration paths for various AI coding agents (Cursor,
+Claude Code, Codex, etc.).
+
+This library loads agent configurations from a YAML file and resolves
+platform-specific paths for skill directories, taking into account environment
+variables, user home directories, and fallback locations. It supports
+detection of which agents are currently installed on the system and provides
+convenient query methods for accessing agent information.
+
+## Overview
+
+Each AI coding agent has two types of skill directories:
+
+1.  *Project-level skills* (skills_dir): A relative path within a project
+    where project-specific skills are stored (e.g., `.cursor/skills`,
+    `.claude/skills`)
+2.  *Global skills* (global_skills_dir): An absolute path to the user's global
+    skill repository shared across all projects (e.g., `~/.cursor/skills`)
+
+The library abstracts away the differences between agents, providing a
+consistent API for working with any supported agent type.
+
+## Configuration
+
+Agent configurations are defined in `agents.yml`, which contains:
+
+*   Base path definitions with environment variable references and fallbacks
+*   Agent entries with names, display names, skill paths, and detection rules
+
+Example YAML structure:
+
+    base_paths:
+      home:
+        env_var: ""
+        fallback: ""
+      xdg_config:
+        env_var: XDG_CONFIG_HOME
+        fallback: ".config"
+
+    agents:
+      - name: cursor
+        display_name: Cursor
+        skills_dir: ".cursor/skills"
+        base_path: home
+        global_skills_path: ".cursor/skills"
+        detect_paths:
+          - ".cursor"
+
+## Finding Agents
+
+To get a specific agent configuration by name:
+
+    agent = AgentSkillsConfigurations.find("cursor")
+    agent.name              # => "cursor"
+    agent.display_name      # => "Cursor"
+    agent.skills_dir        # => ".cursor/skills"
+    agent.global_skills_dir # => "/Users/username/.cursor/skills"
+
+Finding an unknown agent raises an error:
+
+    AgentSkillsConfigurations.find("unknown-agent")
+    # => raises AgentSkillsConfigurations::Error: Unknown agent: unknown-agent
+
+## Listing All Agents
+
+To get all configured agents:
+
+    all_agents = AgentSkillsConfigurations.all
+    all_agents.map(&:name)
+    # => ["amp", "claude-code", "cursor", "codex", "windsurf", ...]
+
+The result is cached for performance. Use {reset!} to clear the cache:
+
+    AgentSkillsConfigurations.reset!
+
+## Detecting Installed Agents
+
+To find which agents are installed on the current machine:
+
+    installed = AgentSkillsConfigurations.installed
+    installed.map(&:name)
+    # => ["cursor", "claude-code"]
+
+Installation detection works by checking configured paths:
+
+*   String paths: Checks if the path exists relative to the user's home
+    directory
+*   Hash paths with `cwd`: Checks relative to the current working directory
+*   Hash paths with `base`: Resolves using the configured base path
+*   Hash paths with `absolute`: Checks the absolute path directly
+
+Examples from the configuration:
+
+    detect_paths:
+      - ".cursor"                    # Check ~/.cursor exists
+      - { cwd: ".agent" }             # Check .agent exists in current dir
+      - { base: home, path: ".codex" } # Check ~/.codex exists
+      - { absolute: "/etc/codex" }    # Check /etc/codex exists
+
+## Environment Variables
+
+Global skill paths are resolved using environment variables when available,
+with automatic fallbacks to default locations:
+
+*   `XDG_CONFIG_HOME`: Used by Amp, Goose, and other XDG-compliant agents
+*   `CLAUDE_CONFIG_DIR`: Used by Claude Code and OpenCode
+*   `CODEX_HOME`: Used by Codex
+
+Example with XDG_CONFIG_HOME:
+
+    ENV["XDG_CONFIG_HOME"] = "/custom/xdg"
+    agent = AgentSkillsConfigurations.find("amp")
+    agent.global_skills_dir  # => "/custom/xdg/agents/skills"
+
+Without the environment variable, falls back to default:
+
+    ENV["XDG_CONFIG_HOME"] = nil
+    agent = AgentSkillsConfigurations.find("amp")
+    agent.global_skills_dir  # => "/Users/username/.config/agents/skills"
+
+## Path Resolution with Fallbacks
+
+Some agents support multiple fallback paths for global skills. The first
+existing path is used:
+
+    agents:
+      - name: moltbot
+        global_skills_path: ".moltbot/skills"
+        global_skills_path_fallbacks:
+          - ".clawdbot/skills"
+          - ".moltbot/skills"
+
+The library checks each candidate path in order and returns the first one that
+exists.
+
+## Error Handling
+
+The library raises {AgentSkillsConfigurations::Error} for configuration errors
+(unknown agents) and {Psych::SyntaxError} for invalid YAML syntax.
+
+**@author** [] Lucian Ghinda
+
+**@since** [] 0.1.0
+
+
+# Class Methods
+## all() [](#method-c-all)
+Return all configured agents.
+
+Returns a frozen array of all {Agent} objects defined in the configuration.
+The result is cached for performance. Use {reset!} to clear the cache when you
+need fresh results (e.g., after changing environment variables).
+**@raise** [Psych::SyntaxError] when the YAML configuration is invalid
+
+**@return** [Array<Agent>] all agents defined in `agents.yml`
+
+**@see** [] Clear cached agent lists
+
+**@see** [] Get only installed agents
+
+**@since** [] 0.1.0
+
+
+**@example**
+```ruby
+all_agents = AgentSkillsConfigurations.all
+all_agents.map(&:name)
+# => ["amp", "claude-code", "cursor", "codex", "windsurf", ...]
+```
+**@example**
+```ruby
+AgentSkillsConfigurations.all.each do |agent|
+  puts "#{agent.display_name}: #{agent.skills_dir}"
+end
+```
+**@example**
+```ruby
+all = AgentSkillsConfigurations.all
+cursor = all.find { |a| a.name == "cursor" }
+cursor.global_skills_dir # => "/Users/username/.cursor/skills"
+```## find(name ) [](#method-c-find)
+Find a configured agent by name.
+
+Returns an {Agent} value object containing the agent's name, display name, and
+resolved skill directory paths. This is the primary method for accessing agent
+configuration.
+**@param** [String] agent name from `agents.yml`
+
+**@raise** [Error] when the agent name is unknown
+
+**@raise** [Psych::SyntaxError] when the YAML configuration is invalid
+
+**@return** [Agent] resolved agent configuration
+
+**@since** [] 0.1.0
+
+
+**@example**
+```ruby
+agent = AgentSkillsConfigurations.find("cursor")
+agent.name              # => "cursor"
+agent.display_name      # => "Cursor"
+agent.skills_dir        # => ".cursor/skills"
+agent.global_skills_dir # => "/Users/username/.cursor/skills"
+```
+**@example**
+```ruby
+ENV["CLAUDE_CONFIG_DIR"] = "/custom/claude"
+agent = AgentSkillsConfigurations.find("claude-code")
+agent.global_skills_dir # => "/custom/claude/skills"
+```
+**@example**
+```ruby
+AgentSkillsConfigurations.find("unknown-agent")
+# => raises AgentSkillsConfigurations::Error: Unknown agent: unknown-agent
+```## installed() [](#method-c-installed)
+Return agents that appear to be installed on this machine.
+
+Installation is detected by checking the paths configured in each agent's
+`detect_paths` configuration. Different detection strategies are supported:
+
+*   String paths: Check if the path exists relative to user's home directory
+*   Hash with `cwd`: Check relative to current working directory
+*   Hash with `base`: Resolve using a configured base path
+*   Hash with `absolute`: Check an absolute path directly
+
+The result is cached for performance. Use {reset!} to clear the cache.
+**@raise** [Psych::SyntaxError] when the YAML configuration is invalid
+
+**@return** [Array<Agent>] agents matching their detect paths
+
+**@see** [] Get all configured agents regardless of installation status
+
+**@see** [] Clear cached agent lists
+
+**@since** [] 0.1.0
+
+
+**@example**
+```ruby
+installed = AgentSkillsConfigurations.installed
+installed.map(&:name)
+# => ["cursor", "claude-code"]
+```
+**@example**
+```ruby
+installed_names = AgentSkillsConfigurations.installed.map(&:name)
+installed_names.include?("cursor")  # => true
+installed_names.include?("unknown") # => false
+```
+**@example**
+```ruby
+AgentSkillsConfigurations.installed.each do |agent|
+  puts "#{agent.display_name} is installed"
+end
+```## reset!() [](#method-c-reset!)
+Clear cached agent lists.
+
+This method clears the internal caches for {all} and {installed} results. Use
+this when you need fresh data, such as:
+
+*   After changing environment variables that affect path resolution
+*   After installing or uninstalling agents
+*   After modifying the YAML configuration file
+**@raise** [Psych::SyntaxError] when the YAML configuration is invalid
+
+**@return** [void] 
+
+**@see** [] Returns cached all agents
+
+**@see** [] Returns cached installed agents
+
+**@since** [] 0.1.0
+
+
+**@example**
+```ruby
+ENV["XDG_CONFIG_HOME"] = "/new/path"
+AgentSkillsConfigurations.reset!
+agent = AgentSkillsConfigurations.find("amp")
+agent.global_skills_dir # => "/new/path/agents/skills"
+```
+**@example**
+```ruby
+AgentSkillsConfigurations.reset!
+installed = AgentSkillsConfigurations.installed
+```
+
+# Documentation
+
+- [AgentSkillsConfigurations/Agent.md](AgentSkillsConfigurations/Agent.md)
+- [AgentSkillsConfigurations/Error.md](AgentSkillsConfigurations/Error.md)
+- [AgentSkillsConfigurations/Registry.md](AgentSkillsConfigurations/Registry.md)

data/doc/index.csv

@@ -0,0 +1,18 @@
+name,type,path
+AgentSkillsConfigurations,Module,AgentSkillsConfigurations.md
+AgentSkillsConfigurations.all,Method,AgentSkillsConfigurations.md#method-c-all
+AgentSkillsConfigurations.find,Method,AgentSkillsConfigurations.md#method-c-find
+AgentSkillsConfigurations.installed,Method,AgentSkillsConfigurations.md#method-c-installed
+AgentSkillsConfigurations.reset!,Method,AgentSkillsConfigurations.md#method-c-reset!
+AgentSkillsConfigurations::Error,Class,AgentSkillsConfigurations/Error.md
+AgentSkillsConfigurations::Agent,Class,AgentSkillsConfigurations/Agent.md
+display_name,Attribute,AgentSkillsConfigurations/Agent.md#attribute-i-display_name
+global_skills_dir,Attribute,AgentSkillsConfigurations/Agent.md#attribute-i-global_skills_dir
+name,Attribute,AgentSkillsConfigurations/Agent.md#attribute-i-name
+skills_dir,Attribute,AgentSkillsConfigurations/Agent.md#attribute-i-skills_dir
+AgentSkillsConfigurations::Registry,Class,AgentSkillsConfigurations/Registry.md
+AgentSkillsConfigurations::Registry.all,Method,AgentSkillsConfigurations/Registry.md#method-i-all
+AgentSkillsConfigurations::Registry.find,Method,AgentSkillsConfigurations/Registry.md#method-i-find
+AgentSkillsConfigurations::Registry.initialize,Method,AgentSkillsConfigurations/Registry.md#method-i-initialize
+AgentSkillsConfigurations::Registry.installed,Method,AgentSkillsConfigurations/Registry.md#method-i-installed
+AgentSkillsConfigurations::Registry.reset,Method,AgentSkillsConfigurations/Registry.md#method-i-reset

data/lib/agent_skills_configurations/agent.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module AgentSkillsConfigurations
+  # Value object describing a configured agent and its skill locations.
+  #
+  # An Agent represents a single AI coding agent configuration with information about
+  # where to find project-level skills and global skills for that agent. This is a
+  # read-only data structure returned by {AgentSkillsConfigurations.find} and other
+  # query methods.
+  #
+  # == Agent Attributes
+  #
+  # Each agent has four key attributes:
+  #
+  # * +name+ - The canonical identifier used in code (e.g., "cursor", "claude-code")
+  # * +display_name+ - A human-friendly name for UI/display purposes (e.g., "Cursor", "Claude Code")
+  # * +skills_dir+ - A relative path for project-specific skills (e.g., ".cursor/skills")
+  # * +global_skills_dir+ - An absolute path to the user's global skill repository
+  #
+  # == Understanding Skill Directories
+  #
+  # AI coding agents typically support two types of skills:
+  #
+  # 1. *Project Skills* ({skills_dir}): These are specific to a single project and
+  #    live alongside the project code. For example, a project might have a
+  #    <tt>.cursor/skills</tt> directory containing skills tailored to that project.
+  #
+  # 2. *Global Skills* ({global_skills_dir}): These are shared across all projects
+  #    and typically live in the user's home directory. For example,
+  #    <tt>~/.cursor/skills</tt> contains reusable skills that work with any project.
+  #
+  # When working with skills, you typically:
+  #
+  # * Check the project's +skills_dir+ for project-specific skills
+  # * Fall back to +global_skills_dir+ for general-purpose skills
+  # * Combine both sources to give the agent full access to available skills
+  #
+  # == Accessing Agent Information
+  #
+  # Since Agent is a Data object, all attributes are accessible via reader methods:
+  #
+  #   agent = AgentSkillsConfigurations.find("cursor")
+  #   agent.name              # => "cursor"
+  #   agent.display_name      # => "Cursor"
+  #   agent.skills_dir        # => ".cursor/skills"
+  #   agent.global_skills_dir # => "/Users/username/.cursor/skills"
+  #
+  # You can also convert to a Hash:
+  #
+  #   agent.to_h
+  #   # => { name: "cursor",
+  #   #      display_name: "Cursor",
+  #   #      skills_dir: ".cursor/skills",
+  #   #      global_skills_dir: "/Users/username/.cursor/skills" }
+  #
+  # @attr_reader [String] name Canonical agent name from `agents.yml`. This is the
+  #   identifier used when finding agents via {AgentSkillsConfigurations.find}.
+  #
+  # @attr_reader [String] display_name Human-friendly label for UI/display purposes.
+  #   This is the name shown to users, e.g., in menus or configuration interfaces.
+  #
+  # @attr_reader [String] skills_dir Relative directory where project-specific
+  #   skills live. This path is relative to the project root and should not start
+  #   with a slash (e.g., ".cursor/skills", not "/.cursor/skills").
+  #
+  # @attr_reader [String] global_skills_dir Absolute resolved path to global skills.
+  #   This path is resolved from the YAML configuration, taking into account
+  #   environment variables and fallbacks. It always begins with a slash.
+  #
+  # @see AgentSkillsConfigurations.find Find an agent by name
+  # @see AgentSkillsConfigurations.all Get all agents
+  # @see AgentSkillsConfigurations.detected Get detected agents
+  Agent = Data.define(:name, :display_name, :skills_dir, :global_skills_dir)
+end