ask-skills 0.2.2 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d8c568c09d6c6e27218b0d78855b3d56fa0c0127f72c84c66d9da2c15f79240b
-  data.tar.gz: 9ab57cf36d99a7e2cff8c9c1a93c11166f4b56387bd7fd1b2793580c9020dcf5
+  metadata.gz: 768239027d0fbaa9696f54f17dab21af118661b7d36c89969e2e8408ff75d8c0
+  data.tar.gz: 02ac858fc1be5fa4d9ffd93909cf828d8dafb6b9d134a4aac41ba8e3dfe46f38
 SHA512:
-  metadata.gz: 391db4fed6330dbfe3f57a6b5e8ae5c5a7c64546e1a99936c9c18c304a8ccdd18c9cdb24bed27a9e991297afc0209312ba75bab0b2c457ad8d88e8224226e454
-  data.tar.gz: 1a1e6cbc55db3f9cabb36bc5a5618b9cefa4f270e744a44a22ac7ef16a654f65f5ff73a70fa0a9c7a0bf9462a52bbaf57070ce1396ad60ea66172684059c307b
+  metadata.gz: a242038997b6697ce44fcea6372bcc7ce797dc1ce510e2a5d36216256efdaa34f41d095c2909851f0db8dc2fc12137e934d826fa0cc3eb2bbc8ec1f854161045
+  data.tar.gz: 478b061e75189527782cff6c567c37b2f629b5594e6839427536a87260fcc89cc383adc4e6db172338d33a8289d5a09b851788532aab3fd07fd8b531611786c4

data/CHANGELOG.md

@@ -1,3 +1,91 @@
+## [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
+
+- **New discovery paths** — skills are now discovered from `agents/shared/skills/` and `app/agents/shared/skills/` alongside the legacy `.agents/skills/`. These paths follow the existing `agents/` convention already established for agent definitions.
+
+  ```
+  agents/
+  ├── health_check/
+  ├── daily_report/
+  └── shared/
+      ├── tools/          ← shared tools
+      └── skills/         ← new: shared skills
+          └── rails_debug/SKILL.md
+  ```
+
+- **Per-agent skills** — `Ask::Skills.discover(agent_dir:)` discovers skills scoped to a specific agent directory. These have highest priority over shared, legacy, user, gem, and built-in skills.
+
+  ```
+  agents/health_check/
+  ├── agent.rb
+  ├── instructions.md
+  └── skills/             ← new: only available to health_check agent
+      └── nginx_debug/SKILL.md
+  ```
+
+- **ask-agent integration** — `Ask::Agent::Session` accepts `agent_dir:` parameter. When creating a session from an agent definition via `Ask::Agent.new("name")`, per-agent skills are auto-discovered and included. No configuration needed.
+
+### Changed
+
+- `Ask::Skills.discover` now accepts `agent_dir:` keyword. When provided, the source list starts with the per-agent skills directory (highest priority). Shared project skills from `agents/shared/skills/` and `app/agents/shared/skills/` are included in the default source list.
+- Backward compatible — legacy `.agents/skills/` continues to work.
+
+### Tested
+
+- 10 new integration tests: discovery from `agents/shared/skills/`, `app/agents/shared/skills/`, per-agent skills, priority ordering, backward compatibility with `.agents/skills/`, and source list verification.
+- Full suite: 79 tests, 217 assertions — 0 failures.
+
 ## [0.2.2] - 2026-06-25
 
 ### Changed

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/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,7 +1,11 @@
+# frozen_string_literal: true
+
 module Ask
   module Skills
     module Source
       class Filesystem < Base
+        SIBLING_CATEGORIES = %w[references scripts assets].freeze
+
         def initialize(dir: nil, project_dir: nil, user_dir: nil)
           @path = dir || project_dir || (user_dir ? File.expand_path(user_dir) : nil)
         end
@@ -35,25 +39,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.2.2"
+    VERSION = "0.4.0"
   end
 end

data/lib/ask/skills.rb

@@ -16,33 +16,29 @@ module Ask
     end
 
     class << self
-      def discover(sources: nil)
-        Registry.new(sources || default_sources)
+      # Discover skills from all configured sources.
+      #
+      # @param agent_dir [String, nil] optional agent directory to discover
+      #   per-agent skills from (e.g. "agents/health_check")
+      # @param sources [Array<Source::Base>, nil] custom source list
+      # @return [Registry]
+      def discover(sources: nil, agent_dir: nil)
+        all_sources = sources || build_source_list(agent_dir: agent_dir)
+        Registry.new(all_sources)
       end
 
+      # Default sources when no custom sources or agent directory given.
+      # Legacy `.agents/skills/` is kept for backward compatibility.
       def default_sources
-        [
-          # Highest priority first — first source wins in Registry
-          Source::Filesystem.new(project_dir: ".agents/skills"),
-          Source::Filesystem.new(user_dir: "~/.config/ask/skills"),
-          Source::Gems.new,
-          Source::Filesystem.new(dir: builtin_skills_dir),
-        ]
+        build_source_list
       end
 
+      # Built-in skills that ship with the gem.
       def builtin_skills_dir
-        # Skills live in lib/ask/skills/<skill_name>/SKILL.md
-        # __dir__ in this file (lib/ask/skills.rb) is lib/ask/
-        # The skill directories are in lib/ask/skills/
         File.join(__dir__, "skills")
       end
 
       # Load a skill from an arbitrary markdown file path.
-      # Parses frontmatter if present, otherwise uses the filename as the skill name.
-      #
-      # @param path [String] absolute or relative path to a markdown (.md) file
-      # @return [Skill] a skill with the file's content as instructions
-      # @raise [Errno::ENOENT] if the file does not exist
       def load_file(path)
         path = File.expand_path(path)
         content = File.read(path)
@@ -61,23 +57,40 @@ module Ask
       end
 
       # Simple frontmatter parsing for skill files.
-      # Returns a hash of key-value pairs from between --- markers.
       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/))
+            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")
@@ -86,6 +99,38 @@ module Ask
         body = content[(end_idx + 5)..] || ""
         body.sub(/\A\n/, "").strip
       end
+
+      private
+
+      # Build the prioritized source list.
+      # Order: per-agent → shared project → legacy → user → gems → built-in
+      def build_source_list(agent_dir: nil)
+        sources = []
+
+        # Per-agent skills (highest priority — agent-specific first)
+        if agent_dir
+          per_agent = File.join(agent_dir, "skills")
+          sources << Source::Filesystem.new(dir: per_agent)
+        end
+
+        # Shared project skills
+        sources << Source::Filesystem.new(project_dir: "agents/shared/skills")
+        sources << Source::Filesystem.new(project_dir: "app/agents/shared/skills")
+
+        # Legacy project skills (backward compat)
+        sources << Source::Filesystem.new(project_dir: ".agents/skills")
+
+        # User-global skills
+        sources << Source::Filesystem.new(user_dir: "~/.config/ask/skills")
+
+        # Gems
+        sources << Source::Gems.new
+
+        # Built-in
+        sources << Source::Filesystem.new(dir: builtin_skills_dir)
+
+        sources
+      end
     end
   end
 end

metadata

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