simple-agent-extension 0.2.1 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d5b57957c947b2f4c126dca54b41f69e67d8d2cbfc3a9447a31bea468b03cf76
-  data.tar.gz: 2aafa730f3def389acfd18c2cec0807dfcd78aa1148199ca7a6129ab93fe7c49
+  metadata.gz: 404e535b96de550ec739358155e62a38ec0d9a07a2ec2f78e7607eb3a98930d7
+  data.tar.gz: e17a63f61c78d8b9f30631d52ff212ba890e71ccc0ab17e8a9e1a9b56d919060
 SHA512:
-  metadata.gz: 6bcc677fcc9c6afe8f01f67e77b7a65e86fda1a45ea951a21a362eb88e8b3650ec34e90399292cb3b9b0dacdb082e8c8a5ea3bc0033dbf13f3476366ed4491f2
-  data.tar.gz: f86cf67049dbc0bb7c16ed8c708ebb2e4b6c903240f1f260a2d88eb4be75e8a60c3922550ac1c99962393f5dcacee17c6c6c2ea72780a890f304b4e6d9c78bbd
+  metadata.gz: b9d622f95994d3f6abcfa23cb3bce94b92316250ad9c3a24ca0b83092be5f05628fa73a10ca5093b60b86cb27753e903566c4a38e248c200518a2d7bb99ef3d7
+  data.tar.gz: 963497aacd95ec19efa3157202dc547dacccd2c71567be762d7a8c8ba347efd6a65894c3501b1c0f5ab5794622ba3ff26db682eda2d73fe68cf1c3dbe4f54e63

data/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [0.2.3] 2026-10-12
+
+- feat: add version option
+- feat: add clean subcommand
+- feat: support `disable-model-invocation' field for very heavy skills
+
+## [0.2.2] 2026-10-04
+
+- fix: make the causes of errors easier to read
+- chore: add gem package task
+- docs: install from rubygems.org or run with rvx
+
 ## [0.2.1] 2026-10-02
 
 - feat: support Claude Code

data/README.md

@@ -4,14 +4,14 @@
 
 ## Installation
 
-Requires Ruby 3.3 or later.
+Requires Ruby 3.3 or later (not needed beforehand when running with `rvx`, which provides Ruby itself).
 
-The gem is not published to RubyGems.org yet, so install it from GitHub with Bundler:
+Add the gem to your Gemfile:
 
 ```ruby
 # Gemfile
 group :development do
-  gem "simple-agent-extension", github: "colorfulcompany/simple-agent-extension"
+  gem "simple-agent-extension"
 end
 ```
 
@@ -25,16 +25,12 @@ Then run the CLI through Bundler:
 bundle exec simple-agent-extension packages
 ```
 
-Pin a release with `tag:` so the checkout does not move:
+Or run it without a Gemfile with [rv](https://github.com/spinel-coop/rv)'s `rvx`, which installs the gem on first use:
 
-```ruby
-gem "simple-agent-extension",
-  github: "colorfulcompany/simple-agent-extension",
-  tag: "v0.1.0"
+```sh
+rvx simple-agent-extension packages
 ```
 
-`branch:` and `ref:` are also available; note that `branch:` follows new commits rather than pinning.
-
 ## Usage
 
 ### Defining a package
@@ -119,9 +115,16 @@ entrypoint frontmatter
   < static.agents.<agent>
 ```
 
-#### Adaptation across Agents
+#### Supported adaptive fields
+
+| Field | Applies to | Value | Meaning |
+|---|---|---|---|
+| `permissions` | agent, skill | map of tool name to `allow`, `ask`, or `deny` | Which tools the extension may use, and how. |
+| `disable-model-invocation` | skill | boolean | `true` keeps the skill out of model auto-selection; `/name` still works. |
 
-One `adaptive` fragment becomes different artifact metadata per Agent. The `permissions` fragment above compiles to:
+Each Agent decides how a field appears in its artifact; see the `MetadataTranslator` in `lib/simple_agent_extension/agents/`. A field an Agent has no rule for, listed here or not, passes through unchanged, so it takes effect only on an Agent that recognizes it.
+
+The `permissions` fragment above (`read: allow`, `edit: ask`) compiles to:
 
 | Agent | Artifact metadata |
 |---|---|
@@ -131,6 +134,8 @@ One `adaptive` fragment becomes different artifact metadata per Agent. The `perm
 
 `claude` maps known lowercase tool names such as `read` and `webfetch` to Claude Code's names (`Read`, `WebFetch`) and passes any other name through unchanged. `deny` becomes `disallowedTools` on an agent and `disallowed-tools` on a skill. An agent's `tools` lists both `allow` and `ask` tools, because Claude Code's `tools` limits which tools exist rather than pre-approving them.
 
+`disable-model-invocation` is not part of the Agent Skills specification, but Claude Code, Copilot, and OpenCode v2 ( 2.0.23+ ) read it as written. Older OpenCode versions read only their own `metadata` keys, so `opencode` translates the field for them.
+
 A skill whose metadata is left unchanged by adaptation and carries no Agent-specific static fragments is written once to the shared skill directory. Otherwise it is written into that Agent's own configuration tree ( written with Ruby ). An agent extension is always Agent-specific. `claude` does not read the shared skill directory, so its skills are always written to `~/.claude/skills`.
 
 ### Commands
@@ -141,11 +146,14 @@ snapshot as below:
 
 ```sh
 simple-agent-extension packages
+simple-agent-extension clean
 simple-agent-extension build
 simple-agent-extension deploy
 simple-agent-extension agents
 ```
 
+`build` (and therefore `deploy`) runs `clean` first, so an artifact whose source package was removed is not deployed again. `clean` removes `<build-root>/<agent>/` for each targeted Agent only. It does not remove anything already deployed.
+
 All commands resolve `--source-root` from `./packages` and `--build-root` from `./build` by default. Either root may be outside the repository.
 
 ```sh

data/lib/simple_agent_extension/agent_directory_loader.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
 module SimpleAgentExtension
-  class InvalidAgentDirectory < Error; end
+  class AgentDirectoryNotFound < Error; end
+  class AgentDirectoryNotDirectory < Error; end
+  class AgentDirectoryNotReadable < Error; end
   class MissingAgentRegistration < Error; end
   class UnloadableAgentRegistration < Error; end
 
@@ -28,12 +30,15 @@ module SimpleAgentExtension
       @directories.map { |directory| canonical_directory(directory) }.uniq
     end
 
+    # The error class names the condition, so the message carries the path
+    # alone.
     def canonical_directory(directory)
       path = File.expand_path(directory)
-      raise InvalidAgentDirectory, "invalid agent directory: #{path}" unless File.directory?(path)
+      raise AgentDirectoryNotFound, path unless File.exist?(path)
+      raise AgentDirectoryNotDirectory, path unless File.directory?(path)
 
       path = File.realpath(path)
-      raise InvalidAgentDirectory, "invalid agent directory: #{path}" unless File.readable?(path)
+      raise AgentDirectoryNotReadable, path unless File.readable?(path)
 
       path
     end

data/lib/simple_agent_extension/agents/opencode.rb

@@ -10,6 +10,22 @@ module SimpleAgentExtension
           {"permission" => permissions}
         end
 
+        # For OpenCode before 2.0.23, which reads only these `metadata` keys.
+        # 2.0.23+ reads top-level `disable-model-invocation` itself and ignores
+        # `opencode/slash`, so this rule can go once older versions are unsupported.
+        define_translation type: :skill, field: "disable-model-invocation" do |disabled|
+          if disabled == true
+            {
+              "metadata" => {
+                "opencode/autoinvoke" => "false",
+                "opencode/slash" => "true"
+              }
+            }
+          else # standard:disable Style/EmptyElse
+            nil
+          end
+        end
+
         define_translation type: :agent, field: "name" do |_name|
           nil
         end

data/lib/simple_agent_extension/cli.rb

@@ -6,9 +6,17 @@ require "simple_agent_extension"
 module SimpleAgentExtension
   # Command-line adapter for public package compilation and deployment.
   class CLI
+    # The command line itself was written wrong. The message describes the
+    # mistake in full, so where it was raised tells the caller nothing.
+    class UsageError < Error; end
+
+    # No command was resolved, so the caller still needs the vocabulary.
+    class CommandError < UsageError; end
+
     COMMANDS = {
       "packages" => "List package names under the source root",
-      "build" => "Compile artifacts into the build root",
+      "clean" => "Remove artifacts from the build root",
+      "build" => "Clean, then compile artifacts into the build root",
       "deploy" => "Build artifacts, then deploy them to Agents",
       "agents" => "List Agent names that can be targeted"
     }.freeze
@@ -22,6 +30,12 @@ module SimpleAgentExtension
       @error = error
     end
 
+    # Only errors this CLI defines, and the one OptionParser raises for a
+    # misspelled option, are reduced to a message. Everything else passes
+    # through with its class, origin, and backtrace intact.
+    #
+    # CommandError has to be listed first: it is a UsageError, so the wider
+    # clause would take it otherwise.
     def run(arguments)
       arguments = arguments.dup
       options = default_options
@@ -29,15 +43,17 @@ module SimpleAgentExtension
       parser.parse!(arguments)
 
       return display_help(parser) if options[:help]
+      return display_version(parser) if options[:version]
 
       command = command(arguments)
       validate_options(command, options)
       AgentDirectoryLoader.new(options[:agent_directories]).load
       run_command(command, options)
       0
-    rescue OptionParser::ParseError, Error, ArgumentError, KeyError => error
-      @error.puts error.message
-      1
+    rescue CommandError => error
+      report_failure(error, usage: parser)
+    rescue OptionParser::ParseError, UsageError => error
+      report_failure(error)
     end
 
     # Aligns the name column alone. Columns an Agent does not declare are
@@ -55,6 +71,16 @@ module SimpleAgentExtension
 
     private
 
+    # @param [Exception] error
+    # @param [OptionParser, nil] usage printed when the caller still needs the
+    #   command vocabulary
+    # @return [Integer] exit status the run reports as a failure
+    def report_failure(error, usage: nil)
+      @error.puts error.message
+      @error.puts usage if usage
+      1
+    end
+
     def default_options
       {
         source_root: File.expand_path("packages"),
@@ -62,13 +88,16 @@ module SimpleAgentExtension
         agents: [],
         agent_directories: [],
         force: false,
-        help: false
+        help: false,
+        version: false
       }
     end
 
     def option_parser(options)
       OptionParser.new do |parser|
         parser.banner = banner
+        parser.program_name = "simple-agent-extension"
+        parser.version = VERSION
 
         parser.on("--source-root DIRECTORY", "Source package root (default: ./packages)") do |directory|
           options[:source_root] = File.expand_path(directory)
@@ -76,7 +105,7 @@ module SimpleAgentExtension
         parser.on("--build-root DIRECTORY", "Build artifact root (default: ./build)") do |directory|
           options[:build_root] = File.expand_path(directory)
         end
-        parser.on("--agent NAME", "Build or deploy only NAME (repeatable)") do |name|
+        parser.on("--agent NAME", "Clean, build, or deploy only NAME (repeatable)") do |name|
           options[:agents] << name
         end
         parser.on("--agent-dir DIRECTORY", "Load direct *.rb Agent registrations from DIRECTORY") do |directory|
@@ -88,6 +117,9 @@ module SimpleAgentExtension
         parser.on("-h", "--help", "Show this help") do
           options[:help] = true
         end
+        parser.on("-V", "--version", "Show version") do
+          options[:version] = true
+        end
       end
     end
 
@@ -99,15 +131,20 @@ module SimpleAgentExtension
     end
 
     def display_help(parser)
-      @output.puts parser
+      @output.puts parser.ver, "", parser
+      0
+    end
+
+    def display_version(parser)
+      @output.puts parser.ver
       0
     end
 
     def command(arguments)
       command = arguments.shift
-      raise ArgumentError, "missing command" unless command
-      raise ArgumentError, "unknown command: #{command}" unless COMMANDS.key?(command)
-      raise ArgumentError, "unexpected arguments: #{arguments.join(" ")}" unless arguments.empty?
+      raise CommandError, "missing command" unless command
+      raise CommandError, "unknown command: #{command}" unless COMMANDS.key?(command)
+      raise CommandError, "unexpected arguments: #{arguments.join(" ")}" unless arguments.empty?
 
       command
     end
@@ -115,7 +152,7 @@ module SimpleAgentExtension
     def validate_options(command, options)
       return unless options[:force] && command != "deploy"
 
-      raise ArgumentError, "--force is only valid for deploy"
+      raise UsageError, "--force is only valid for deploy"
     end
 
     def run_command(command, options)
@@ -130,6 +167,8 @@ module SimpleAgentExtension
         @output.puts runner.packages
       when "agents"
         @output.puts agent_lines(runner.agents)
+      when "clean"
+        @output.puts runner.clean(agents: options[:agents])
       when "build"
         @output.puts runner.build(agents: options[:agents])
       when "deploy"

data/lib/simple_agent_extension/extensions/base.rb

@@ -1,5 +1,8 @@
 module SimpleAgentExtension
   module Extensions
+    class EntrypointDocumentNotFound < Error; end
+    class InvalidEntrypointFrontmatter < Error; end
+
     EntrypointDocument = Data.define(:metadata, :body)
 
     # An extension that owns loading metadata from its directory.
@@ -48,6 +51,12 @@ module SimpleAgentExtension
         metadata, body = Frontmatter.parse(File.read(entrypoint_path))
 
         EntrypointDocument.new(metadata, body)
+      rescue Errno::ENOENT => e
+        not_found = EntrypointDocumentNotFound.new("entrypoint of package `#{@package}' / type `#{type}', #{entrypoint_path} not found.")
+        not_found.set_backtrace(e.backtrace)
+        raise not_found, cause: nil
+      rescue Psych::SyntaxError => e
+        raise InvalidEntrypointFrontmatter, "#{entrypoint_path}: #{[e.problem, e.context].compact.join(" ")} at line #{e.line + Frontmatter::METADATA_START_LINE_OFFSET} column #{e.column}", cause: nil
       end
 
       # @return [MetadataLoader] source YAML reader

data/lib/simple_agent_extension/frontmatter.rb

@@ -13,6 +13,8 @@ module SimpleAgentExtension
   module Frontmatter
     DELIMITER = "---".freeze
     PATTERN = /\A---\r?\n(.*?)^---[ \t]*\r?\n?/m
+    # Metadata starts after the opening delimiter line.
+    METADATA_START_LINE_OFFSET = 1
 
     class InvalidFrontmatter < Error; end
 

data/lib/simple_agent_extension/metadata_loader.rb

@@ -8,15 +8,23 @@ module SimpleAgentExtension
   # reader exposes adaptive, common static, and Agent-specific static fragment
   # collections without defining their field vocabulary.
   class MetadataLoader
+    class InvalidMetadata < Error; end
+
     FILENAME = "metadata.yaml".freeze
 
+    # Psych does not know which file it parsed, so the path is attached here.
+    # Its backtrace points into Psych itself, so it is dropped.
+    #
     # @param [String] dir
     # @return [MetadataLoader] empty when +metadata.yaml+ is absent, never nil
+    # @raise [InvalidMetadata] when +metadata.yaml+ has a YAML syntax error
     def self.load(dir)
       path = File.join(dir, FILENAME)
       return new(Metadata.new) unless File.exist?(path)
 
       new(Metadata.from(YAML.safe_load(File.read(path)) || {})) # rubocop:disable Style/YAMLFileRead
+    rescue Psych::SyntaxError => e
+      raise InvalidMetadata, "#{path}: #{[e.problem, e.context].compact.join(" ")} at line #{e.line} column #{e.column}", cause: nil
     end
 
     # @param [Metadata] metadata source YAML mapping

data/lib/simple_agent_extension/runner.rb

@@ -1,3 +1,5 @@
+require "fileutils"
+
 module SimpleAgentExtension
   # Coordinates source collection, compilation, and deployment for one
   # source and build roots. Entry points configure these boundaries explicitly.
@@ -25,12 +27,29 @@ module SimpleAgentExtension
       end
     end
 
+    # Removes each selected Agent's whole artifact subtree, so artifacts whose
+    # source package is gone cannot survive into the next deploy. Other
+    # Agents' subtrees are left alone.
+    #
+    # @param [Array<String>] agents target names; all targets when empty
+    # @return [Array<String>] Agent directories that existed and were removed
+    def clean(agents: [])
+      selected_agents(agents)
+        .map { |agent| File.join(@build_root, agent.name) }
+        .select { |dir| File.exist?(dir) }
+        .each { |dir| FileUtils.rm_rf(dir) }
+    end
+
+    # Cleans the selected Agents first, so the build tree mirrors the current
+    # source tree instead of accumulating every artifact ever compiled.
+    #
     # @param [Array<String>] agents target names; all targets when empty
     # @return [Array<String>] directories written to the build tree
     def build(agents: [])
       targets = selected_agents(agents)
       extensions = source_extensions
       warn_unknown_deploy_to_names(extensions)
+      clean(agents: agents)
 
       targets.flat_map { |agent|
         compiler = Compiler.new(agent: agent, build_root: @build_root)

data/lib/simple_agent_extension/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SimpleAgentExtension
-  VERSION = "0.2.1"
+  VERSION = "0.2.3"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: simple-agent-extension
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.2.3
 platform: ruby
 authors:
 - ''
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-10-02 00:00:00.000000000 Z
+date: 2026-10-13 00:00:00.000000000 Z
 dependencies: []
 description: 'Coding Agent Extension Utility with Simple DSL and Rule Translating
   and Deploying '