agent_skills 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 57798b894d8e2eff5fba30de74130a813e7ae2bdc6599021e3f3ff610a9a9908
+  data.tar.gz: 38f5cda0c7ee6714794ae177bd575c066f27f0d3f1738408b39d9b09dc17ef75
+SHA512:
+  metadata.gz: 3668a7b89dc969da83ae0dbf6eddf7355ae1df69ba4d784fa9946605e9bd2d189f9269b12da21e990b28705c27b2247807a6e82b5f63b9a700f86535183c5d01
+  data.tar.gz: a3e154ddb1665f9aff7cf90d921414c9b0fa2a1541d90b35eade04ae82c744e9cb7398d29a65208f643adb038f96bb45b8dd19e2c4de68e1a0e49155dc3ea0dc

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2025-01-29
+
+### Added
+
+- `Skill` class for parsing SKILL.md files with YAML frontmatter
+- `Validator` class for validating skills against agentskills.io specification
+- `Generator` class for scaffolding new skills
+- `Loader` class for discovering skills from filesystem paths
+- `Packager` class for creating and extracting .skill bundles
+- CLI tool with commands: `new`, `validate`, `list`, `info`, `pack`, `unpack`, `version`
+- Support for `scripts/`, `references/`, and `assets/` directories
+- `to_prompt_xml` method for LLM prompt injection
+- GitHub Actions CI workflow
+
+---
+
+[Unreleased]: https://github.com/rubyonai/agent_skills/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/rubyonai/agent_skills/releases/tag/v0.1.0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nagendra
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,140 @@
+# Agent Skills
+
+[![CI](https://github.com/rubyonai/agent_skills/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/rubyonai/agent_skills/actions/workflows/ci.yml)
+[![Gem Version](https://badge.fury.io/rb/agent_skills.svg)](https://badge.fury.io/rb/agent_skills)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Ruby implementation of the [Agent Skills](https://agentskills.io) open standard — a simple format for giving AI agents new capabilities.
+
+## What are Agent Skills?
+
+Agent Skills are portable folders of instructions that AI agents can load to perform specialized tasks. The format is supported by **Claude, GitHub Copilot, Cursor, VS Code**, and [26+ other tools](https://agentskills.io).
+
+```
+my-skill/
+├── SKILL.md          # Instructions for the agent (required)
+├── scripts/          # Executable code (optional)
+├── references/       # Supporting docs (optional)
+└── assets/           # Templates, data files (optional)
+```
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'agent_skills'
+```
+
+Or install directly:
+
+```bash
+gem install agent_skills
+```
+
+## Quick Start
+
+### Create a skill
+
+```bash
+agent-skills new my-skill -d "Description of what this skill does"
+```
+
+### Validate a skill
+
+```bash
+agent-skills validate ./my-skill
+```
+
+### Package for distribution
+
+```bash
+agent-skills pack ./my-skill
+# Creates: my-skill.skill
+```
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `agent-skills new NAME -d DESC` | Create a new skill |
+| `agent-skills validate PATH` | Validate skill against spec |
+| `agent-skills list` | List discovered skills |
+| `agent-skills info PATH` | Show skill details |
+| `agent-skills pack PATH` | Package into .skill file |
+| `agent-skills unpack FILE` | Extract a .skill file |
+
+## Ruby API
+
+```ruby
+require 'agent_skills'
+
+# Load and parse a skill
+skill = AgentSkills::Skill.load('./my-skill')
+skill.name          # => "my-skill"
+skill.description   # => "What it does..."
+
+# Validate against spec
+validator = AgentSkills::Validator.new(skill)
+validator.valid?    # => true
+validator.errors    # => []
+
+# Discover skills from paths
+loader = AgentSkills::Loader.new(paths: ['./skills'])
+loader.discover
+loader['my-skill']  # => #<AgentSkills::Skill>
+
+# Generate prompt XML for LLM injection
+skill.to_prompt_xml
+# => "<skill name=\"my-skill\"><description>...</description>...</skill>"
+
+# Create a new skill programmatically
+AgentSkills::Generator.create(
+  path: './skills',
+  name: 'my-skill',
+  description: 'What this skill does'
+)
+
+# Package and distribute
+AgentSkills::Packager.pack('./my-skill')              # => "my-skill.skill"
+AgentSkills::Packager.unpack('my-skill.skill', output: './extracted')
+```
+
+## SKILL.md Format
+
+```markdown
+---
+name: my-skill
+description: What this skill does and when to use it.
+license: MIT                        # optional
+compatibility: Requires Python 3.x  # optional
+---
+
+# My Skill
+
+Instructions for the agent go here...
+```
+
+See the [full specification](https://agentskills.io/specification) for details.
+
+## Development
+
+```bash
+git clone https://github.com/rubyonai/agent_skills.git
+cd agent_skills
+bundle install
+bundle exec rspec
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on [GitHub](https://github.com/rubyonai/agent_skills).
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.
+
+## Resources
+
+- [Agent Skills Specification](https://agentskills.io)
+- [Example Skills](https://github.com/anthropics/skills)

data/RELEASING.md

@@ -0,0 +1,95 @@
+# Releasing
+
+This document describes how to release a new version of the `agent_skills` gem.
+
+## Prerequisites
+
+1. Push access to the GitHub repository
+2. RubyGems account with ownership of `agent_skills` gem
+3. `RUBYGEMS_API_KEY` secret configured in GitHub repository settings
+
+## Setup (One-time)
+
+### Configure RubyGems API Key
+
+1. Get your API key from https://rubygems.org/profile/api_keys
+2. Add it to GitHub: Repository → Settings → Secrets → Actions → New secret
+   - Name: `RUBYGEMS_API_KEY`
+   - Value: Your API key
+
+## Release Process
+
+### 1. Update version
+
+Edit `lib/agent_skills/version.rb`:
+
+```ruby
+module AgentSkills
+  VERSION = "0.2.0"  # Update this
+end
+```
+
+### 2. Update CHANGELOG
+
+Add release notes to `CHANGELOG.md`:
+
+```markdown
+## [0.2.0] - YYYY-MM-DD
+
+### Added
+- New feature X
+
+### Fixed
+- Bug fix Y
+```
+
+### 3. Commit and tag
+
+```bash
+git add lib/agent_skills/version.rb CHANGELOG.md
+git commit -m "Release v0.2.0"
+git tag v0.2.0
+git push origin main --tags
+```
+
+### 4. Automated release
+
+Pushing the tag triggers the release workflow which:
+- Runs tests
+- Builds the gem
+- Creates a GitHub Release
+- Publishes to RubyGems
+
+## Manual Release (if needed)
+
+```bash
+# Build
+gem build agent_skills.gemspec
+
+# Test locally
+gem install ./agent_skills-0.2.0.gem
+
+# Publish
+gem push agent_skills-0.2.0.gem
+```
+
+## Rake Tasks
+
+```bash
+# Build gem
+bundle exec rake build
+
+# Install locally
+bundle exec rake install
+
+# Release (build, tag, push gem)
+bundle exec rake release
+```
+
+## Version Guidelines
+
+Follow [Semantic Versioning](https://semver.org/):
+
+- **MAJOR** (1.0.0): Breaking API changes
+- **MINOR** (0.2.0): New features, backward compatible
+- **PATCH** (0.1.1): Bug fixes, backward compatible

data/Rakefile

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "rubocop/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]
+
+desc "Run all tests and checks"
+task ci: %i[spec rubocop]
+
+desc "Open an IRB session with the gem loaded"
+task :console do
+  require "irb"
+  require "agent_skills"
+  ARGV.clear
+  IRB.start(__FILE__)
+end

data/agent_skills.gemspec

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative "lib/agent_skills/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "agent_skills"
+  spec.version       = AgentSkills::VERSION
+  spec.authors       = ["rubyonai"]
+  spec.email         = ["your-email@example.com"]
+
+  spec.summary       = "Ruby implementation of the Agent Skills open standard"
+  spec.description   = <<~DESC
+    Parse, validate, create, package, and load Agent Skills in Ruby.
+    Agent Skills is an open format (by Anthropic) for giving AI agents
+    new capabilities through structured instructions, scripts, and resources.
+  DESC
+  spec.homepage      = "https://github.com/rubyonai/agent_skills"
+  spec.license       = "MIT"
+  spec.required_ruby_version = ">= 3.0.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/rubyonai/agent_skills"
+  spec.metadata["changelog_uri"] = "https://github.com/rubyonai/agent_skills/blob/main/CHANGELOG.md"
+  spec.metadata["documentation_uri"] = "https://rubydoc.info/gems/agent_skills"
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  # Specify which files should be added to the gem
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[bin/ test/ spec/ features/ .git .github .circleci appveyor Gemfile])
+    end
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  # Runtime dependencies
+  spec.add_dependency "rubyzip", "~> 2.3"
+  spec.add_dependency "thor", "~> 1.3"
+end

data/exe/agent-skills

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "agent_skills"
+require "agent_skills/cli"
+
+AgentSkills::CLI.start(ARGV)

data/lib/agent_skills/cli.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require "thor"
+
+module AgentSkills
+  class CLI < Thor
+    def self.exit_on_failure?
+      true
+    end
+
+    desc "new NAME", "Create a new skill"
+    option :description, aliases: "-d", required: true, desc: "Skill description"
+    option :path, aliases: "-p", default: ".", desc: "Output directory"
+    option :scripts, type: :boolean, default: false, desc: "Include scripts directory"
+    option :references, type: :boolean, default: false, desc: "Include references directory"
+    option :assets, type: :boolean, default: false, desc: "Include assets directory"
+    def new(name)
+      path = Generator.create(
+        path: options[:path],
+        name: name,
+        description: options[:description],
+        with_scripts: options[:scripts],
+        with_references: options[:references],
+        with_assets: options[:assets]
+      )
+
+      say "Created skill at #{path}/", :green
+      say "  SKILL.md"
+      say "  scripts/" if options[:scripts]
+      say "  references/" if options[:references]
+      say "  assets/" if options[:assets]
+    end
+
+    desc "validate PATH", "Validate a skill against the spec"
+    def validate(path)
+      skill = Skill.load(path)
+      validator = Validator.new(skill)
+
+      if validator.valid?
+        say "#{skill.name} is valid", :green
+      else
+        say "#{skill.name} has errors:", :red
+        validator.errors.each { |e| say "  - #{e}", :red }
+        exit 1
+      end
+    rescue NotFoundError, ParseError => e
+      say "Error: #{e.message}", :red
+      exit 1
+    end
+
+    desc "list", "List discovered skills"
+    option :path, aliases: "-p", type: :array, desc: "Paths to search"
+    def list
+      paths = options[:path] || Loader::DEFAULT_PATHS
+      loader = Loader.new(paths: paths)
+      skills = loader.discover
+
+      if skills.empty?
+        say "No skills found in: #{paths.join(', ')}", :yellow
+        return
+      end
+
+      say "Found #{skills.size} skill(s):\n\n"
+
+      skills.each do |name, skill|
+        say name, :green
+        say "  #{truncate(skill.description, 60)}"
+        say "  Path: #{skill.path}" if skill.path
+        say ""
+      end
+    end
+
+    desc "info PATH", "Show detailed skill information"
+    def info(path)
+      skill = Skill.load(path)
+
+      say "Name:        ", :green, false
+      say skill.name
+      say "Description: ", :green, false
+      say skill.description
+      say "Path:        ", :green, false
+      say skill.path || "(none)"
+
+      if skill.license
+        say "License:     ", :green, false
+        say skill.license
+      end
+
+      if skill.compatibility
+        say "Compat:      ", :green, false
+        say skill.compatibility
+      end
+
+      unless skill.scripts.empty?
+        say "Scripts:     ", :green, false
+        say skill.scripts.map { |s| File.basename(s) }.join(", ")
+      end
+
+      unless skill.references.empty?
+        say "References:  ", :green, false
+        say skill.references.map { |r| File.basename(r) }.join(", ")
+      end
+
+      # Validation status
+      validator = Validator.new(skill)
+      say "Valid:       ", :green, false
+      say validator.valid? ? "Yes" : "No (#{validator.errors.join(', ')})"
+    rescue NotFoundError, ParseError => e
+      say "Error: #{e.message}", :red
+      exit 1
+    end
+
+    desc "pack PATH", "Package a skill into a .skill file"
+    option :output, aliases: "-o", desc: "Output file path"
+    def pack(path)
+      output = Packager.pack(path, output: options[:output])
+      say "Created #{output}", :green
+    rescue NotFoundError, ParseError, ValidationError => e
+      say "Error: #{e.message}", :red
+      exit 1
+    end
+
+    desc "unpack FILE", "Extract a .skill file"
+    option :output, aliases: "-o", default: ".", desc: "Output directory"
+    def unpack(file)
+      extracted = Packager.unpack(file, output: options[:output])
+      say "Extracted to #{extracted}", :green
+    rescue NotFoundError => e
+      say "Error: #{e.message}", :red
+      exit 1
+    end
+
+    desc "version", "Show version"
+    def version
+      say "agent_skills #{VERSION}"
+    end
+
+    private
+
+    def truncate(text, length)
+      return text if text.length <= length
+
+      "#{text[0, length - 3]}..."
+    end
+  end
+end

data/lib/agent_skills/errors.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module AgentSkills
+  class Error < StandardError; end
+
+  class NotFoundError < Error; end
+
+  class ParseError < Error; end
+
+  class ValidationError < Error; end
+end

data/lib/agent_skills/generator.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module AgentSkills
+  class Generator
+    SKILL_TEMPLATE = <<~SKILL
+      ---
+      name: %<name>s
+      description: %<description>s
+      ---
+
+      # %<title>s
+
+      ## Instructions
+
+      [Add step-by-step instructions here]
+
+      ## Examples
+
+      ### Input
+      [Example input]
+
+      ### Output
+      [Expected output]
+
+      ## Guidelines
+
+      - [Add guidelines here]
+    SKILL
+
+    attr_reader :path, :name, :description, :options
+
+    def initialize(path:, name:, description:, **options)
+      @path = path
+      @name = name
+      @description = description
+      @options = options
+    end
+
+    def self.create(path:, name:, description:, **options)
+      new(path: path, name: name, description: description, **options).create
+    end
+
+    def create
+      validate_inputs!
+      create_directories
+      create_skill_md
+      skill_path
+    end
+
+    private
+
+    def validate_inputs!
+      raise ArgumentError, "name is required" if @name.nil? || @name.empty?
+      raise ArgumentError, "description is required" if @description.nil? || @description.empty?
+    end
+
+    def skill_path
+      File.join(@path, @name)
+    end
+
+    def create_directories
+      FileUtils.mkdir_p(skill_path)
+      FileUtils.mkdir_p(File.join(skill_path, "scripts")) if @options[:with_scripts]
+      FileUtils.mkdir_p(File.join(skill_path, "references")) if @options[:with_references]
+      FileUtils.mkdir_p(File.join(skill_path, "assets")) if @options[:with_assets]
+    end
+
+    def create_skill_md
+      content = format(
+        SKILL_TEMPLATE,
+        name: @name,
+        description: @description,
+        title: titleize(@name)
+      )
+
+      File.write(File.join(skill_path, "SKILL.md"), content)
+    end
+
+    def titleize(name)
+      name.split("-").map(&:capitalize).join(" ")
+    end
+  end
+end

data/lib/agent_skills/loader.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module AgentSkills
+  class Loader
+    DEFAULT_PATHS = [
+      File.expand_path("~/.config/claude/skills"),
+      ".claude/skills",
+      "skills"
+    ].freeze
+
+    attr_reader :paths, :skills
+
+    def initialize(paths: DEFAULT_PATHS)
+      @paths = Array(paths)
+      @skills = {}
+    end
+
+    def discover
+      @skills = {}
+
+      @paths.each do |base_path|
+        expanded = File.expand_path(base_path)
+        next unless File.directory?(expanded)
+
+        discover_in_path(expanded)
+      end
+
+      @skills
+    end
+
+    def [](name)
+      @skills[name]
+    end
+
+    def count
+      @skills.size
+    end
+
+    def each(&block)
+      @skills.each(&block)
+    end
+
+    def find_relevant(query)
+      return [] if query.nil? || query.empty?
+
+      keywords = query.downcase.split(/\s+/)
+
+      @skills.values.select do |skill|
+        text = "#{skill.name} #{skill.description}".downcase
+        keywords.any? { |keyword| text.include?(keyword) }
+      end
+    end
+
+    private
+
+    def discover_in_path(base_path)
+      Dir.glob(File.join(base_path, "*", "SKILL.md")).each do |skill_md|
+        skill_dir = File.dirname(skill_md)
+
+        begin
+          skill = Skill.load(skill_dir)
+          @skills[skill.name] = skill
+        rescue Error => e
+          warn "Warning: Failed to load skill at #{skill_dir}: #{e.message}"
+        end
+      end
+    end
+  end
+end

data/lib/agent_skills/packager.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "zip"
+require "fileutils"
+
+module AgentSkills
+  class Packager
+    SKILL_EXTENSION = ".skill"
+
+    def self.pack(skill_path, output: nil)
+      new(skill_path).pack(output: output)
+    end
+
+    def self.unpack(skill_file, output:)
+      new(nil).unpack(skill_file, output: output)
+    end
+
+    def initialize(skill_path)
+      @skill_path = skill_path
+    end
+
+    def pack(output: nil)
+      validate_skill!
+
+      skill = Skill.load(@skill_path)
+      Validator.validate!(skill)
+
+      output_file = output || "#{skill.name}#{SKILL_EXTENSION}"
+
+      create_zip(output_file)
+      output_file
+    end
+
+    def unpack(skill_file, output:)
+      raise NotFoundError, "Skill file not found: #{skill_file}" unless File.exist?(skill_file)
+
+      FileUtils.mkdir_p(output)
+
+      Zip::File.open(skill_file) do |zip|
+        zip.each do |entry|
+          dest = File.join(output, entry.name)
+          FileUtils.mkdir_p(File.dirname(dest))
+          entry.extract(dest) { true } # overwrite existing
+        end
+      end
+
+      # Return the extracted skill directory
+      skill_dirs = Dir.glob(File.join(output, "*", "SKILL.md")).map { |f| File.dirname(f) }
+      skill_dirs.first || output
+    end
+
+    private
+
+    def validate_skill!
+      raise NotFoundError, "Skill path not found: #{@skill_path}" unless File.directory?(@skill_path)
+
+      skill_md = File.join(@skill_path, "SKILL.md")
+      raise NotFoundError, "SKILL.md not found in #{@skill_path}" unless File.exist?(skill_md)
+    end
+
+    def create_zip(output_file)
+      File.delete(output_file) if File.exist?(output_file)
+
+      Zip::File.open(output_file, Zip::File::CREATE) do |zip|
+        add_directory_to_zip(zip, @skill_path, File.basename(@skill_path))
+      end
+    end
+
+    def add_directory_to_zip(zip, dir_path, base_name)
+      Dir.glob(File.join(dir_path, "**", "*")).each do |file|
+        next if File.directory?(file)
+
+        relative_path = file.sub("#{dir_path}/", "")
+        zip_path = File.join(base_name, relative_path)
+        zip.add(zip_path, file)
+      end
+    end
+  end
+end

data/lib/agent_skills/skill.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module AgentSkills
+  class Skill
+    FRONTMATTER_REGEX = /\A---\s*\n(.+?)\n---\s*\n(.*)/m
+
+    attr_reader :path, :name, :description, :license, :compatibility,
+                :metadata, :allowed_tools, :body
+
+    def initialize(path:, name:, description:, body:, license: nil,
+                   compatibility: nil, metadata: {}, allowed_tools: [])
+      @path = path
+      @name = name
+      @description = description
+      @body = body
+      @license = license
+      @compatibility = compatibility
+      @metadata = metadata
+      @allowed_tools = allowed_tools
+    end
+
+    def self.load(skill_path)
+      skill_md_path = File.join(skill_path, "SKILL.md")
+
+      unless File.exist?(skill_md_path)
+        raise NotFoundError, "SKILL.md not found in #{skill_path}"
+      end
+
+      content = File.read(skill_md_path, encoding: "UTF-8")
+      parse(content, skill_path)
+    end
+
+    def self.parse(content, path = nil)
+      match = content.match(FRONTMATTER_REGEX)
+
+      unless match
+        raise ParseError, "Invalid SKILL.md format: missing YAML frontmatter"
+      end
+
+      frontmatter = YAML.safe_load(match[1], symbolize_names: true)
+      body = match[2].strip
+
+      new(
+        path: path,
+        name: frontmatter[:name],
+        description: frontmatter[:description],
+        license: frontmatter[:license],
+        compatibility: frontmatter[:compatibility],
+        metadata: frontmatter[:metadata] || {},
+        allowed_tools: parse_allowed_tools(frontmatter[:"allowed-tools"]),
+        body: body
+      )
+    end
+
+    def scripts
+      return [] unless @path
+
+      Dir.glob(File.join(@path, "scripts", "*")).select { |f| File.file?(f) }
+    end
+
+    def references
+      return [] unless @path
+
+      Dir.glob(File.join(@path, "references", "*.md"))
+    end
+
+    def assets
+      return [] unless @path
+
+      Dir.glob(File.join(@path, "assets", "*")).select { |f| File.file?(f) }
+    end
+
+    def to_prompt_xml
+      <<~XML.strip
+        <skill name="#{@name}">
+          <description>#{@description}</description>
+          <instructions>
+        #{@body}
+          </instructions>
+        </skill>
+      XML
+    end
+
+    def to_h
+      {
+        name: @name,
+        description: @description,
+        license: @license,
+        compatibility: @compatibility,
+        metadata: @metadata,
+        allowed_tools: @allowed_tools,
+        body: @body
+      }.compact
+    end
+
+    private
+
+    def self.parse_allowed_tools(value)
+      return [] if value.nil?
+
+      value.to_s.split(/\s+/)
+    end
+
+    private_class_method :parse_allowed_tools
+  end
+end

data/lib/agent_skills/validator.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module AgentSkills
+  class Validator
+    NAME_REGEX = /\A[a-z0-9]+(-[a-z0-9]+)*\z/
+    MAX_NAME_LENGTH = 64
+    MAX_DESCRIPTION_LENGTH = 1024
+    MAX_COMPATIBILITY_LENGTH = 500
+
+    attr_reader :skill, :errors
+
+    def initialize(skill)
+      @skill = skill
+      @errors = []
+    end
+
+    def valid?
+      @errors = []
+      validate_name
+      validate_description
+      validate_compatibility
+      validate_directory_match
+      @errors.empty?
+    end
+
+    def self.validate!(skill)
+      validator = new(skill)
+      return skill if validator.valid?
+
+      raise ValidationError, validator.errors.join(", ")
+    end
+
+    private
+
+    def validate_name
+      name = @skill.name.to_s
+
+      if name.empty?
+        @errors << "name is required"
+        return
+      end
+
+      if name.length > MAX_NAME_LENGTH
+        @errors << "name must be #{MAX_NAME_LENGTH} characters or less"
+      end
+
+      unless name.match?(NAME_REGEX)
+        @errors << "name must contain only lowercase letters, numbers, and hyphens"
+      end
+
+      if name.start_with?("-") || name.end_with?("-")
+        @errors << "name cannot start or end with a hyphen"
+      end
+
+      if name.include?("--")
+        @errors << "name cannot contain consecutive hyphens"
+      end
+    end
+
+    def validate_description
+      description = @skill.description.to_s
+
+      if description.empty?
+        @errors << "description is required"
+        return
+      end
+
+      if description.length > MAX_DESCRIPTION_LENGTH
+        @errors << "description must be #{MAX_DESCRIPTION_LENGTH} characters or less"
+      end
+    end
+
+    def validate_compatibility
+      compatibility = @skill.compatibility.to_s
+      return if compatibility.empty?
+
+      if compatibility.length > MAX_COMPATIBILITY_LENGTH
+        @errors << "compatibility must be #{MAX_COMPATIBILITY_LENGTH} characters or less"
+      end
+    end
+
+    def validate_directory_match
+      return unless @skill.path
+
+      dir_name = File.basename(@skill.path)
+      return if dir_name == @skill.name
+
+      @errors << "name '#{@skill.name}' must match directory name '#{dir_name}'"
+    end
+  end
+end

data/lib/agent_skills/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module AgentSkills
+  VERSION = "0.1.0"
+end

data/lib/agent_skills.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative "agent_skills/version"
+require_relative "agent_skills/errors"
+require_relative "agent_skills/skill"
+require_relative "agent_skills/validator"
+require_relative "agent_skills/generator"
+require_relative "agent_skills/loader"
+require_relative "agent_skills/packager"
+
+module AgentSkills
+end

metadata

@@ -0,0 +1,97 @@
+--- !ruby/object:Gem::Specification
+name: agent_skills
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- rubyonai
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-01-29 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rubyzip
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.3'
+- !ruby/object:Gem::Dependency
+  name: thor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+description: |
+  Parse, validate, create, package, and load Agent Skills in Ruby.
+  Agent Skills is an open format (by Anthropic) for giving AI agents
+  new capabilities through structured instructions, scripts, and resources.
+email:
+- your-email@example.com
+executables:
+- agent-skills
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- CHANGELOG.md
+- LICENSE
+- README.md
+- RELEASING.md
+- Rakefile
+- agent_skills.gemspec
+- exe/agent-skills
+- lib/agent_skills.rb
+- lib/agent_skills/cli.rb
+- lib/agent_skills/errors.rb
+- lib/agent_skills/generator.rb
+- lib/agent_skills/loader.rb
+- lib/agent_skills/packager.rb
+- lib/agent_skills/skill.rb
+- lib/agent_skills/validator.rb
+- lib/agent_skills/version.rb
+homepage: https://github.com/rubyonai/agent_skills
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/rubyonai/agent_skills
+  source_code_uri: https://github.com/rubyonai/agent_skills
+  changelog_uri: https://github.com/rubyonai/agent_skills/blob/main/CHANGELOG.md
+  documentation_uri: https://rubydoc.info/gems/agent_skills
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Ruby implementation of the Agent Skills open standard
+test_files: []