legion-llm 0.6.31 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0a2032854701a258fc788e3b3ef4cd495a2f031765c29775ed1486dd5eb8f35f
-  data.tar.gz: 62cd0ed1943b0730be9adb30c6c1b77308f10f9e223cfaea47f13d90b9794b6c
+  metadata.gz: c9434ffcb40fb1c04975e72914ee52527be3cd88241ed9f173177abd67386e69
+  data.tar.gz: 1c56c1f6fb21f441d976f4cfc9012023c65f296693f2c18dde54b7dbe89e7f14
 SHA512:
-  metadata.gz: 5e7a3f1e28c2af1d5cc3489a4bbe2592e7e019511920ad0c7c82943a0f444f36500d9707f6cda52f342a9af79922178bb5df249b1f53b477b52a9920ed856e9d
-  data.tar.gz: 69d8dc01c5c43a4fa7acfde15e81986e757670127fae2140b22ca77c4d8938ff0d1fa91a61d4c6664269ae147b26416c066ef57ab4fecbc86b605d8541c047c2
+  metadata.gz: 1a2099e39f14bd3750728a6c3015b6cce4a84ea22beca9383ebe9455e5eb1452c0afc52ea380a90650e975a0b8cbe7f405e1a523dad902511eb1854be28f450b
+  data.tar.gz: b127e711a671a3f11ee40f7f854dc264a99d636be24b5f6ee7d46e943788247e669a65e1a6792745e91f4927c879e069e4e929b13f0ace4d30ab714b1beac792

data/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 ## [Unreleased]
 
+## [0.7.0] - 2026-04-12
+
+### Added
+- `Legion::LLM::Skills` subsystem — first-class daemon-side skill execution
+- `Legion::LLM::Skills::Base` — DSL base class with `skill_name`, `namespace`, `description`, `trigger_words`, `trigger`, `steps`, `follows`, `file_change_triggers`, `content` DSL
+- `Legion::LLM::Skills::Registry` — thread-safe registry with `register`, `find`, `all`, `by_trigger`, `chain_for`, `reset!`, trigger word index, file trigger index, and cycle detection
+- `Legion::LLM::Skills::StepResult` — result struct from individual skill steps (`inject:`, `gate:`, `metadata:`)
+- `Legion::LLM::Skills::SkillRunResult` — aggregated result struct from a full skill run (`complete:`, `gated:`, `inject:`, `gate:`, `resume_at:`)
+- `Legion::LLM::Skills::InvalidSkill` and `Legion::LLM::Skills::StepError` — typed skill validation and execution errors
+- `Legion::LLM::Pipeline::Steps::SkillInjector` — pipeline step (step 10.5) that matches trigger words and file change patterns, activates matching skills, and injects results as `skill:active` enrichment
+- `Legion::LLM::ConversationStore` skill state methods: `set_skill_state`, `skill_state`, `clear_skill_state` for resumable multi-turn skills
+- `Legion::LLM::Audit::SkillEvent` — audit event for skill invocations
+
 ## [0.6.31] - 2026-04-10
 
 ### Fixed

data/lib/legion/llm/audit/skill_event.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative '../transport/message'
+
+module Legion
+  module LLM
+    module Audit
+      class SkillEvent < Legion::LLM::Transport::Message
+        def type        = 'llm.audit.skill'
+        def exchange    = Legion::LLM::Transport::Exchanges::Audit
+        def routing_key = "audit.skill.#{@options[:namespace]}.#{@options[:skill_name]}"
+        def priority    = 0
+        def encrypt?    = true
+        def expiration  = nil
+
+        def headers
+          super.merge(skill_headers).merge(classification_headers)
+        end
+
+        private
+
+        def message_id_prefix = 'audit_skill'
+
+        def skill_headers
+          h = {}
+          h['x-legion-skill-name']      = @options[:skill_name].to_s if @options[:skill_name]
+          h['x-legion-skill-namespace'] = @options[:namespace].to_s  if @options[:namespace]
+          h['x-legion-skill-step']      = @options[:step_name].to_s  if @options[:step_name]
+          h['x-legion-skill-gate']      = @options[:gate].to_s       if @options[:gate]
+          h['x-legion-skill-status']    = @options[:status].to_s     if @options[:status]
+          h
+        end
+
+        def classification_headers
+          cls = @options[:classification] || {}
+          h = {}
+          h['x-legion-classification'] = cls[:level].to_s        if cls[:level]
+          h['x-legion-contains-phi']   = cls[:contains_phi].to_s unless cls[:contains_phi].nil?
+          h
+        end
+      end
+    end
+  end
+end

data/lib/legion/llm/audit.rb

@@ -6,6 +6,7 @@ if defined?(Legion::Transport::Message)
   require_relative 'audit/exchange'
   require_relative 'audit/prompt_event'
   require_relative 'audit/tool_event'
+  require_relative 'audit/skill_event'
 end
 
 module Legion
@@ -43,6 +44,20 @@ module Legion
         :dropped
       end
 
+      def emit_skill(**event)
+        if transport_connected? && defined?(Legion::LLM::Audit::SkillEvent)
+          Legion::LLM::Audit::SkillEvent.new(**event).publish
+          log.info('[llm][audit] published skill audit')
+          :published
+        else
+          log.warn('[llm][audit] dropped skill audit: transport unavailable')
+          :dropped
+        end
+      rescue StandardError => e
+        handle_exception(e, level: :warn, operation: 'llm.audit.emit_skill')
+        :dropped
+      end
+
       def transport_connected?
         !!(defined?(Legion::Transport) &&
           Legion::Transport.respond_to?(:connected?) &&

data/lib/legion/llm/conversation_store.rb

@@ -147,6 +147,53 @@ module Legion
           @lru_counter   = 0
         end
 
+        def set_skill_state(conversation_id, skill_key:, resume_at:)
+          ensure_conversation(conversation_id)
+          conversations[conversation_id][:skill_state] = { skill_key: skill_key, resume_at: resume_at }
+          touch(conversation_id)
+        end
+
+        def skill_state(conversation_id)
+          return nil unless in_memory?(conversation_id)
+
+          touch(conversation_id)
+          conversations[conversation_id][:skill_state]&.dup
+        end
+
+        def clear_skill_state(conversation_id)
+          return unless in_memory?(conversation_id)
+
+          conversations[conversation_id].delete(:skill_state)
+          touch(conversation_id)
+        end
+
+        # Reads current state, clears :skill_state, sets :skill_cancelled flag.
+        # Returns the previous state (for use in skill.cancelled payload), or nil if none.
+        def cancel_skill!(conversation_id)
+          ensure_conversation(conversation_id)
+          state = conversations[conversation_id].delete(:skill_state)
+          if state
+            conversations[conversation_id][:skill_cancelled] = true
+            touch(conversation_id)
+          end
+          state
+        end
+
+        # :skill_cancelled is distinct from a nil :skill_state.
+        # nil skill_state also occurs after normal completion — use this flag to detect cancel.
+        def skill_cancelled?(conversation_id)
+          return false unless in_memory?(conversation_id)
+
+          conversations[conversation_id][:skill_cancelled] == true
+        end
+
+        def clear_cancel_flag(conversation_id)
+          return unless in_memory?(conversation_id)
+
+          conversations[conversation_id].delete(:skill_cancelled)
+          touch(conversation_id)
+        end
+
         # Migrate existing sequential messages to use parent links.
         # Safe to call on already-migrated data (no-op when parent links present).
         def migrate_parent_links!(conversation_id)

data/lib/legion/llm/pipeline/enrichment_injector.rb

@@ -24,6 +24,11 @@ module Legion
             parts << "Relevant context:\n#{context_text}" unless context_text.empty?
           end
 
+          # Skill injection — active skill's step output appended after the RAG context
+          if (skill = enrichments['skill:active'])
+            parts << skill
+          end
+
           return system if parts.empty?
 
           parts << system if system

data/lib/legion/llm/pipeline/executor.rb

@@ -20,6 +20,7 @@ module Legion
         attr_accessor :tool_event_handler
 
         include Steps::TriggerMatch
+        include Steps::SkillInjector
         include Steps::ToolDiscovery
         include Steps::ToolCalls
         include Steps::KnowledgeCapture
@@ -30,14 +31,14 @@ module Legion
 
         STEPS = %i[
           tracing_init idempotency conversation_uuid context_load
-          rbac classification billing gaia_advisory tier_assignment rag_context trigger_match tool_discovery
+          rbac classification billing gaia_advisory tier_assignment rag_context trigger_match skill_injector tool_discovery
           routing request_normalization token_budget provider_call response_normalization
           debate confidence_scoring tool_calls context_store post_response knowledge_capture response_return
         ].freeze
 
         PRE_PROVIDER_STEPS = %i[
           tracing_init idempotency conversation_uuid context_load
-          rbac classification billing gaia_advisory tier_assignment rag_context trigger_match tool_discovery
+          rbac classification billing gaia_advisory tier_assignment rag_context trigger_match skill_injector tool_discovery
           routing request_normalization token_budget
         ].freeze
 

data/lib/legion/llm/pipeline/steps/skill_injector.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+require 'legion/logging/helper'
+
+module Legion
+  module LLM
+    module Pipeline
+      module Steps
+        module SkillInjector
+          include Legion::Logging::Helper
+
+          def step_skill_injector
+            return unless skills_enabled?
+
+            conv_id = @request.conversation_id
+            return unless conv_id
+
+            if (state = ConversationStore.skill_state(conv_id))
+              resume_active_skill(conv_id, state)
+              return
+            end
+
+            @skill_executed = false
+
+            check_trigger_words(conv_id)
+            return if @skill_executed
+
+            check_file_change_triggers(conv_id)
+            return if @skill_executed
+
+            check_auto_skills(conv_id)
+          rescue StandardError => e
+            @warnings << "SkillInjector error: #{e.message}"
+            handle_exception(e, level: :warn, operation: 'llm.pipeline.steps.skill_injector')
+          end
+
+          private
+
+          def skills_enabled?
+            defined?(Legion::LLM::Skills::Registry) &&
+              defined?(Legion::LLM) &&
+              Legion::LLM.respond_to?(:settings) &&
+              Legion::LLM.settings.dig(:skills, :enabled) != false
+          end
+
+          def resume_active_skill(conv_id, state)
+            skill_class = Legion::LLM::Skills::Registry.find(state[:skill_key])
+            unless skill_class
+              ConversationStore.clear_skill_state(conv_id)
+              return
+            end
+
+            result = skill_class.new.run(from_step: state[:resume_at],
+                                         context:   build_skill_context(conv_id))
+            inject_skill_result(result)
+          end
+
+          def check_trigger_words(conv_id)
+            return if at_max_active_skills?(conv_id)
+
+            text  = extract_message_text
+            words = text.downcase.gsub(/[^a-z ]/, ' ').split.to_set
+            return if words.empty?
+
+            index = Legion::LLM::Skills::Registry.trigger_word_index
+            matched_keys = words.flat_map { |w| index[w] || [] }.uniq
+            return if matched_keys.empty?
+
+            matched_keys.each do |key|
+              skill_class = Legion::LLM::Skills::Registry.find(key)
+              next unless skill_class
+              next if skill_disabled?(key)
+
+              activate_skill(conv_id, skill_class)
+              break
+            end
+          end
+
+          def check_file_change_triggers(conv_id)
+            return if at_max_active_skills?(conv_id)
+
+            changed = Array(@request.metadata&.dig(:changed_files) || [])
+            return if changed.empty?
+
+            Legion::LLM::Skills::Registry.file_trigger_skills.each do |skill_class|
+              key = "#{skill_class.namespace}:#{skill_class.skill_name}"
+              next if skill_disabled?(key)
+
+              matched = changed.any? do |path|
+                skill_class.file_change_trigger_patterns.any? do |pat|
+                  ::File.fnmatch(pat, path, ::File::FNM_DOTMATCH)
+                end
+              end
+              next unless matched
+
+              activate_skill(conv_id, skill_class)
+              break
+            end
+          end
+
+          def check_auto_skills(conv_id)
+            return if at_max_active_skills?(conv_id)
+            return if Legion::LLM.settings.dig(:skills, :auto_inject) == false
+
+            Legion::LLM::Skills::Registry.by_trigger(:auto).each do |skill_class|
+              key = "#{skill_class.namespace}:#{skill_class.skill_name}"
+              next if skill_disabled?(key)
+              next unless when_conditions_match?(skill_class)
+
+              activate_skill(conv_id, skill_class)
+              break
+            end
+          end
+
+          def activate_skill(conv_id, skill_class)
+            result = skill_class.new.run(from_step: 0, context: build_skill_context(conv_id))
+            @skill_executed = true
+            inject_skill_result(result)
+          end
+
+          def inject_skill_result(result)
+            return unless result.inject && !result.inject.empty?
+
+            @enrichments['skill:active'] = result.inject
+          end
+
+          def when_conditions_match?(skill_class)
+            return true if skill_class.when_conditions.empty?
+
+            skill_class.when_conditions.all? do |key, expected|
+              unless @request.respond_to?(key)
+                log.warn("[skill_injector] unknown condition key #{key.inspect}, non-matching")
+                next false
+              end
+
+              deep_subset_match?(@request.public_send(key), expected)
+            end
+          end
+
+          def deep_subset_match?(actual, expected)
+            return actual == expected unless expected.is_a?(Hash)
+
+            expected.all? do |k, v|
+              actual.is_a?(Hash) && actual.key?(k) && deep_subset_match?(actual[k], v)
+            end
+          end
+
+          def at_max_active_skills?(conv_id)
+            max    = Legion::LLM.settings.dig(:skills, :max_active_skills) || 1
+            active = ConversationStore.skill_state(conv_id) ? 1 : 0
+            active >= max
+          end
+
+          def skill_disabled?(key)
+            disabled = Array(Legion::LLM.settings.dig(:skills, :disabled_skills) || [])
+            enabled  = Array(Legion::LLM.settings.dig(:skills, :enabled_skills)  || [])
+            return true if disabled.include?(key)
+            return false if enabled.empty?
+
+            !enabled.include?(key)
+          end
+
+          def extract_message_text
+            @request.messages.last(2).map do |msg|
+              msg.is_a?(Hash) ? (msg[:content] || msg['content'] || '').to_s : msg.to_s
+            end.join(' ')
+          end
+
+          def build_skill_context(conv_id)
+            {
+              conversation_id: conv_id,
+              classification:  @request.classification,
+              metadata:        @request.metadata,
+              intent:          @request.extra&.dig(:intent)
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/llm/pipeline/steps.rb

@@ -19,6 +19,7 @@ require_relative 'steps/tier_assigner'
 require_relative 'steps/post_response'
 require_relative 'steps/tool_discovery'
 require_relative 'steps/trigger_match'
+require_relative 'steps/skill_injector'
 require_relative 'steps/tool_calls'
 require_relative 'steps/rag_context'
 require_relative 'steps/rag_guard'

data/lib/legion/llm/skills/base.rb

@@ -0,0 +1,271 @@
+# frozen_string_literal: true
+
+require_relative 'step_result'
+require_relative 'skill_run_result'
+require_relative 'errors'
+
+module Legion
+  module LLM
+    module Skills
+      class Base
+        class << self
+          def skill_name(name = nil)
+            name ? (@skill_name = name.to_s) : @skill_name
+          end
+
+          def description(text = nil)
+            text ? (@description = text) : @description
+          end
+
+          def trigger(type = nil)
+            type ? (@trigger = type) : (@trigger || :on_demand)
+          end
+
+          def namespace(nsp = nil)
+            nsp ? (@namespace = nsp.to_s) : @namespace
+          end
+
+          def steps(*names)
+            if names.any?
+              @steps = names
+              validate_steps!
+            else
+              @steps || []
+            end
+          end
+
+          def trigger_words(*words)
+            words.any? ? (@trigger_words_list = words.map(&:to_s)) : (@trigger_words_list || [])
+          end
+
+          def file_change_triggers(*patterns)
+            patterns.any? ? (@file_change_trigger_patterns = patterns.map(&:to_s)) : (@file_change_trigger_patterns || [])
+          end
+
+          def file_change_trigger_patterns
+            @file_change_trigger_patterns || []
+          end
+
+          def follows(skill_key = nil)
+            skill_key ? (@follows_skill = skill_key.to_s) : @follows_skill
+          end
+
+          attr_reader :follows_skill
+
+          # `condition` is used instead of `when` because `when` is a Ruby reserved keyword.
+          # DSL: `condition classification: { level: 'internal' }`
+          def condition(**conds)
+            @when_conditions = conds
+          end
+
+          def when_conditions
+            @when_conditions || {}
+          end
+
+          def content(context: {}) # rubocop:disable Lint/UnusedMethodArgument
+            path = content_path
+            return ::File.read(path) if path && ::File.exist?(path)
+
+            generate_content_from_step_names
+          end
+
+          private
+
+          def validate_steps!
+            missing = @steps.reject { |name| method_defined?(name) || private_method_defined?(name) }
+            return if missing.empty?
+
+            raise InvalidSkill, "#{self}: missing step methods: #{missing.join(', ')}"
+          end
+
+          def content_path
+            return nil unless @skill_name
+
+            # Derive gem name: Legion::Extensions::SkillSuperpowers -> lex-skill-superpowers
+            parts = name.to_s.split('::').drop(2)
+            return nil if parts.empty?
+
+            gem_name = parts.first.gsub(/([A-Z])/) { "-#{::Regexp.last_match(1).downcase}" }.sub(/^-/, 'lex-')
+            spec = begin
+              ::Gem::Specification.find_by_name(gem_name)
+            rescue ::Gem::MissingSpecError
+              nil
+            end
+            return nil unless spec
+
+            ::File.join(spec.gem_dir, 'content', @skill_name, 'SKILL.md')
+          end
+
+          def generate_content_from_step_names
+            lines = ["# #{@skill_name} — #{@skill_name.to_s.tr('-', ' ').capitalize}", '',
+                     @description.to_s, '', '## Steps', '']
+            (@steps || []).each_with_index { |n, i| lines << "#{i + 1}. #{n.to_s.tr('_', ' ').capitalize}" }
+            lines.join("\n")
+          end
+        end
+
+        def run(from_step: 0, context: {})
+          inject_parts   = []
+          total_duration = 0
+          classification = context[:classification]
+          conv_id        = context[:conversation_id]
+          self_key       = "#{self.class.namespace}:#{self.class.skill_name}"
+
+          emit_event(conv_id, 'skill.started',
+                     skill_name: self.class.skill_name, namespace: self.class.namespace,
+                     total_steps: self.class.steps.length)
+
+          remaining_steps = self.class.steps[from_step..] || []
+
+          remaining_steps.each_with_index do |method_name, offset|
+            step_idx = from_step + offset
+            if conv_id && Legion::LLM::ConversationStore.skill_cancelled?(conv_id)
+              Legion::LLM::ConversationStore.clear_cancel_flag(conv_id)
+              return SkillRunResult.build(inject: inject_parts.join("\n\n"),
+                                          gated: false, gate: nil, resume_at: nil, complete: false)
+            end
+
+            result, duration_ms = execute_step(method_name, step_idx, context, conv_id, classification)
+            total_duration += duration_ms
+            inject_parts << result.inject if result.inject
+
+            emit_step_success(conv_id, method_name, step_idx, duration_ms, result, classification)
+
+            next unless result.gate
+
+            if conv_id
+              Legion::LLM::ConversationStore.set_skill_state(
+                conv_id, skill_key: self_key, resume_at: step_idx + 1
+              )
+            end
+            emit_event(conv_id, 'skill.step.gated',
+                       step_name: method_name, gate_type: result.gate)
+            return SkillRunResult.build(
+              inject: inject_parts.join("\n\n"), gated: true,
+              gate: result.gate, resume_at: step_idx + 1, complete: false
+            )
+          end
+
+          finalize_run(conv_id, self_key, inject_parts, total_duration, context)
+        end
+
+        private
+
+        def execute_step(method_name, step_idx, context, conv_id, classification)
+          t0 = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
+          emit_event(conv_id, 'skill.step.started',
+                     step_name: method_name, step_index: step_idx)
+          Legion::LLM::Metering.emit(
+            request_type: 'skill.step.start', skill_name: self.class.skill_name,
+            namespace: self.class.namespace, step_name: method_name,
+            step_index: step_idx, tier: 'local'
+          )
+          result = public_send(method_name, context: context)
+          unless result.respond_to?(:inject) && result.respond_to?(:metadata) && result.respond_to?(:gate)
+            raise Legion::LLM::Skills::StepError.new(
+              "#{self.class.skill_name}##{method_name} returned #{result.class} instead of StepResult",
+              cause: nil
+            )
+          end
+
+          duration_ms = ((::Process.clock_gettime(::Process::CLOCK_MONOTONIC) - t0) * 1000).round
+          [result, duration_ms]
+        rescue StandardError => e
+          duration_ms = ((::Process.clock_gettime(::Process::CLOCK_MONOTONIC) - t0) * 1000).round
+          handle_step_error(e, method_name, step_idx, conv_id, duration_ms, classification)
+        end
+
+        def handle_step_error(err, method_name, step_idx, conv_id, duration_ms, classification)
+          Legion::LLM::ConversationStore.clear_skill_state(conv_id) if conv_id
+          emit_event(conv_id, 'skill.step.failed',
+                     step_name: method_name, error: err.message)
+          Legion::LLM::Audit.emit_skill(
+            skill_name: self.class.skill_name, namespace: self.class.namespace,
+            step_name: method_name, gate: nil, status: :failed,
+            duration_ms: duration_ms, metadata: { error: err.message },
+            classification: classification
+          )
+          Legion::LLM::Metering.emit(
+            request_type: 'skill.step', skill_name: self.class.skill_name,
+            namespace: self.class.namespace, step_name: method_name,
+            step_index: step_idx, duration_ms: duration_ms, gate: nil, tier: 'local'
+          )
+          raise Legion::LLM::Skills::StepError.new(
+            "#{self.class.skill_name}##{method_name} failed: #{err.message}", cause: err
+          )
+        end
+
+        def emit_step_success(conv_id, method_name, step_idx, duration_ms, result, classification)
+          emit_event(conv_id, 'skill.step.completed',
+                     step_name: method_name, duration_ms: duration_ms,
+                     metadata: result.metadata)
+          Legion::LLM::Audit.emit_skill(
+            skill_name: self.class.skill_name, namespace: self.class.namespace,
+            step_name: method_name, gate: result.gate,
+            status: :completed, duration_ms: duration_ms,
+            metadata: result.metadata, classification: classification
+          )
+          Legion::LLM::Metering.emit(
+            request_type: 'skill.step', skill_name: self.class.skill_name,
+            namespace: self.class.namespace, step_name: method_name,
+            step_index: step_idx, duration_ms: duration_ms,
+            gate: result.gate&.to_s, tier: 'local'
+          )
+        end
+
+        def finalize_run(conv_id, self_key, inject_parts, total_duration, context)
+          chain_next    = Legion::LLM::Skills::Registry.chain_for(self_key)
+          chained_class = chain_next ? Legion::LLM::Skills::Registry.find(chain_next) : nil
+          resolved_chain = chained_class ? chain_next : nil
+
+          Legion::LLM::ConversationStore.clear_skill_state(conv_id) if conv_id
+          emit_event(conv_id, 'skill.completed',
+                     skill_name: self.class.skill_name, namespace: self.class.namespace,
+                     total_duration_ms: total_duration, chained_to: resolved_chain)
+
+          return run_chained(chained_class, chain_next, conv_id, self_key, inject_parts, context) if chained_class
+
+          SkillRunResult.build(inject: inject_parts.join("\n\n"),
+                               gated: false, gate: nil, resume_at: nil, complete: true)
+        end
+
+        def run_chained(chained_class, chain_key, conv_id, self_key, inject_parts, context)
+          emit_event(conv_id, 'skill.chained',
+                     from_skill: self_key, to_skill: chain_key)
+          chained_result = chained_class.new.run(from_step: 0, context: context)
+          inject_parts << chained_result.inject if chained_result.inject
+          SkillRunResult.build(
+            inject:    inject_parts.join("\n\n"),
+            gated:     chained_result.gated,
+            gate:      chained_result.gate,
+            resume_at: chained_result.resume_at,
+            complete:  chained_result.complete
+          )
+        end
+
+        def emit_event(conv_id, event, **payload)
+          return unless conv_id
+
+          Legion::Events.emit(event, { conversation_id: conv_id }.merge(payload))
+        end
+
+        protected
+
+        def detect_project(context)
+          root = context[:project_root]
+          return 'unknown project' unless root
+
+          ::File.basename(root.to_s)
+        end
+
+        def conversation_id(context)
+          context[:conversation_id]
+        end
+
+        def current_intent(context)
+          context[:intent]
+        end
+      end
+    end
+  end
+end

data/lib/legion/llm/skills/disk_loader.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require 'legion/logging/helper'
+
+module Legion
+  module LLM
+    module Skills
+      module DiskLoader
+        extend Legion::Logging::Helper
+
+        module_function
+
+        def load_from_directories(directories)
+          loaded = 0
+          Array(directories).each do |dir|
+            expanded = ::File.expand_path(dir)
+            next unless ::File.directory?(expanded)
+
+            loaded += load_directory(expanded)
+          end
+          loaded
+        end
+
+        def load_directory(dir)
+          loaded = 0
+          ::Dir.glob(::File.join(dir, '*.rb')).each do |path|
+            require path
+            loaded += 1
+          rescue StandardError => e
+            log.warn("[skills][disk_loader] failed to load #{path}: #{e.message}")
+          end
+          ::Dir.glob(::File.join(dir, '*.md')).each do |path|
+            load_md_skill(path)
+            loaded += 1
+          rescue StandardError => e
+            log.warn("[skills][disk_loader] failed to load #{path}: #{e.message}")
+          end
+          ::Dir.glob(::File.join(dir, '*/SKILL.md')).each do |path|
+            load_md_skill(path, skill_name: ::File.basename(::File.dirname(path)))
+            loaded += 1
+          rescue StandardError => e
+            log.warn("[skills][disk_loader] failed to load #{path}: #{e.message}")
+          end
+          loaded
+        end
+
+        # Public for testing. Accepts an optional content: kwarg to avoid disk reads in specs.
+        def load_md_skill(path, skill_name: nil, content: nil)
+          raw = content || ::File.read(path)
+          meta, body = parse_frontmatter(raw)
+          name      = skill_name || meta[:name] || ::File.basename(path, '.md')
+          ns        = (meta[:namespace] || 'disk').to_s
+          desc      = (meta[:description] || '').to_s
+          trig      = (meta[:trigger] || 'on_demand').to_sym
+          words     = Array(meta[:trigger_words] || []).map(&:to_s)
+          klass     = build_md_skill_class(name: name, namespace: ns, description: desc,
+                                           trigger: trig, trigger_words: words, content: body)
+          Registry.register(klass)
+        end
+
+        def parse_frontmatter(text)
+          return [{}, text] unless text.start_with?('---')
+
+          parts = text.split(/^---\s*$/, 3)
+          return [{}, text] unless parts.size >= 3
+
+          require 'yaml'
+          meta = ::YAML.safe_load(parts[1], permitted_classes: [], symbolize_names: true) || {}
+          [meta, parts[2].lstrip]
+        rescue StandardError
+          [{}, text]
+        end
+
+        def build_md_skill_class(name:, namespace:, description:, trigger:, trigger_words:, content:)
+          raw_content = content
+          klass = Class.new(Legion::LLM::Skills::Base)
+          klass.send(:define_method, :present_content) do |context: {}| # rubocop:disable Lint/UnusedBlockArgument
+            Legion::LLM::Skills::StepResult.build(inject: raw_content)
+          end
+          klass.skill_name(name)
+          klass.namespace(namespace)
+          klass.description(description)
+          klass.trigger(trigger)
+          klass.trigger_words(*trigger_words) if trigger_words.any?
+          klass.steps(:present_content)
+          klass
+        end
+      end
+    end
+  end
+end

data/lib/legion/llm/skills/errors.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'legion/llm/errors'
+
+module Legion
+  module LLM
+    module Skills
+      class InvalidSkill < Legion::LLM::LLMError
+        def initialize(msg = 'Invalid skill definition')
+          super
+        end
+      end
+
+      class StepError < Legion::LLM::LLMError
+        attr_reader :cause
+
+        def initialize(msg, cause: nil)
+          super(msg)
+          @cause = cause
+        end
+      end
+    end
+  end
+end

data/lib/legion/llm/skills/external_discovery.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Legion
+  module LLM
+    module Skills
+      module ExternalDiscovery
+        module_function
+
+        def discover
+          dirs = []
+          dirs.concat(claude_directories) if claude_auto_discover?
+          dirs.concat(codex_directories)  if codex_auto_discover?
+          dirs
+        end
+
+        def claude_directories
+          home = ::File.expand_path('~')
+          dirs = []
+
+          skills_dir = ::File.join(home, '.claude', 'skills')
+          dirs << skills_dir if ::File.directory?(skills_dir)
+
+          plugins_dir = ::File.join(home, '.claude', 'plugins')
+          if ::File.directory?(plugins_dir)
+            ::Dir.glob(::File.join(plugins_dir, '*', 'skills')).each do |skill_subdir|
+              dirs << skill_subdir if ::File.directory?(skill_subdir)
+            end
+          end
+
+          dirs.uniq
+        end
+
+        def codex_directories
+          candidate = ::File.join(::File.expand_path('~'), '.codex', 'skills')
+          ::File.directory?(candidate) ? [candidate] : []
+        end
+
+        def claude_auto_discover?
+          Legion::LLM.settings.dig(:skills, :auto_discover, :claude) != false
+        rescue StandardError
+          true
+        end
+
+        def codex_auto_discover?
+          Legion::LLM.settings.dig(:skills, :auto_discover, :codex) != false
+        rescue StandardError
+          true
+        end
+      end
+    end
+  end
+end

data/lib/legion/llm/skills/registry.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require 'legion/logging/helper'
+
+module Legion
+  module LLM
+    module Skills
+      module Registry
+        extend Legion::Logging::Helper
+
+        MUTEX = Mutex.new
+
+        class << self
+          def register(skill_class)
+            MUTEX.synchronize do
+              validate!(skill_class)
+              key = registry_key(skill_class)
+              if (@by_key ||= {}).key?(key)
+                log.warn("[skills][registry] duplicate: #{key} replaced")
+                remove_from_indexes(@by_key[key], key)
+              end
+              @ordered ||= []
+              @ordered.reject! { |k| k == key }
+              @by_key[key] = skill_class
+              @ordered << key
+              index_trigger_words(key, skill_class)
+              index_file_triggers(skill_class)
+              index_chain(skill_class)
+            end
+          end
+
+          def all
+            MUTEX.synchronize { (@ordered || []).filter_map { |k| (@by_key || {})[k] } }
+          end
+
+          def find(key)
+            MUTEX.synchronize { (@by_key || {})[key] }
+          end
+
+          def by_trigger(type)
+            all.select { |c| c.trigger == type }
+          end
+
+          def chain_for(skill_key)
+            MUTEX.synchronize { (@chain_index || {})[skill_key] }
+          end
+
+          def trigger_word_index
+            MUTEX.synchronize do
+              (@trigger_word_index || {}).each_with_object({}) do |(word, keys), copy|
+                copy[word] = keys.dup
+              end
+            end
+          end
+
+          def file_trigger_skills
+            MUTEX.synchronize { (@file_trigger_skills || []).dup }
+          end
+
+          def reset!
+            MUTEX.synchronize do
+              @by_key              = {}
+              @ordered             = []
+              @chain_index         = {}
+              @trigger_word_index  = {}
+              @file_trigger_skills = []
+            end
+          end
+
+          private
+
+          def registry_key(skill_class)
+            "#{skill_class.namespace}:#{skill_class.skill_name}"
+          end
+
+          def validate!(skill_class)
+            raise InvalidSkill, "#{skill_class}: skill_name required" if skill_class.skill_name.nil?
+            raise InvalidSkill, "#{skill_class}: namespace required"  if skill_class.namespace.nil?
+
+            check_chain_cycle!(skill_class)
+          end
+
+          def check_chain_cycle!(skill_class)
+            return unless skill_class.follows_skill
+
+            self_key = registry_key(skill_class)
+            visited  = Set.new([self_key])
+            current  = skill_class.follows_skill
+            while current
+              raise InvalidSkill, "Cycle detected in skill chain involving #{self_key}" if visited.include?(current)
+
+              visited.add(current)
+              current = (@by_key || {})[current]&.follows_skill
+            end
+          end
+
+          def index_trigger_words(key, skill_class)
+            @trigger_word_index ||= {}
+            skill_class.trigger_words.each do |word|
+              @trigger_word_index[word] ||= []
+              @trigger_word_index[word] << key unless @trigger_word_index[word].include?(key)
+            end
+          end
+
+          def index_file_triggers(skill_class)
+            @file_trigger_skills ||= []
+            return if skill_class.file_change_trigger_patterns.empty?
+            return if @file_trigger_skills.include?(skill_class)
+
+            @file_trigger_skills << skill_class
+          end
+
+          def index_chain(skill_class)
+            @chain_index ||= {}
+            return unless skill_class.follows_skill
+
+            self_key = registry_key(skill_class)
+            @chain_index[skill_class.follows_skill] = self_key
+          end
+
+          def remove_from_indexes(old_class, key)
+            old_class.trigger_words.each { |w| @trigger_word_index&.[](w)&.delete(key) }
+            @file_trigger_skills&.delete(old_class)
+            @chain_index&.delete_if { |_parent, child_key| child_key == key }
+            @chain_index&.delete(old_class.follows_skill) if old_class.follows_skill
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/llm/skills/settings.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Legion
+  module LLM
+    module Skills
+      module Settings
+        DEFAULTS = {
+          enabled:           true,
+          auto_inject:       true,
+          on_demand:         true,
+          max_active_skills: 1,
+          directories:       ['.legion/skills', '~/.legionio/skills'],
+          auto_discover:     { claude: false, codex: false },
+          enabled_skills:    [],
+          disabled_skills:   []
+        }.freeze
+
+        module_function
+
+        def apply
+          return unless defined?(Legion::Settings)
+
+          llm_settings = (Legion::Settings[:llm] || {}).dup
+          current = llm_settings[:skills] || {}
+          merged  = deep_merge(DEFAULTS, current)
+          llm_settings[:skills] = merged
+          Legion::Settings[:llm] = llm_settings
+        end
+
+        def deep_merge(base, override)
+          result = base.dup
+          override.each do |key, val|
+            result[key] = val.is_a?(Hash) && result[key].is_a?(Hash) ? deep_merge(result[key], val) : val
+          end
+          result
+        end
+      end
+    end
+  end
+end

data/lib/legion/llm/skills/skill_run_result.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Legion
+  module LLM
+    module Skills
+      SkillRunResult = ::Data.define(:inject, :gated, :gate, :resume_at, :complete) do
+        def self.build(inject:, gated:, gate:, resume_at:, complete:)
+          new(inject: inject, gated: gated, gate: gate, resume_at: resume_at, complete: complete)
+        end
+      end
+    end
+  end
+end

data/lib/legion/llm/skills/step_result.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Legion
+  module LLM
+    module Skills
+      StepResult = ::Data.define(:inject, :gate, :metadata) do
+        def self.build(inject:, gate: nil, metadata: {})
+          new(inject: inject, gate: gate, metadata: metadata)
+        end
+      end
+    end
+  end
+end

data/lib/legion/llm/skills.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative 'skills/errors'
+require_relative 'skills/step_result'
+require_relative 'skills/skill_run_result'
+require_relative 'skills/registry'
+require_relative 'skills/settings'
+require_relative 'skills/base'
+require_relative 'skills/disk_loader'
+require_relative 'skills/external_discovery'
+
+module Legion
+  module LLM
+    module Skills
+      module_function
+
+      def start
+        Settings.apply
+        directories = settings_directories + ExternalDiscovery.discover
+        DiskLoader.load_from_directories(directories)
+      end
+
+      def settings_directories
+        Array(Legion::LLM.settings.dig(:skills, :directories) || [])
+      rescue StandardError
+        []
+      end
+    end
+  end
+end

data/lib/legion/llm/version.rb

@@ -2,6 +2,6 @@
 
 module Legion
   module LLM
-    VERSION = '0.6.31'
+    VERSION = '0.7.0'
   end
 end

data/lib/legion/llm.rb

@@ -38,6 +38,12 @@ require_relative 'llm/token_tracker'
 require_relative 'llm/override_confidence'
 require_relative 'llm/routes'
 
+begin
+  require_relative 'llm/skills'
+rescue LoadError => e
+  Legion::Logging.debug "LLM: skills not loadable: #{e.message}" if defined?(Legion::Logging)
+end
+
 module Legion
   module LLM
     class EscalationExhausted < StandardError; end
@@ -72,6 +78,9 @@ module Legion
         install_hooks
         load_tool_interceptors
 
+        # Skills startup — load after settings, before pipeline is used
+        Legion::LLM::Skills.start if defined?(Legion::LLM::Skills) && settings.dig(:skills, :enabled) != false
+
         @started = true
         Legion::Settings[:llm][:connected] = true
         log.info 'Legion::LLM started'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: legion-llm
 version: !ruby/object:Gem::Version
-  version: 0.6.31
+  version: 0.7.0
 platform: ruby
 authors:
 - Esity
@@ -227,6 +227,7 @@ files:
 - lib/legion/llm/audit.rb
 - lib/legion/llm/audit/exchange.rb
 - lib/legion/llm/audit/prompt_event.rb
+- lib/legion/llm/audit/skill_event.rb
 - lib/legion/llm/audit/tool_event.rb
 - lib/legion/llm/batch.rb
 - lib/legion/llm/bedrock_bearer_auth.rb
@@ -295,6 +296,7 @@ files:
 - lib/legion/llm/pipeline/steps/rag_context.rb
 - lib/legion/llm/pipeline/steps/rag_guard.rb
 - lib/legion/llm/pipeline/steps/rbac.rb
+- lib/legion/llm/pipeline/steps/skill_injector.rb
 - lib/legion/llm/pipeline/steps/span_annotator.rb
 - lib/legion/llm/pipeline/steps/tier_assigner.rb
 - lib/legion/llm/pipeline/steps/token_budget.rb
@@ -319,6 +321,15 @@ files:
 - lib/legion/llm/scheduling.rb
 - lib/legion/llm/settings.rb
 - lib/legion/llm/shadow_eval.rb
+- lib/legion/llm/skills.rb
+- lib/legion/llm/skills/base.rb
+- lib/legion/llm/skills/disk_loader.rb
+- lib/legion/llm/skills/errors.rb
+- lib/legion/llm/skills/external_discovery.rb
+- lib/legion/llm/skills/registry.rb
+- lib/legion/llm/skills/settings.rb
+- lib/legion/llm/skills/skill_run_result.rb
+- lib/legion/llm/skills/step_result.rb
 - lib/legion/llm/structured_output.rb
 - lib/legion/llm/token_tracker.rb
 - lib/legion/llm/tools/adapter.rb