ask-skills 0.3.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 944cddd3dbc0de89913d1deb45668542f189e154bf3d40cc00468184689aeb38
-  data.tar.gz: a200f4181fa77aabc25dc6e1d0e2454d450159e5c64fa0cf7acf698910b8269b
+  metadata.gz: c3467a3de9f58a23327ca0624d3440f6eed9983bb4d8f834db30725d16eea52a
+  data.tar.gz: 4cd313ba7ef8419fe9683ea7f7d4d6ce88a0270082e1b7f7d2d74092b320bb86
 SHA512:
-  metadata.gz: bf049da94d308df2c5bb89164adc488abcc625ef65db0e2e14d73b981c03c9a0fe5d8dcf53b7f4037c437c1d3464a6515edf170ad439e28bf2f2afcf0fc7abb7
-  data.tar.gz: '03947665d57b76371ce167641b2b98a7d6e8f0587cc2af11c134a282906322c1f72cc4b7d45972c19738189d50eb45fc23cccffbbf1341a6c14dd663f26e0eff'
+  metadata.gz: 101a0a858c1ee4e0f414dfb2964984096094c397e8e14014181875c95dea3b67ed7c3e3ddec201da831e5f0aaa973176e69be71ac6b563278eecad8b5761d88e
+  data.tar.gz: ab7c5ec0eaa6c1887076a3b5314c5e83f5ef6eee1a411bc1de7371ef1c3b2b01d0636f483fa6a850b09ebc7c0d5e64099458747b0891a6d9b9dc3258960968a6

data/CHANGELOG.md

@@ -1,3 +1,53 @@
+## [0.4.0] - 2026-07-21
+
+### Added
+
+- **Enhanced frontmatter** — skill metadata now supports `tags`, `version`, `author`, and any custom fields alongside `name` and `description`. Frontmatter parser handles multi-line values and preserves all metadata in `skill.metadata`.
+
+  ```markdown
+  ---
+  name: rails_debug
+  description: Debug Rails database issues
+  tags: rails, database, debugging
+  version: 2
+  ---
+  ```
+
+- **Sibling files in skills** — skills now discover sibling files and directories in the skill directory alongside `SKILL.md`. Recognized categories are discovered automatically: `references/`, `scripts/`, `assets/`. Unrecognized directories and flat files are also collected.
+
+  ```
+  rails_debug/
+  ├── SKILL.md           → instructions
+  ├── references/
+  │   ├── migration_guide.md
+  │   └── apis.md
+  └── scripts/
+      └── db_check.sh
+  ```
+
+  Accessible at runtime via `skill.references`, `skill.scripts`, `skill.assets`, and `skill.siblings`.
+
+- **XML formatter** now includes `<tags>` and `<siblings>` sections when present. Markdown prompt entries show tags inline (`[rails, database]`).
+
+- **`askr skills` CLI commands** — new `askr` subcommands for managing skills:
+
+  ```bash
+  askr skills list              # All skills with descriptions and tags
+  askr skills show rails_debug  # Full details + instructions + siblings
+  askr skills search deploy     # Filter by name, description, or tags
+  ```
+
+### Changed
+
+- `Skill` data object now includes `metadata` (Hash) and `siblings` (Hash) fields with default empty values. Backward compatible — existing `Skill.new(...)` calls without these fields get empty defaults.
+- `Source::Filesystem#parse_frontmatter` rewritten to support multi-line values and arbitrary metadata keys (not just `name`/`description`).
+- `Ask::Skills.parse_frontmatter` updated to match, with new `process_metadata_value` helper.
+
+### Tested
+
+- 18 new tests for: tags parsing, metadata preservation, sibling discovery (references, scripts, assets, flat files), hidden file filtering, empty sibling handling, formatter output with tags/siblings, and CLI commands.
+- Full suite: 97 tests, 265 assertions — 0 failures.
+
 ## [0.3.0] - 2026-07-21
 
 ### Added

data/lib/ask/skills/formatter.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Ask
   module Skills
     class Formatter
@@ -10,7 +12,11 @@ module Ask
 
         lines = ["", "## Available Skills", ""]
         @skills.each_value do |skill|
-          lines << skill.to_prompt_entry
+          line = skill.to_prompt_entry
+          if skill.tags.any?
+            line += " [#{skill.tags.join(", ")}]"
+          end
+          lines << line
         end
         lines << ""
         lines << "When a task matches a skill's description, load it for step-by-step methodology."
@@ -26,6 +32,18 @@ module Ask
           lines << "  <skill>"
           lines << "    <name>#{escape_xml(skill.name)}</name>"
           lines << "    <description>#{escape_xml(skill.description)}</description>"
+          if skill.tags.any?
+            lines << "    <tags>#{escape_xml(skill.tags.join(", "))}</tags>"
+          end
+          if skill.siblings.any?
+            lines << "    <siblings>"
+            skill.siblings.each do |category, files|
+              lines << "      <#{category}>"
+              files.each { |f| lines << "        <file>#{escape_xml(f)}</file>" }
+              lines << "      </#{category}>"
+            end
+            lines << "    </siblings>"
+          end
           lines << "  </skill>"
         end
         lines << "</available_skills>"

data/lib/ask/skills/registry.rb

@@ -19,12 +19,14 @@ module Ask
 
       def format_for_prompt
         return "" if @skills.empty?
-        lines = ["", "## Available Skills", ""]
-        @skills.each_value do |skill|
-          lines << skill.to_prompt_entry
-        end
-        lines << ""
-        lines.join("\n")
+        Formatter.new(@skills).to_prompt_section
+      end
+
+      # Full instructions for skills with +always: true+ in their frontmatter.
+      # These skills are auto-injected into the system prompt rather than
+      # being listed for the LLM to load on demand.
+      def always_active_skills
+        @skills.values.select { |s| s.metadata["always"] == "true" || s.metadata["always"] == true }
       end
 
       private
@@ -33,8 +35,13 @@ module Ask
         @sources.each do |source|
           source.load.each do |skill|
             next unless skill
-            # First source wins (project overrides gems, user overrides project)
-            @skills[skill.name] ||= skill
+            if @skills.key?(skill.name)
+              # First-wins collision: log diagnostic but keep first
+              warn "[ask-skills] Collision: skill '#{skill.name}' already loaded from " \
+                   "#{@skills[skill.name].source}, skipping #{skill.source}"
+            else
+              @skills[skill.name] = skill
+            end
           end
         end
       end

data/lib/ask/skills/skill.rb

@@ -1,12 +1,58 @@
+# frozen_string_literal: true
+
 module Ask
   module Skills
-    Skill = Data.define(:name, :description, :instructions, :source) do
+    # A discovered skill with its metadata, instructions, and sibling files.
+    #
+    # Skills live in directories following the SKILL.md convention:
+    #
+    #   rails_debug/
+    #   ├── SKILL.md          → name, description, tags, instructions
+    #   ├── references/       → reference documents (loaded on demand)
+    #   ├── scripts/          → executable helpers
+    #   └── assets/           → images, templates, other resources
+    #
+    # The +siblings+ hash maps category names to arrays of file paths,
+    # relative to the skill's directory. Categories are inferred from
+    # sibling directory names (references, scripts, assets) or files.
+    Skill = Data.define(:name, :description, :instructions, :source, :metadata, :siblings) do
+      def initialize(name:, description:, instructions:, source:, metadata: {}, siblings: {})
+        super(name: name, description: description, instructions: instructions,
+              source: source, metadata: metadata, siblings: siblings)
+      end
+
       def to_s
         "#{name}: #{description}"
       end
 
       def to_prompt_entry
-        "- **#{name}**: #{description}"
+        line = "- **#{name}**: #{description}"
+        line
+      end
+
+      # Reference documents bundled with this skill.
+      # @return [Array<String>] file paths relative to skill directory
+      def references
+        siblings["references"] || []
+      end
+
+      # Executable scripts bundled with this skill.
+      # @return [Array<String>] file paths relative to skill directory
+      def scripts
+        siblings["scripts"] || []
+      end
+
+      # Asset files bundled with this skill.
+      # @return [Array<String>] file paths relative to skill directory
+      def assets
+        siblings["assets"] || []
+      end
+
+      # Comma-separated tags from frontmatter.
+      # @return [Array<String>]
+      def tags
+        raw = metadata["tags"] || metadata[:tags] || ""
+        raw.split(",").map(&:strip).reject(&:empty?)
       end
     end
   end

data/lib/ask/skills/sources/filesystem.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Ask
   module Skills
     module Source
@@ -35,25 +37,90 @@ module Ask
 
           return nil if description.empty?
 
-          Skill.new(name: name, description: description, instructions: body, source: path)
+          # Separate known metadata from reserved fields
+          reserved = %w[name description]
+          metadata = frontmatter.reject { |k, _| reserved.include?(k) }
+
+          # Discover sibling files
+          skill_dir = File.dirname(path)
+          siblings = discover_siblings(skill_dir)
+
+          Skill.new(
+            name: name,
+            description: description,
+            instructions: body,
+            source: path,
+            metadata: metadata,
+            siblings: siblings
+          )
+        end
+
+        # Scan the skill directory for sibling files and categorize them.
+        def discover_siblings(skill_dir)
+          siblings = {}
+          return siblings unless File.directory?(skill_dir)
+
+          Dir.entries(skill_dir).each do |entry|
+            next if entry.start_with?(".")
+            next if entry == "SKILL.md"
+            entry_path = File.join(skill_dir, entry)
+
+            if File.directory?(entry_path)
+              # Categorized sibling directories
+              category = entry
+              files = Dir.children(entry_path)
+                        .reject { |f| f.start_with?(".") }
+                        .map { |f| File.join(entry, f) }
+              siblings[category] = files if files.any?
+            else
+              # Individual files go into a general "files" category
+              siblings["files"] ||= []
+              siblings["files"] << entry
+            end
+          end
+
+          siblings
         end
 
         def parse_frontmatter(content)
           return {} unless content.start_with?("---\n")
           end_idx = content.index("\n---\n", 4)
           return {} unless end_idx
+
           yaml_str = content[4...end_idx]
           yaml = {}
+          current_key = nil
+          current_value = nil
+
           yaml_str.split("\n").each do |line|
-            if (m = line.match(/\A(\w+):\s*(.+)\z/))
-              value = m[2].strip
-              value = value.gsub(/\A"|"\z/, "").gsub(/\A'|'\z/, "")
-              yaml[m[1]] = value
+            if (m = line.match(/\A(\w[\w_]*):\s*(.*)\z/))
+              # Store previous key if any
+              if current_key
+                yaml[current_key] = process_value(current_value.strip)
+              end
+              current_key = m[1]
+              current_value = m[2].strip
+            elsif current_key && line.match?(/\A\s+/)
+              # Continuation of multi-line value (e.g. tags on next line)
+              current_value << " #{line.strip}"
             end
           end
+
+          # Store last key
+          if current_key
+            yaml[current_key] = process_value(current_value.strip)
+          end
+
           yaml
         end
 
+        def process_value(value)
+          return value unless value
+          # Remove surrounding quotes
+          value = value.gsub(/\A"|"\z/, "").gsub(/\A'|'\z/, "")
+          value
+        end
+
         def extract_body(content)
           return content unless content.start_with?("---\n")
           end_idx = content.index("\n---\n", 4)

data/lib/ask/skills/version.rb

@@ -1,5 +1,5 @@
 module Ask
   module Skills
-    VERSION = "0.3.0"
+    VERSION = "0.4.1"
   end
 end

data/lib/ask/skills.rb

@@ -61,18 +61,36 @@ module Ask
         return {} unless content.start_with?("---\n")
         end_idx = content.index("\n---\n", 4)
         return {} unless end_idx
+
         yaml_str = content[4...end_idx]
         yaml = {}
+        current_key = nil
+        current_value = nil
+
         yaml_str.split("\n").each do |line|
-          if (m = line.match(/\A(\w+):\s*(.+)\z/))
-            value = m[2].strip
-            value = value.gsub(/\A"|"\z/, "").gsub(/\A'|'\z/, "")
-            yaml[m[1]] = value
+          if (m = line.match(/\A(\w[\w_]*):\s*(.*)\z/))
+            if current_key
+              yaml[current_key] = process_metadata_value(current_value.strip)
+            end
+            current_key = m[1]
+            current_value = m[2].strip
+          elsif current_key && line.match?(/\A\s+/)
+            current_value << " #{line.strip}"
           end
         end
+
+        if current_key
+          yaml[current_key] = process_metadata_value(current_value.strip)
+        end
+
         yaml
       end
 
+      def process_metadata_value(value)
+        return value unless value
+        value.gsub(/\A"|"\z/, "").gsub(/\A'|'\z/, "")
+      end
+
       # Extract the markdown body from a file with frontmatter.
       def extract_body(content)
         return content unless content.start_with?("---\n")

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-skills
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.1
 platform: ruby
 authors:
 - Kaka Ruto