elelem-skills 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8f2f20ca978d891df63d961aa6addc64e332b8c714951c7175350676fbbd8ede
-  data.tar.gz: d6e2469954a584ba74ead6eda9f53752115c9a4413a5788c9ae9991689c7d4a4
+  metadata.gz: 941ba03698ec16a9c0c6bffa098b25192cb633d1c22c34d8099400ff0baf87c7
+  data.tar.gz: 1656947d3135a5b4679d492d6c1912d1f6b5b2fefe3434eb7c5b36e19c34fbbb
 SHA512:
-  metadata.gz: 114a7a7d6d8f5c98fef7fba0731fbbb3fd69a7d0fda9a135aa5d30baf9c0e8ccd9f9283c1a7102b1445b188d1977051e1bdc5034b0635f25542613451162ae1f
-  data.tar.gz: d022633dc2203c10b1a7c72cb2c72877c4da3478e4a3bcfdb1990db10da0d61aab86c0c160d39219480757c8bdcf0081aa28260261902b99a484f2a219b0675b
+  metadata.gz: b53aabc68112a4164f942da764691458c6a488324a4ef58c4866977bb984d800f4b0aca0f29f75f6a72d10ee0b86b378ff64ab1e5f16166e7aac193232c2e3cb
+  data.tar.gz: deaf2dee82d9dd91ba1731d80311533ee8506973aa28023f4b9abb05e1c66cb6b60d246ea7c9b5f6ea0f40a9314669c39d657ed0f94874a803324de431608d35

data/.rspec

@@ -0,0 +1 @@
+--require spec_helper

data/README.md

@@ -0,0 +1,3 @@
+# elelem-skills
+
+Loads [agent skills](https://github.com/anthropics/skills) files under an `.agents/skills/` directory and exposes them to an `elelem` agent.

data/Rakefile

@@ -1,4 +1,8 @@
 # frozen_string_literal: true
 
 require "bundler/gem_tasks"
-task default: %i[]
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: %i[spec]

data/lib/elelem/skills/builtin/scrum/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: scrum
+description: Story-driven workflow for building a feature -- plan it into stories, design tasks, build test-first, review, then verify. Stories live in .agents/backlog/. Use when the user wants to work through a feature as a tracked, multi-step process rather than a single one-off change.
+---
+
+# Scrum
+
+A five-phase workflow, one story at a time, tracked as a markdown file in
+`.agents/backlog/`. Each phase is a separate file in this skill's directory
+-- read the one for the phase you're in.
+
+# Phases
+
+| Phase | File | When |
+|---|---|---|
+| Plan | [plan.md](plan.md) | Nothing is broken into stories yet |
+| Design | [design.md](design.md) | A story exists but has no Tasks, or its Tasks are stale |
+| Build | [build.md](build.md) | A story has Tasks and needs implementing |
+| Review | [review.md](review.md) | A story's Tasks are all checked off |
+| Verify | [verify.md](verify.md) | A story passed review |
+
+Read only the phase file you need for the current request -- each one is
+self-contained and says what to read the story for and what to write back.
+
+# Story Lifecycle
+
+A story file moves through the phases in order: plan creates it, design adds
+Tasks, build implements and checks them off, review approves the diff, verify
+confirms it works end-to-end and closes it out. Each phase only reads/writes
+the story file and the code it describes -- nothing here tracks phases across
+turns, so name the story explicitly once it exists (`.agents/backlog/NNN-*.md`)
+rather than relying on this skill to remember where you left off.

data/lib/elelem/skills/builtin/scrum/build.md

@@ -0,0 +1,29 @@
+Implement a story's tasks, one at a time, test-first.
+
+# Role
+- Work through the Tasks in the story the user specifies (see plan.md for the naming convention)
+- Follow TDD: write a failing test, implement the minimal code to pass, then move on
+- Check off each task in the story file as it's completed
+
+# Process
+1. **Focus** - If the user didn't name a story, list .agents/backlog/ and stop -- do not guess which one
+2. **Read** - Load the story and its Tasks
+3. **Red** - Write a failing test for the next unchecked task
+4. **Green** - Write the minimal code to make it pass
+5. **Verify** - Run the test suite
+6. **Check** - Mark the task complete in the story file, then repeat from step 3 for the next task
+
+# Task Completion
+When a task is done, edit the story file:
+```markdown
+# Tasks
+
+* [x] Create FooService in lib/foo_service.rb  ← mark done
+* [ ] Add #bar method to handle X              ← next task
+```
+
+# Guidelines
+- One task at a time, in order
+- Minimal diffs -- only what the current task needs
+- No defensive code or speculative abstraction
+- Run the test suite after every change, not just at the end

data/lib/elelem/skills/builtin/scrum/design.md

@@ -0,0 +1,32 @@
+Research the codebase and turn a story's intent into a concrete task list.
+
+# Role
+- Read the story from .agents/backlog/ (see plan.md for the naming convention)
+- Explore the codebase to find where the change belongs and what it touches
+- Fill in the story's Tasks section
+- Note risks or dependencies in the story's DESCRIPTION or SEE ALSO
+
+Do not write or edit application/test code in this skill -- only the story
+file. That's what makes design safe to run before committing to an approach.
+
+# Process
+1. **Review** - Read the story in .agents/backlog/
+2. **Explore** - Trace code paths, find the extension points and existing patterns to follow
+3. **Plan** - Break the story into small, ordered, testable tasks
+4. **Update** - Edit the story file's Tasks section
+
+# Task Format
+In the story's # Tasks section:
+```markdown
+# Tasks
+
+* [ ] Write a failing spec for FooService#bar in spec/foo_service_spec.rb
+* [ ] Create FooService#bar in lib/foo_service.rb to pass it
+* [ ] Update config/routes.rb to add the endpoint
+```
+
+# Guidelines
+- Tasks should be small, atomic, and independently testable
+- Order by dependency (write the test before the implementation task it drives)
+- Reference specific files to modify or create
+- One task should map to roughly one red-green cycle during the build phase

data/lib/elelem/skills/builtin/scrum/plan.md

@@ -0,0 +1,67 @@
+Turn the user's request into a backlog of small, testable user stories.
+
+# Role
+- Interview the user before writing anything. Ask clarifying questions, one
+  turn at a time, until you are at least 95% sure you understand the
+  request -- personas, goals, edge cases, what's explicitly out of scope.
+- Never make assumptions to fill a gap. If something is unclear or
+  unstated, ask about it instead of guessing.
+- Break large requests into small, independently deliverable stories.
+- Capture acceptance criteria in testable terms.
+- Write each story to .agents/backlog/ as a separate file.
+
+# Asking Questions
+This is a chat REPL: each response you give ends your turn and the user's
+next message continues the same conversation, so a real back-and-forth
+interview works here. To ask, just respond with the question as plain text
+and stop -- do not call a tool, do not write a story file yet. Ask one
+focused question (or a short related group) at a time rather than a long
+questionnaire in one message; that keeps the interview conversational and
+lets the user's answer to one question inform the next.
+
+(If you're running as `elelem ask` rather than `elelem chat`, there's no
+next turn to read an answer from. Say so, then proceed with your best
+understanding and mark the actual gaps as SEE ALSO items -- this is the
+one situation where documenting an assumption is the only option.)
+
+# Process
+1. **Read** - Take in the user's request; identify the distinct capabilities inside it.
+2. **Interview** - Ask clarifying questions, one exchange at a time, until you're at least 95% sure you understand each capability -- what it is, who it's for, and what's out of scope.
+3. **Scope** - Split into stories small enough to finish in one build session.
+4. **Document** - Write each as a story file (template below).
+5. **List** - After writing, list the story filenames and one-line summaries back to the user so they can redirect before build starts.
+
+# Story Template
+```markdown
+As a `[persona]`, I `[want to]`, so that `[goal]`.
+
+# SYNOPSIS
+
+<one-line summary>
+
+# DESCRIPTION
+
+<detailed explanation, informed by the interview -- not by assumptions>
+
+# SEE ALSO
+
+* [ ] <related files or concepts; not a place to park unanswered questions>
+
+# Tasks
+
+* [ ] TBD (filled in during the design phase, see design.md)
+
+# Acceptance Criteria
+
+* [ ] <testable criterion>
+```
+
+# Naming Convention
+Files: .agents/backlog/NNN-short-name.md (e.g., 001-user-login.md). NNN is
+zero-padded and continues from the highest existing number in the directory.
+
+# Guidelines
+- One story per file
+- Stories should be small enough to complete in one session
+- Acceptance criteria must be objectively testable -- ask "how will we know this is done?"
+- Don't write a story until the interview has resolved its open questions

data/lib/elelem/skills/{prompts/review.erb → builtin/scrum/review.md}

@@ -1,25 +1,24 @@
-You are in review mode. Verify changes meet acceptance criteria.
+Review code changes against a story's acceptance criteria.
 
 # Role
-- Review code changes against story acceptance criteria
+- Review code changes against the story's acceptance criteria
 - Check test coverage
 - Identify bugs, security issues, and quality concerns
 
 # Process
-1. **Context** - Read the story from .elelem/backlog/
+1. **Context** - Read the story from .agents/backlog/
 2. **Diff** - Run `git diff` to see changes
-3. **Trace** - Read surrounding context
-4. **Verify** - Check each acceptance criterion
-5. **Report** - Summarize findings
+3. **Trace** - Read surrounding context for anything the diff touches
+4. **Verify** - Check each acceptance criterion against the actual code
+5. **Report** - Summarize findings in the format below
 
 # Review Checklist
-- [ ] All tasks in story are checked off
+- [ ] All tasks in the story are checked off
 - [ ] Acceptance criteria are satisfied
 - [ ] Tests exist and pass
 - [ ] No logic errors or edge case bugs
 - [ ] No security vulnerabilities
 - [ ] No performance issues
-- [ ] SOLID principles followed
 - [ ] Code is readable and minimal
 
 # Output Format
@@ -40,5 +39,5 @@ Severity: critical | warning | nit
 
 # Guidelines
 - Be specific: cite file:line
-- Suggest fixes
-- Distinguish blocking from non-blocking issues
+- Suggest fixes, not just problems
+- Distinguish blocking issues from non-blocking ones

data/lib/elelem/skills/builtin/scrum/verify.md

@@ -0,0 +1,38 @@
+Smoke-test a finished feature end-to-end and record what you found.
+
+# Role
+- Run the feature as a user would, not by re-reading the code
+- Walk through the happy path and at least one realistic error case
+- Verify the actual behavior matches the story's intent
+- Record demo notes in the story file
+
+# Process
+1. **Setup** - Read the story in .agents/backlog/ to know what to demo
+2. **Execute** - Run the feature end-to-end (real commands, not a read-through)
+3. **Observe** - Note actual behavior, output, and any issues
+4. **Document** - Append demo notes to the story file (format below)
+5. **Report** - Summarize the result
+
+# Demo Checklist
+- [ ] Feature works as described in the story
+- [ ] Happy path completes successfully
+- [ ] At least one error case was tried and handled gracefully
+- [ ] Actual output matches the story's acceptance criteria
+
+# Story Update
+Append to the story file:
+```markdown
+# Demo Notes
+
+Status: ACCEPTED | NEEDS WORK
+
+Observations:
+- <what was tested>
+- <what worked>
+- <what needs attention, if anything>
+```
+
+# Guidelines
+- Test from the user's perspective, not the developer's
+- Try realistic scenarios, not just the exact example from the story
+- Be honest about gaps -- NEEDS WORK is a valid, useful outcome

data/lib/elelem/skills/catalog.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Elelem
+  module Skills
+    class Catalog
+      GEM_SKILLS = File.expand_path("builtin", __dir__).freeze
+      REMOTE_SKILLS = File.expand_path("~/.agents/remote-skills").freeze
+
+      LOAD_PATHS = [
+        GEM_SKILLS,
+        "~/.agents/skills",
+        ".agents/skills"
+      ].freeze
+
+      def initialize(load_paths: LOAD_PATHS, remote_skills: REMOTE_SKILLS)
+        @load_paths = load_paths
+        @remote_skills = remote_skills
+      end
+
+      def all
+        @all ||= discover
+      end
+
+      def find(name)
+        all.find { |skill| skill.name == name }
+      end
+
+      def index(limit: nil)
+        summaries = all.map(&:summary)
+        summaries = summaries.map { |text| truncate(text, limit) } if limit
+        summaries.join("\n")
+      end
+
+      private
+
+      def discover
+        seen = {}
+
+        @load_paths.each do |path|
+          scan_one_level(path, seen)
+          scan_remote(seen) if path == GEM_SKILLS && @remote_skills
+        end
+
+        seen.values
+      end
+
+      def scan_one_level(path, seen)
+        dir = File.expand_path(path)
+        return unless File.directory?(dir)
+
+        Dir["#{dir}/*/SKILL.md"].sort.each { |skill_md| load_into(skill_md, seen) }
+      end
+
+      def scan_remote(seen)
+        dir = File.expand_path(@remote_skills)
+        return unless File.directory?(dir)
+
+        Dir["#{dir}/*/*/SKILL.md"].sort.each { |skill_md| load_into(skill_md, seen) }
+      end
+
+      def load_into(skill_md, seen)
+        skill = SkillFile.load(skill_md)
+        return unless skill
+
+        seen[skill.name] = skill
+      rescue => e
+        Elelem.logger.warn("elelem-skills: failed to load #{skill_md}: #{e.message}")
+      end
+
+      def truncate(text, limit)
+        return text if text.length <= limit
+
+        "#{text[0, limit]}..."
+      end
+    end
+  end
+end

data/lib/elelem/skills/fetcher.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "digest"
+require "fileutils"
+require "json"
+require "net/http"
+require "uri"
+
+module Elelem
+  module Skills
+    class Fetcher
+      SCHEMA = "https://schemas.agentskills.io/discovery/0.2.0/schema.json"
+
+      FetchError = Class.new(StandardError)
+
+      def initialize(install_dir: Catalog::REMOTE_SKILLS, http: Net::HTTP)
+        @install_dir = install_dir
+        @http = http
+      end
+
+      # Fetches https://<origin>/.well-known/agent-skills/index.json
+      def fetch(origin)
+        base = normalize(origin)
+        index_url = URI.join(base, "/.well-known/agent-skills/index.json")
+        index = get_json(index_url)
+
+        unless index["$schema"] == SCHEMA
+          raise FetchError, "unrecognized index schema #{index["$schema"].inspect} at #{index_url} (expected #{SCHEMA})"
+        end
+
+        host_dir = File.join(@install_dir, sanitize(base.host))
+        (index["skills"] || []).filter_map { |entry| install(entry, index_url, host_dir) }
+      end
+
+      private
+
+      def normalize(origin)
+        origin = "https://#{origin}" unless origin.start_with?("http://", "https://")
+        URI.parse(origin)
+      end
+
+      def sanitize(host)
+        host.to_s.downcase.gsub(/[^a-z0-9.-]/, "_")
+      end
+
+      def install(entry, index_url, host_dir)
+        name, type, url, digest = entry.values_at("name", "type", "url", "digest")
+
+        unless type == "skill-md"
+          Elelem.logger.warn("elelem-skills: fetch: skipping #{name.inspect}, unsupported type #{type.inspect} (archives are not implemented)")
+          return nil
+        end
+
+        body = get_raw(URI.join(index_url, url))
+        verify!(name, body, digest)
+
+        dir = File.join(host_dir, sanitize(name))
+        FileUtils.mkdir_p(dir)
+        File.write(File.join(dir, "SKILL.md"), body)
+
+        name
+      end
+
+      def verify!(name, body, digest)
+        expected = digest.to_s.delete_prefix("sha256:")
+        actual = Digest::SHA256.hexdigest(body)
+        return if expected == actual
+
+        raise FetchError, "digest mismatch for #{name.inspect}: expected sha256:#{expected}, got sha256:#{actual}"
+      end
+
+      def get_json(uri)
+        JSON.parse(get_raw(uri))
+      rescue JSON::ParserError => e
+        raise FetchError, "invalid JSON at #{uri}: #{e.message}"
+      end
+
+      def get_raw(uri)
+        response = @http.get_response(uri)
+        raise FetchError, "GET #{uri} -> #{response.code} #{response.message}" unless response.is_a?(Net::HTTPSuccess)
+
+        response.body
+      rescue FetchError
+        raise
+      rescue => e
+        raise FetchError, "GET #{uri} failed: #{e.class}: #{e.message}"
+      end
+    end
+  end
+end

data/lib/elelem/skills/setup.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Elelem
+  module Skills
+    class Setup
+      SUMMARY_LIMIT = 400
+
+      def self.call(agent)
+        new(agent, Catalog.new).call
+      end
+
+      def initialize(agent, catalog)
+        @agent = agent
+        @catalog = catalog
+      end
+
+      def call
+        return if @catalog.all.empty?
+
+        register_tool
+        register_command
+      end
+
+      private
+
+      def register_tool
+        catalog = @catalog
+
+        @agent.toolbox.add("skill",
+          description: "Load a skill's instructions by name. Available skills:\n#{catalog.index(limit: SUMMARY_LIMIT)}",
+          params: { name: { type: "string", description: "the skill name" } },
+          required: ["name"]
+        ) do |a|
+          skill = catalog.find(a["name"])
+          next { error: "unknown skill: #{a["name"]}" } unless skill
+
+          { name: skill.name, dir: skill.dir, content: skill.body }
+        end
+      end
+
+      def register_command
+        catalog = @catalog
+        agent = @agent
+        completions = -> { catalog.all.map(&:name) }
+
+        agent.commands.register("skills", description: "List available skills, or `/skills fetch <origin>` to install from a remote index", completions: completions) do |arg|
+          if arg&.start_with?("fetch ")
+            fetch(agent, arg.delete_prefix("fetch ").strip)
+          elsif arg && !arg.empty?
+            skill = catalog.find(arg)
+            skill ? agent.output.say(skill.body) : agent.output.say("Unknown skill: #{arg}")
+          else
+            agent.output.say(catalog.index)
+          end
+        end
+      end
+
+      def fetch(agent, origin)
+        if origin.empty?
+          agent.output.say("Usage: /skills fetch <origin>")
+          return
+        end
+
+        names = Fetcher.new.fetch(origin)
+        agent.output.say(names.empty? ? "No skills installed from #{origin}." : "Installed: #{names.join(", ")}\nRestart elelem to pick them up (/reload does not currently re-register this gem's tool -- see README).")
+      rescue Fetcher::FetchError => e
+        agent.output.say(e.message, as: :error)
+      end
+    end
+  end
+end

data/lib/elelem/skills/skill.rb

@@ -1,9 +1,11 @@
 # frozen_string_literal: true
 
-Elelem.configure do |config|
-  config.setup(:skill) do |agent|
-    agent.commands.register("skill", description: "Invoke a skill (not yet implemented)") do |_args|
-      agent.output.say NotImplementedError.new("skills are not implemented yet").message
+module Elelem
+  module Skills
+    Skill = Struct.new(:name, :description, :dir, :body) do
+      def summary
+        "#{name}: #{description}"
+      end
     end
   end
 end

data/lib/elelem/skills/skill_file.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Elelem
+  module Skills
+    module SkillFile
+      def self.load(path)
+        parse(File.read(path), path: path)
+      end
+
+      def self.parse(text, path:)
+        frontmatter, body = split(text)
+        unless frontmatter
+          Elelem.logger.warn("elelem-skills: #{path} has no frontmatter, skipping")
+          return nil
+        end
+
+        attrs = YAML.safe_load(frontmatter)
+        name, description = attrs["name"], attrs["description"]
+        unless name && description
+          Elelem.logger.warn("elelem-skills: #{path} is missing name or description, skipping")
+          return nil
+        end
+
+        Skill.new(name, description, File.dirname(path), body.strip)
+      end
+
+      def self.split(text)
+        return [nil, text] unless text.start_with?("---\n")
+
+        _, frontmatter, body = text.split(/^---\s*$/, 3)
+        return [nil, text] unless frontmatter && body
+
+        [frontmatter, body]
+      end
+      private_class_method :split
+    end
+  end
+end

data/lib/elelem/skills/version.rb

@@ -2,6 +2,6 @@
 
 module Elelem
   module Skills
-    VERSION = "0.2.0"
+    VERSION = "0.3.0"
   end
 end

data/lib/elelem/skills.rb

@@ -1,6 +1,17 @@
 # frozen_string_literal: true
 
 require "elelem"
+require "yaml"
 
 require_relative "skills/version"
 require_relative "skills/skill"
+require_relative "skills/skill_file"
+require_relative "skills/catalog"
+require_relative "skills/fetcher"
+require_relative "skills/setup"
+
+Elelem.configure do |config|
+  config.setup(:skills) do |agent|
+    Elelem::Skills::Setup.call(agent)
+  end
+end