agent_skill_parser 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: bb27507d0523f0c0bb623a65b8817074f30f0c33bf415acfa29c16dd25e4d999
+  data.tar.gz: 13913b040ccc6fd706c9ed5d7bd79d00ef6d1ca46c988fa6d5033e06db9dfc68
+SHA512:
+  metadata.gz: 2ba5711dcaa15a855e53a45332f420c3d0c917e3d784468060ed3f7ce4c109eedbf90bdd88f04845402d165b55704403c63b40324cb641020dfd5dea6ee0fba3
+  data.tar.gz: 2b40d143d5f582a5d805887511d726dd849fffa5fced18f3f47bd11b1826e8a41503a32d4b69bcf681e236c9bbd06c2ec7518dbef9ee7f399994f2b5ec33ecac

data/.yardopts

@@ -0,0 +1,12 @@
+--markup markdown
+--format markdown
+--output-dir doc
+--title "AgentSkillParser"
+--protected
+--no-private
+--plugin markdown
+lib/**/*.rb
+-
+README.md
+CHANGELOG.md
+LICENSE.txt

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-01-29
+
+- Initial release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+"agent_skill_parser" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behaviour within this project, please contact us at ["lucianghinda@users.noreply.github.com"](mailto:"lucianghinda@users.noreply.github.com").

data/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

data/README.md

@@ -0,0 +1,175 @@
+# AgentSkillParser
+
+A Ruby gem for parsing skill files that use YAML frontmatter and markdown body content. Designed for agent/AI systems where skills are defined as structured markdown documents with metadata.
+
+Warning: 
+- This gem does not protect against Prompt Injection. It only parses the structure of the skill according with the specification from https://agentskills.io/specification
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "agent_skill_parser"
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install agent_skill_parser
+```
+
+## Skill File Format
+
+A skill file is a markdown document with YAML frontmatter delimited by `---`:
+
+```markdown
+---
+name: pdf-processing
+description: Extract text from PDF documents using various parsing strategies
+license: Apache-2.0
+compatibility: OpenAI Anthropic
+metadata:
+  author: Acme Inc
+  version: 1.0.0
+  category: document-processing
+allowed-tools: Bash(git:*) Read
+---
+
+## Instructions
+
+This skill helps extract text from PDFs.
+
+### Step 1: Download the PDF
+Use the Bash tool to download PDF files from URLs.
+```
+
+### Frontmatter Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | Yes | Skill identifier. Lowercase letters, numbers, and hyphens only (1-64 chars). Cannot start/end with a hyphen or contain consecutive hyphens. |
+| `description` | Yes | Human-readable description (1-1024 chars). |
+| `license` | No | License name (e.g., `MIT`, `Apache-2.0`). |
+| `compatibility` | No | Compatibility notes (max 500 chars). |
+| `metadata` | No | Custom key-value pairs. Values are coerced to strings. |
+| `allowed-tools` | No | Space or comma-separated tool names, optionally with patterns: `Bash(git:*) Read Write`. |
+
+### Allowed Tools Format
+
+Tools can be listed with optional regex patterns in parentheses:
+
+```yaml
+allowed-tools: Bash(git:*) Read Write
+```
+
+This produces `AllowedTool` objects where `Bash` has a pattern of `git:*`, and `Read`/`Write` have no pattern.
+
+## Usage
+
+### Parsing a Skill File
+
+```ruby
+skill = AgentSkillParser.parse("path/to/skill.md")
+
+skill.name          # => "pdf-processing"
+skill.description   # => "Extract text from PDF documents..."
+skill.body          # => "## Instructions\n\nThis skill helps..."
+```
+
+### Accessing Frontmatter
+
+```ruby
+fm = skill.frontmatter
+
+fm.name             # => "pdf-processing"
+fm.description      # => "Extract text from PDF documents..."
+fm.license          # => "Apache-2.0"
+fm.compatibility    # => "OpenAI Anthropic"
+fm.metadata         # => {"author" => "Acme Inc", "version" => "1.0.0", "category" => "document-processing"}
+fm.allowed_tools    # => [#<AllowedTool name="Bash" pattern="git:*">, ...]
+```
+
+### Accessing Allowed Tools
+
+```ruby
+tool = skill.frontmatter.allowed_tools.first
+
+tool.name    # => "Bash"
+tool.pattern # => "git:*"
+```
+
+### Error Handling
+
+```ruby
+begin
+  AgentSkillParser.parse("skill.md")
+rescue AgentSkillParser::Errors::Parser => e
+  puts "Parse error: #{e.message}"
+rescue AgentSkillParser::Errors::Validation => e
+  puts "Validation error: #{e.message}"
+rescue Errno::ENOENT => e
+  puts "File not found: #{e.message}"
+end
+```
+
+- `Errors::Parser` -- raised when YAML is malformed or the file cannot be read.
+- `Errors::Validation` -- raised when frontmatter values violate schema rules (e.g., invalid name format, description too long).
+
+### Minimal Skill File
+
+A skill file only requires `name` and `description`:
+
+```markdown
+---
+name: simple-skill
+description: A simple skill for testing
+---
+
+## Instructions
+
+This is a simple skill.
+```
+
+### Files Without Frontmatter
+
+Files without YAML frontmatter are parsed with an empty frontmatter and the entire content as the body.
+
+## Architecture
+
+The parsing pipeline consists of four stages:
+
+1. **DocumentSplitter** -- Separates YAML frontmatter from the markdown body.
+2. **FrontmatterParser** -- Parses the YAML string into a `Frontmatter` object.
+3. **Validator** -- Validates frontmatter against schema rules.
+4. **Skill construction** -- Combines the validated frontmatter and body into a `Skill` object.
+
+All data structures (`Skill`, `Frontmatter`, `AllowedTool`) are immutable, built using Ruby's `Data.define`.
+
+## Requirements
+
+- Ruby >= 3.2.0
+
+## Development
+
+Note: 
+- The code of this gem was generated with Claude Code + GLM but I review it manually and even if in some cases the code design could be better I feel like it is good enough for a first release. 
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+```bash
+bundle exec rake test     # Run tests
+bundle exec rake rubocop  # Run linter
+bundle exec rake yard     # Generate documentation
+bundle exec rake          # Run tests + linter
+```
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+require "yard"
+YARD::Rake::YardocTask.new
+
+task default: %i[test rubocop]

data/lib/agent_skill_parser/allowed_tool.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module AgentSkillParser
+  # Represents an allowed tool with optional regex pattern.
+  #
+  # @!attribute [r] name
+  #   @return [String] the tool name (e.g., "bash")
+  # @!attribute [r] pattern
+  #   @return [String, nil] optional regex pattern for arguments
+  #
+  # @example Tool without pattern
+  #   AllowedTool.new(name: "bash", pattern: nil)
+  #
+  # @example Tool with pattern
+  #   AllowedTool.new(name: "search_files", pattern: "\\.(rb|js)$")
+  AllowedTool = Data.define(:name, :pattern)
+end

data/lib/agent_skill_parser/allowed_tools_parser.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module AgentSkillParser
+  # Parses tool names with optional argument patterns.
+  #
+  # @example Parse tools
+  #   parser = AllowedToolsParser.new("bash, search_files(\\.rb$)")
+  #   parser.call
+  #   # => [
+  #   #      AllowedTool.new(name: "bash", pattern: nil),
+  #   #      AllowedTool.new(name: "search_files", pattern: "\\.rb$")
+  #   #    ]
+  class AllowedToolsParser
+    # @return [Regexp] pattern matching "tool_name" or "tool_name(pattern)"
+    TOOL_REGEX = /([A-Za-z_]\w*)(?:\(([^)]*)\))?/
+
+    # @param string [String] comma-separated tool list
+    def initialize(string)
+      @string = string
+    end
+
+    # @return [Array<AllowedTool>] parsed tool definitions
+    # @see AllowedTool
+    def call
+      return [] if @string.nil? || @string.empty?
+
+      @string.scan(TOOL_REGEX).map do |name, pattern|
+        AllowedTool.new(name:, pattern:)
+      end
+    end
+  end
+end

data/lib/agent_skill_parser/document_splitter.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module AgentSkillParser
+  # Splits a markdown document into YAML frontmatter and body.
+  #
+  # @example With frontmatter
+  #   splitter = DocumentSplitter.new("---\nname: skill\n---\n# Body")
+  #   splitter.call # => ["name: skill", "# Body"]
+  #
+  # @example Without frontmatter
+  #   splitter = DocumentSplitter.new("# Just body")
+  #   splitter.call # => ["", "# Just body"]
+  class DocumentSplitter
+    # Represents a raw YAML document with separated YAML frontmatter and body.
+    #
+    # @!attribute [r] yaml_string
+    #   @return [String] YAML frontmatter content
+    # @!attribute [r] body
+    #   @return [String] Markdown body content
+    RawYamlDocument = Data.define(:yaml_string, :body)
+
+    # @param text [String] full document content
+    def initialize(text)
+      @text = text
+    end
+
+    # @return [RawYamlDocument]
+    def call
+      parts = @text.lstrip.split(/^---$/, 3)
+
+      if parts.length == 3 && parts[0].empty?
+        RawYamlDocument.new(yaml_string: parts[1].strip, body: parts[2].strip)
+      else
+        RawYamlDocument.new(yaml_string: "", body: @text.strip)
+      end
+    end
+  end
+end

data/lib/agent_skill_parser/errors/base.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module AgentSkillParser
+  module Errors
+    # Base class for all parser exceptions.
+    #
+    # @abstract
+    class Base < StandardError
+    end
+  end
+end

data/lib/agent_skill_parser/errors/parser.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module AgentSkillParser
+  module Errors
+    # Raised when parsing fails (e.g., invalid YAML, file not found).
+    #
+    # @example Rescue pattern
+    #   begin
+    #     AgentSkillParser.parse("invalid.md")
+    #   rescue AgentSkillParser::Errors::Parser => e
+    #     puts "Parsing error: #{e.message}"
+    #   end
+    #
+    # @see FrontmatterParser#call
+    class Parser < Base
+    end
+  end
+end

data/lib/agent_skill_parser/errors/validation.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module AgentSkillParser
+  module Errors
+    # Raised when frontmatter validation fails.
+    #
+    # @example Rescue pattern
+    #   begin
+    #     AgentSkillParser.parse("skill.md")
+    #   rescue AgentSkillParser::Errors::Validation => e
+    #     puts "Validation error: #{e.message}"
+    #   end
+    #
+    # @see Validator#call
+    class Validation < Base
+    end
+  end
+end

data/lib/agent_skill_parser/errors.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module AgentSkillParser
+  # Namespace for all parser exceptions.
+  #
+  # @see Base
+  # @see Parser
+  # @see Validation
+  module Errors
+  end
+end

data/lib/agent_skill_parser/frontmatter.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module AgentSkillParser
+  # Parsed frontmatter data from a skill file.
+  #
+  # @!attribute [r] name
+  #   @return [String] skill identifier (lowercase, hyphens, no spaces)
+  # @!attribute [r] description
+  #   @return [String] human-readable description
+  # @!attribute [r] license
+  #   @return [String, nil] license name (optional)
+  # @!attribute [r] compatibility
+  #   @return [String, nil] compatibility notes (optional)
+  # @!attribute [r] metadata
+  #   @return [Hash{String => String}] custom key-value metadata
+  # @!attribute [r] allowed_tools
+  #   @return [Array<AllowedTool>] list of allowed tools
+  #
+  # @example
+  #   Frontmatter.new(
+  #     name: "my-skill",
+  #     description: "A useful skill",
+  #     license: "MIT",
+  #     compatibility: "v1.2.3+",
+  #     metadata: { "author" => "Alice" },
+  #     allowed_tools: [AllowedTool.new(name: "bash", pattern: nil)]
+  #   )
+  #
+  # @see FrontmatterParser
+  Frontmatter = Data.define(:name, :description, :license, :compatibility, :metadata, :allowed_tools)
+
+  # A singleton nil object for empty frontmatter.
+  # Used when YAML frontmatter is missing or empty.
+  NilFrontmatter = Frontmatter.new(
+    name: "",
+    description: "",
+    license: nil,
+    compatibility: nil,
+    metadata: {},
+    allowed_tools: []
+  ).freeze
+end

data/lib/agent_skill_parser/frontmatter_parser.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module AgentSkillParser
+  # Parses YAML frontmatter into a {Frontmatter} object.
+  #
+  # @example Parse frontmatter
+  #   parser = FrontmatterParser.new("name: my-skill\ndescription: A skill")
+  #   parser.call # => Frontmatter.new(name: "my-skill", description: "A skill", ...)
+  class FrontmatterParser
+    # @param yaml_string [String] YAML content (may be empty)
+    def initialize(yaml_string)
+      @yaml_string = yaml_string
+    end
+
+    # @return [Frontmatter] parsed frontmatter data
+    # @raise [Errors::Parser] if YAML is invalid
+    def call
+      return AgentSkillParser::NilFrontmatter if @yaml_string.empty?
+
+      data = parse_yaml
+      build_frontmatter(data)
+    rescue Psych::SyntaxError => e
+      raise Errors::Parser, "Invalid YAML: #{e.message}"
+    end
+
+    private
+
+    # @return [Hash] parsed YAML data
+    def parse_yaml
+      YAML.safe_load(@yaml_string) || {}
+    end
+
+    # @param data [Hash] raw YAML data
+    # @return [Frontmatter] constructed frontmatter
+    def build_frontmatter(data)
+      allowed_tools_data = data.delete("allowed-tools")
+      metadata_data = data.delete("metadata") || {}
+
+      Frontmatter.new(
+        name: data["name"] || "",
+        description: data["description"] || "",
+        license: data["license"],
+        compatibility: data["compatibility"],
+        metadata: coerce_metadata(metadata_data),
+        allowed_tools: parse_allowed_tools(allowed_tools_data)
+      )
+    end
+
+    # @param data [Object] metadata value
+    # @return [Hash{String => String}] stringified metadata
+    def coerce_metadata(data)
+      return {} unless data.is_a?(Hash)
+
+      data.transform_values(&:to_s).freeze
+    end
+
+    # @param data [String, Array, nil] allowed-tools value
+    # @return [Array<AllowedTool>] parsed tool list
+    def parse_allowed_tools(data)
+      return [] if data.nil? || data.empty?
+
+      case data
+      when String
+        AllowedToolsParser.new(data).call
+      when Array
+        data.flat_map { |item| AllowedToolsParser.new(item.to_s).call }.freeze
+      else
+        []
+      end
+    end
+  end
+end

data/lib/agent_skill_parser/parser.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module AgentSkillParser
+  # Main parser that orchestrates the parsing pipeline.
+  #
+  # Pipeline stages:
+  # 1. {DocumentSplitter} - Split YAML frontmatter from body
+  # 2. {FrontmatterParser} - Parse YAML into {Frontmatter}
+  # 3. {Validator} - Validate frontmatter schema
+  # 4. Construct {Skill} object
+  #
+  # @example Parse a skill file
+  #   parser = Parser.new("my_skill.md")
+  #   skill = parser.call
+  #   skill.name # => "my-skill"
+  #   skill.body # => "# My Skill..."
+  class Parser
+    # @param file_path [String] path to skill file
+    def initialize(file_path)
+      @file_path = file_path
+    end
+
+    # @return [Skill] parsed skill object
+    # @raise [Errors::Parser] if YAML is invalid or file cannot be read
+    # @raise [Errors::Validation] if frontmatter fails validation
+    # @raise [Errno::ENOENT] if file does not exist
+    def call
+      text = File.read(@file_path)
+      raw_yaml_document = DocumentSplitter.new(text).call
+
+      raise Errors::Parser, "Missing required YAML frontmatter" if raw_yaml_document.yaml_string.empty?
+
+      frontmatter = FrontmatterParser.new(raw_yaml_document.yaml_string).call
+      Validator.new(frontmatter).call
+
+      Skill.new(frontmatter: frontmatter, body: raw_yaml_document.body)
+    end
+  end
+end

data/lib/agent_skill_parser/skill.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module AgentSkillParser
+  # A parsed skill with frontmatter and body.
+  #
+  # @!attribute [r] frontmatter
+  #   @return [Frontmatter] parsed metadata
+  # @!attribute [r] body
+  #   @return [String] markdown content after frontmatter
+  #
+  # @example
+  #   Skill.new(
+  #     frontmatter: Frontmatter.new(name: "skill", description: "...", ...),
+  #     body: "# My Skill\n\n..."
+  #   )
+  Skill = Data.define(:frontmatter, :body) do
+    # @return [String] skill name (delegates to frontmatter)
+    # @see Frontmatter#name
+    def name
+      frontmatter.name
+    end
+
+    # @return [String] skill description (delegates to frontmatter)
+    # @see Frontmatter#description
+    def description
+      frontmatter.description
+    end
+  end
+end

data/lib/agent_skill_parser/validator.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module AgentSkillParser
+  # Validates frontmatter data against schema rules.
+  #
+  # @example Successful validation
+  #   fm = Frontmatter.new(name: "skill", description: "A skill", ...)
+  #   Validator.new(fm).call # => nil (no error)
+  #
+  # @example Failed validation
+  #   fm = Frontmatter.new(name: "Bad Name!", description: "...", ...)
+  #   Validator.new(fm).call # => raises Errors::Validation
+  #
+  # @see Errors::Validation
+  class Validator
+    # @return [Integer] maximum name length
+    NAME_MAX_LENGTH = 64
+    # @return [Integer] minimum name length
+    NAME_MIN_LENGTH = 1
+    # @return [Regexp] allowed name pattern
+    NAME_PATTERN = /\A[a-z0-9-]+\z/
+    # @return [Integer] maximum description length
+    DESCRIPTION_MAX_LENGTH = 1024
+    # @return [Integer] minimum description length
+    DESCRIPTION_MIN_LENGTH = 1
+    # @return [Integer] maximum compatibility length
+    COMPATIBILITY_MAX_LENGTH = 500
+
+    # @param frontmatter [Frontmatter] parsed frontmatter data
+    def initialize(frontmatter)
+      @frontmatter = frontmatter
+    end
+
+    # @return [void]
+    # @raise [Errors::Validation] if validation fails
+    def call
+      validate_name
+      validate_description
+      validate_compatibility
+    end
+
+    private
+
+    # @return [void]
+    # @raise [Errors::Validation] if name is invalid
+    def validate_name
+      name = @frontmatter.name
+
+      raise Errors::Validation, "Name must be at least #{NAME_MIN_LENGTH} character(s)" if name.length < NAME_MIN_LENGTH
+
+      raise Errors::Validation, "Name must be at most #{NAME_MAX_LENGTH} characters" if name.length > NAME_MAX_LENGTH
+
+      unless name.match?(NAME_PATTERN)
+        raise Errors::Validation, "Name must contain only lowercase letters, numbers, and hyphens"
+      end
+
+      raise Errors::Validation, "Name cannot contain consecutive hyphens" if name.include?("--")
+
+      return unless name.start_with?("-") || name.end_with?("-")
+
+      raise Errors::Validation, "Name cannot start or end with a hyphen"
+    end
+
+    # @return [void]
+    # @raise [Errors::Validation] if description is invalid
+    def validate_description
+      description = @frontmatter.description
+
+      if description.length < DESCRIPTION_MIN_LENGTH
+        raise Errors::Validation, "Description must be at least #{DESCRIPTION_MIN_LENGTH} character(s)"
+      end
+
+      return unless description.length > DESCRIPTION_MAX_LENGTH
+
+      raise Errors::Validation, "Description must be at most #{DESCRIPTION_MAX_LENGTH} characters"
+    end
+
+    # @return [void]
+    # @raise [Errors::Validation] if compatibility is too long
+    def validate_compatibility
+      return if @frontmatter.compatibility.nil?
+
+      return unless @frontmatter.compatibility.length > COMPATIBILITY_MAX_LENGTH
+
+      raise Errors::Validation, "Compatibility must be at most #{COMPATIBILITY_MAX_LENGTH} characters"
+    end
+  end
+end

data/lib/agent_skill_parser/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module AgentSkillParser
+  # @return [String] gem version
+  VERSION = "0.1.0"
+end

data/lib/agent_skill_parser.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "zeitwerk"
+require "yaml"
+
+loader = Zeitwerk::Loader.for_gem
+loader.setup
+
+# Parses skill files with YAML frontmatter and markdown body.
+#
+# Skill file format:
+# ```yaml
+# ---
+# name: my-skill
+# description: A helpful skill
+# license: MIT
+# compatibility: v1.2.3+
+# metadata:
+#   author: Alice
+# allowed-tools: bash, search_files(\.rb$)
+# ---
+# # My Skill
+#
+# Body content here...
+# ```
+#
+# @example Parse a skill file
+#   skill = AgentSkillParser.parse("my_skill.md")
+#   skill.name # => "my-skill"
+#   skill.description # => "A helpful skill"
+#
+# @example Handle errors
+#   begin
+#     AgentSkillParser.parse("invalid.md")
+#   rescue AgentSkillParser::Errors::Parser => e
+#     puts "Parse error: #{e.message}"
+#   rescue AgentSkillParser::Errors::Validation => e
+#     puts "Validation error: #{e.message}"
+#   end
+module AgentSkillParser
+  # @param file_path [String] path to skill file
+  # @return [Skill] parsed skill object
+  # @raise [Errors::Parser] if YAML is invalid or file cannot be read
+  # @raise [Errors::Validation] if frontmatter fails validation
+  # @raise [Errno::ENOENT] if file does not exist
+  # @see Parser#call
+  def self.parse(file_path)
+    Parser.new(file_path).call
+  end
+end

data/sig/agent_skill_parser.rbs

@@ -0,0 +1,4 @@
+module AgentSkillParser
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,83 @@
+--- !ruby/object:Gem::Specification
+name: agent_skill_parser
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Lucian Ghinda
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+description: A Ruby gem for parsing skill files that use YAML frontmatter and markdown
+  body content. Provides document splitting, YAML parsing, schema validation, and
+  returns immutable Skill objects. Designed for agent/AI systems where skills are
+  defined as structured markdown documents with metadata.
+email:
+- lucian@shortruby.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".yardopts"
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE
+- README.md
+- Rakefile
+- lib/agent_skill_parser.rb
+- lib/agent_skill_parser/allowed_tool.rb
+- lib/agent_skill_parser/allowed_tools_parser.rb
+- lib/agent_skill_parser/document_splitter.rb
+- lib/agent_skill_parser/errors.rb
+- lib/agent_skill_parser/errors/base.rb
+- lib/agent_skill_parser/errors/parser.rb
+- lib/agent_skill_parser/errors/validation.rb
+- lib/agent_skill_parser/frontmatter.rb
+- lib/agent_skill_parser/frontmatter_parser.rb
+- lib/agent_skill_parser/parser.rb
+- lib/agent_skill_parser/skill.rb
+- lib/agent_skill_parser/validator.rb
+- lib/agent_skill_parser/version.rb
+- sig/agent_skill_parser.rbs
+homepage: https://github.com/lucianghinda/agent_skill_parser
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/lucianghinda/agent_skill_parser
+  source_code_uri: https://github.com/lucianghinda/agent_skill_parser
+  changelog_uri: https://github.com/lucianghinda/agent_skill_parser/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: Parse agent skill files with YAML frontmatter and markdown body for agent/AI
+  systems
+test_files: []