agent-skills 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 246bc0cb05c79a7298244fe476e985567455e43c72cd7cce8b19664c2e41f926
+  data.tar.gz: 655771187b61554e981b79d68205e55d0ddd84ebf648548d810551d59938e649
+SHA512:
+  metadata.gz: 30d4fb083c05513469fd848e2ba33c0138f014fdf925a05ca96aaabfb78f17de80818baf39ca3dae0d94f28ef98feccbb9855a0ef95850799370ec2b193ae0f5
+  data.tar.gz: 0a30bf86be55f17b9add3ecfe378504aa8afa8c11f08a7f564f993e60b24c1be53a25307fc12f8b762bb0fa89f6840fa5c592cb8a861f36e73b9a2f9f93f53dd

data/bake/agent/skills.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Shopify Inc.
+# Copyright, 2025-2026, by Samuel Williams.
+
+require_relative "../../lib/agent/skills/installer"
+
+include Agent::Skills
+
+def initialize(context)
+	super(context)
+	
+	@installer = Installer.new(root: context.root)
+end
+
+attr :installer
+
+# List gems and the skills they provide.
+# @parameter gem [String] Optional gem name to inspect.
+def list(gem: nil)
+	if gem
+		skills = @installer.list_skills(gem)
+		if skills
+			puts "Skills provided by gem '#{gem}':"
+			skills.each do |skill|
+				puts "  #{skill.name} - #{skill.description}"
+			end
+		else
+			puts "No skills found for gem '#{gem}'"
+		end
+	else
+		gems = @installer.find_gems_with_skills
+		if gems.any?
+			puts "Gems with skills available:"
+			gems.each do |gem_information|
+				names = gem_information[:skills].map(&:name).join(", ")
+				puts "  #{gem_information[:name]} (#{gem_information[:version]}): #{names}"
+			end
+		else
+			puts "No gems with skills found"
+		end
+	end
+end
+
+# Show the `SKILL.md` content for a provided skill.
+# @parameter gem [String] The provider gem name.
+# @parameter skill [String] The skill name.
+def show(gem:, skill:)
+	content = @installer.show_skill(gem, skill)
+	if content
+		puts content
+	else
+		puts "Skill '#{skill}' not found in gem '#{gem}'"
+	end
+end
+
+# Install skills from gems into `.agents/skills`.
+# @parameter gem [String] Optional gem name to install from.
+def install(gem: nil)
+	if gem
+		installed = @installer.install_gem_skills(gem)
+		if installed
+			puts "Installed #{installed.length} skills from gem '#{gem}':"
+			installed.each {|skill_name| puts "  #{skill_name}"}
+		else
+			puts "No skills found for gem '#{gem}'"
+		end
+	else
+		installed = @installer.install_all_skills
+		if installed.any?
+			puts "Installed #{installed.length} skills:"
+			installed.each {|skill_name| puts "  #{skill_name}"}
+		else
+			puts "No gems with skills found"
+		end
+	end
+end

data/context/getting-started.md

@@ -0,0 +1,71 @@
+# Getting Started with Agent Skills
+
+This guide explains how to discover, inspect, and install agent skills provided by Ruby gems.
+
+## Installation
+
+Add `agent-skills` to the consuming project:
+
+```bash
+$ bundle add agent-skills
+```
+
+List the skills available from installed gems:
+
+```bash
+$ bundle exec bake agent:skills:list
+```
+
+Install them into the project:
+
+```bash
+$ bundle exec bake agent:skills:install
+```
+
+## Source and Destination Directories
+
+Provider gems publish skills beneath `skills/`:
+
+```text
+provider-gem/
+└── skills/
+    └── ruby-testing/
+        ├── SKILL.md
+        ├── references/
+        └── scripts/
+```
+
+The consuming project receives them beneath `.agents/skills/`:
+
+```text
+consumer-project/
+└── .agents/
+    └── skills/
+        ├── ruby-testing/
+        └── .agent-skills.yaml
+```
+
+## Providing a Skill
+
+Create a directory beneath your gem's top-level `skills/` directory. Add a `SKILL.md` file with required frontmatter:
+
+```markdown
+---
+name: ruby-testing
+description: Test Ruby changes with the project's configured test framework.
+---
+
+# Ruby Testing
+
+Run the narrowest relevant test first, then run the complete suite.
+```
+
+The `name` must match the containing directory. Include the complete `skills/**/*` tree in the gemspec.
+
+## Installation Ownership
+
+`agent-skills` writes `.agents/skills/.agent-skills.yaml` to record which gem owns each installed skill. It will update skills owned by the same gem, but refuses to overwrite unmanaged skills or skills owned by another gem.
+
+## Safety
+
+Skills may contain scripts and operational instructions. Inspect skills with `bake agent:skills:list` and `bake agent:skills:show` before installation when evaluating an unfamiliar dependency.

data/context/index.yaml

@@ -0,0 +1,10 @@
+---
+description: Install and manage agent skills from Ruby gems.
+metadata:
+  documentation_uri: https://socketry.github.io/agent-skills/
+  funding_uri: https://github.com/sponsors/ioquatix/
+  source_code_uri: https://github.com/socketry/agent-skills.git
+files:
+- path: getting-started.md
+  title: Getting Started with Agent Skills
+  description: Discover, inspect, and install agent skills provided by Ruby gems.

data/lib/agent/skills/definition.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Shopify Inc.
+# Copyright, 2025-2026, by Samuel Williams.
+
+module Agent
+	module Skills
+		# A validated skill discovered in a provider gem.
+		class Definition
+			# Initialize a skill definition.
+			#
+			# @parameter name [String] The declared skill name.
+			# @parameter description [String] A short description used for skill discovery.
+			# @parameter path [String] The source directory containing `SKILL.md`.
+			# @parameter provider_name [String] The source gem name.
+			# @parameter provider_version [String] The source gem version.
+			def initialize(name:, description:, path:, provider_name:, provider_version:)
+				@name = name
+				@description = description
+				@path = path
+				@provider_name = provider_name
+				@provider_version = provider_version
+			end
+			
+			attr_reader :name
+			attr_reader :description
+			attr_reader :path
+			attr_reader :provider_name
+			attr_reader :provider_version
+			
+			# The path to the skill's required instruction file.
+			def skill_file
+				File.join(@path, "SKILL.md")
+			end
+		end
+	end
+end

data/lib/agent/skills/installer.rb

@@ -0,0 +1,254 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Shopify Inc.
+# Copyright, 2025-2026, by Samuel Williams.
+
+require "fileutils"
+require "rubygems"
+require "yaml"
+
+require_relative "definition"
+require_relative "registry"
+
+module Agent
+	module Skills
+		# Discovers and installs skills provided by Ruby gems.
+		class Installer
+			NAME_PATTERN = Registry::NAME_PATTERN
+			MAXIMUM_NAME_LENGTH = 100
+			MAXIMUM_DESCRIPTION_LENGTH = 500
+			
+			# Base error for skill discovery and installation failures.
+			class Error < StandardError
+			end
+			
+			# Raised when a provider contains an invalid skill.
+			class InvalidSkill < Error
+			end
+			
+			# Raised when a skill would overwrite content owned by another source.
+			class Conflict < Error
+			end
+			
+			# Initialize a skill installer.
+			#
+			# @parameter root [String] The consuming project root.
+			# @parameter specifications [Gem::Specification] The gem specifications to scan.
+			def initialize(root: Dir.pwd, specifications: ::Gem::Specification)
+				@root = File.expand_path(root)
+				@skills_path = File.join(@root, ".agents", "skills")
+				@specifications = specifications
+			end
+			
+			attr_reader :root
+			attr_reader :skills_path
+			
+			# Find installed gems which provide one or more valid skills.
+			#
+			# @parameter skip_local [Boolean] Whether to skip a gem loaded from the consuming project root.
+			def find_gems_with_skills(skip_local: true)
+				@specifications.filter_map do |specification|
+					next if skip_local && same_path?(specification.full_gem_path, @root)
+					
+					build_gem_information(specification)
+				end
+			end
+			
+			# Find a named gem which provides skills.
+			#
+			# @parameter gem_name [String] The gem name to find.
+			def find_gem_with_skills(gem_name)
+				specification = @specifications.find {|candidate| candidate.name == gem_name}
+				return unless specification
+				
+				build_gem_information(specification)
+			end
+			
+			# List skills provided by a named gem.
+			#
+			# @parameter gem_name [String] The gem name.
+			def list_skills(gem_name)
+				gem = find_gem_with_skills(gem_name)
+				gem && gem[:skills]
+			end
+			
+			# Read the instruction file for a skill provided by a gem.
+			#
+			# @parameter gem_name [String] The provider gem name.
+			# @parameter skill_name [String] The declared skill name.
+			def show_skill(gem_name, skill_name)
+				skills = list_skills(gem_name)
+				return unless skills
+				
+				definition = skills.find {|skill| skill.name == skill_name}
+				File.read(definition.skill_file) if definition
+			end
+			
+			# Install all skills provided by a named gem.
+			#
+			# @parameter gem_name [String] The provider gem name.
+			# @returns [Array(String), nil] Installed skill names, or `nil` if the gem provides no skills.
+			def install_gem_skills(gem_name)
+				gem = find_gem_with_skills(gem_name)
+				return unless gem
+				
+				install_gems([gem])
+			end
+			
+			# Install skills from every discovered gem.
+			#
+			# @parameter skip_local [Boolean] Whether to skip a gem loaded from the consuming project root.
+			# @returns [Array(String)] Installed skill names.
+			def install_all_skills(skip_local: true)
+				install_gems(find_gems_with_skills(skip_local: skip_local))
+			end
+			
+			private
+			
+			def build_gem_information(specification)
+				source_path = File.join(specification.full_gem_path, "skills")
+				return unless Dir.exist?(source_path)
+				
+				skills = discover_skills(source_path, specification.name, specification.version.to_s)
+				return if skills.empty?
+				
+				{
+					name: specification.name,
+					version: specification.version.to_s,
+					summary: specification.summary,
+					metadata: specification.metadata,
+					path: source_path,
+					skills: skills,
+				}
+			end
+			
+			def discover_skills(source_path, provider_name, provider_version)
+				Dir.children(source_path).sort.filter_map do |entry|
+					skill_path = File.join(source_path, entry)
+					next unless File.directory?(skill_path)
+					
+					skill_file = File.join(skill_path, "SKILL.md")
+					next unless File.file?(skill_file)
+					
+					metadata = load_skill_metadata(skill_file)
+					validate_skill_metadata(metadata, entry, skill_file)
+					
+					Definition.new(
+						name: metadata["name"],
+						description: metadata["description"],
+						path: skill_path,
+						provider_name: provider_name,
+						provider_version: provider_version,
+					)
+				end
+			end
+			
+			def load_skill_metadata(skill_file)
+				content = File.read(skill_file)
+				match = content.match(/\A---\s*\n(.*?)\n---\s*(?:\n|\z)/m)
+				
+				unless match
+					raise InvalidSkill, "Skill must begin with YAML frontmatter: #{skill_file}"
+				end
+				
+				metadata = YAML.safe_load(match[1], aliases: false)
+				unless metadata.is_a?(Hash)
+					raise InvalidSkill, "Skill frontmatter must be a mapping: #{skill_file}"
+				end
+				
+				metadata
+			rescue Psych::Exception => error
+				raise InvalidSkill, "Invalid skill frontmatter in #{skill_file}: #{error.message}"
+			end
+			
+			def validate_skill_metadata(metadata, directory_name, skill_file)
+				name = metadata["name"]
+				description = metadata["description"]
+				
+				unless name.is_a?(String) && name.match?(NAME_PATTERN) && name.length <= MAXIMUM_NAME_LENGTH
+					raise InvalidSkill, "Invalid skill name in #{skill_file}: #{name.inspect}"
+				end
+				
+				unless name == directory_name
+					raise InvalidSkill, "Skill name #{name.inspect} must match its directory #{directory_name.inspect}"
+				end
+				
+				unless description.is_a?(String) && !description.strip.empty? && description.length <= MAXIMUM_DESCRIPTION_LENGTH
+					raise InvalidSkill, "Invalid skill description in #{skill_file}"
+				end
+			end
+			
+			def install_gems(gems)
+				definitions = gems.flat_map {|gem| gem[:skills]}
+				return [] if definitions.empty?
+				
+				validate_unique_skills(definitions)
+				
+				registry = Registry.new(File.join(@skills_path, Registry::FILE_NAME))
+				definitions.each {|definition| validate_destination(definition, registry)}
+				
+				stale_skills = gems.flat_map do |gem|
+					current_names = gem[:skills].map(&:name)
+					registry.skills_for(gem[:name]).keys - current_names
+				end
+				
+				definitions.each do |definition|
+					registry.claim(definition.name, definition.provider_name, definition.provider_version)
+				end
+				stale_skills.each {|skill_name| registry.release(skill_name)}
+				registry.save
+				
+				definitions.each {|definition| copy_skill(definition)}
+				stale_skills.each {|skill_name| remove_skill(skill_name)}
+				
+				definitions.map(&:name)
+			end
+			
+			def validate_unique_skills(definitions)
+				duplicates = definitions.group_by(&:name).select {|_name, matches| matches.length > 1}
+				return if duplicates.empty?
+				
+				details = duplicates.map do |name, matches|
+					providers = matches.map(&:provider_name).uniq.join(", ")
+					"#{name} (#{providers})"
+				end
+				
+				raise Conflict, "Multiple gems provide the same skill: #{details.join('; ')}"
+			end
+			
+			def validate_destination(definition, registry)
+				destination = File.join(@skills_path, definition.name)
+				owner = registry.owner(definition.name)
+				
+				if owner && owner["gem"] != definition.provider_name
+					raise Conflict, "Skill #{definition.name.inspect} is owned by gem #{owner['gem'].inspect}"
+				end
+				
+				if path_exists?(destination) && !owner
+					raise Conflict, "Skill #{definition.name.inspect} already exists and is not managed by agent-skills"
+				end
+			end
+			
+			def copy_skill(definition)
+				FileUtils.mkdir_p(@skills_path)
+				destination = File.join(@skills_path, definition.name)
+				FileUtils.rm_rf(destination) if path_exists?(destination)
+				FileUtils.cp_r(definition.path, destination, preserve: true)
+			end
+			
+			def remove_skill(skill_name)
+				destination = File.join(@skills_path, skill_name)
+				FileUtils.rm_rf(destination) if path_exists?(destination)
+			end
+			
+			def path_exists?(path)
+				File.exist?(path) || File.symlink?(path)
+			end
+			
+			def same_path?(left, right)
+				File.expand_path(left) == File.expand_path(right)
+			end
+		end
+	end
+end

data/lib/agent/skills/registry.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Shopify Inc.
+# Copyright, 2025-2026, by Samuel Williams.
+
+require "fileutils"
+require "yaml"
+
+module Agent
+	module Skills
+		# Tracks which installed skills are owned by which gems.
+		class Registry
+			FILE_NAME = ".agent-skills.yaml"
+			FORMAT_VERSION = 1
+			NAME_PATTERN = /\A[a-z0-9]+(?:-[a-z0-9]+)*\z/
+			
+			# Raised when the registry cannot be safely interpreted.
+			class Invalid < StandardError
+			end
+			
+			# Initialize a registry stored at the given path.
+			#
+			# @parameter path [String] The registry file path.
+			def initialize(path)
+				@path = path
+				@data = load_data
+			end
+			
+			attr_reader :path
+			
+			# Get ownership metadata for a skill.
+			#
+			# @parameter skill_name [String] The installed skill name.
+			def owner(skill_name)
+				@data["skills"][skill_name]
+			end
+			
+			# Get all skills owned by a gem.
+			#
+			# @parameter gem_name [String] The provider gem name.
+			def skills_for(gem_name)
+				@data["skills"].select do |_skill_name, owner|
+					owner["gem"] == gem_name
+				end
+			end
+			
+			# Record ownership of an installed skill.
+			#
+			# @parameter skill_name [String] The installed skill name.
+			# @parameter gem_name [String] The provider gem name.
+			# @parameter gem_version [String] The provider gem version.
+			def claim(skill_name, gem_name, gem_version)
+				@data["skills"][skill_name] = {
+					"gem" => gem_name,
+					"version" => gem_version,
+				}
+			end
+			
+			# Remove ownership information for a skill.
+			#
+			# @parameter skill_name [String] The installed skill name.
+			def release(skill_name)
+				@data["skills"].delete(skill_name)
+			end
+			
+			# Persist the registry atomically.
+			def save
+				FileUtils.mkdir_p(File.dirname(@path))
+				
+				content = {
+					"version" => FORMAT_VERSION,
+					"skills" => @data["skills"].sort.to_h,
+				}.to_yaml
+				
+				temporary_path = "#{@path}.#{Process.pid}.tmp"
+				File.write(temporary_path, content)
+				File.rename(temporary_path, @path)
+			ensure
+				FileUtils.rm_f(temporary_path) if temporary_path
+			end
+			
+			private
+			
+			def load_data
+				return default_data unless File.exist?(@path)
+				
+				data = YAML.safe_load(File.read(@path), aliases: false)
+				validate_data(data)
+				data
+			rescue Psych::Exception => error
+				raise Invalid, "Could not load skill registry #{@path}: #{error.message}"
+			end
+			
+			def validate_data(data)
+				unless data.is_a?(Hash) && data["version"] == FORMAT_VERSION && data["skills"].is_a?(Hash)
+					raise Invalid, "Invalid skill registry format: #{@path}"
+				end
+				
+				data["skills"].each do |skill_name, owner|
+					unless skill_name.is_a?(String) && skill_name.match?(NAME_PATTERN)
+						raise Invalid, "Invalid skill name in registry: #{skill_name.inspect}"
+					end
+					
+					unless owner.is_a?(Hash) && owner["gem"].is_a?(String) && owner["version"].is_a?(String)
+						raise Invalid, "Invalid owner for skill #{skill_name.inspect}"
+					end
+				end
+			end
+			
+			def default_data
+				{
+					"version" => FORMAT_VERSION,
+					"skills" => {},
+				}
+			end
+		end
+	end
+end

data/lib/agent/skills/version.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Shopify Inc.
+# Copyright, 2025-2026, by Samuel Williams.
+
+module Agent
+	module Skills
+		VERSION = "0.0.1"
+	end
+end

data/lib/agent/skills.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Shopify Inc.
+# Copyright, 2025-2026, by Samuel Williams.
+
+require_relative "skill/version"
+require_relative "skill/definition"
+require_relative "skill/registry"
+require_relative "skill/installer"
+
+# @namespace
+module Agent
+	# Tools for discovering and installing agent skills from Ruby gems.
+	module Skills
+	end
+end

data/license.md

@@ -0,0 +1,22 @@
+# MIT License
+
+Copyright, 2025, by Shopify Inc.  
+Copyright, 2025-2026, by Samuel Williams.  
+
+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,112 @@
+# Agent Skills
+
+Provides tools for discovering and installing agent skills distributed by Ruby gems.
+
+[![Development Status](https://github.com/socketry/agent-skills/workflows/Test/badge.svg)](https://github.com/socketry/agent-skills/actions?workflow=Test)
+
+## Overview
+
+Ruby gems can provide reusable agent workflows in a top-level `skills/` directory. `agent-skills` discovers those packages and installs them into the consuming project's `.agents/skills/` directory.
+
+Installed skills are copied into the project so they can be used independently of the provider gem's installation path.
+
+## Quick Start
+
+Add the gem to your project:
+
+``` bash
+$ bundle add agent-skills
+```
+
+List available skills:
+
+``` bash
+$ bundle exec bake agent:skills:list
+```
+
+Install all available skills:
+
+``` bash
+$ bundle exec bake agent:skills:install
+```
+
+Install skills from a specific gem:
+
+``` bash
+$ bundle exec bake agent:skills:install --gem sus
+```
+
+## Providing Skills in a Gem
+
+Create a top-level `skills/` directory containing one directory per skill:
+
+``` text
+your-gem/
+├── skills/
+│   └── ruby-testing/
+│       ├── SKILL.md
+│       ├── scripts/
+│       ├── references/
+│       └── assets/
+├── lib/
+└── your-gem.gemspec
+```
+
+Each `SKILL.md` begins with YAML frontmatter:
+
+``` markdown
+---
+name: ruby-testing
+description: Test Ruby projects using the project's configured test framework.
+---
+
+# Ruby Testing
+
+Read the project instructions and run the narrowest relevant tests first.
+```
+
+The declared `name` must match its containing directory. Ensure `skills/**/*` is included in the gem's packaged files.
+
+## Installation Safety
+
+The installer records gem-owned skills in `.agents/skills/.agent-skills.yaml`.
+
+  - Existing project-authored skills are never overwritten.
+  - Different gems cannot install the same skill name.
+  - A gem can update or remove only skills previously recorded as belonging to that gem.
+  - Invalid `SKILL.md` metadata stops installation with an error.
+
+Skills may include scripts and operational instructions. Review the skills supplied by dependencies before installing them.
+
+The generated `.agents/` directory should be excluded from version control. Run installation during project setup and in CI when skills are required.
+
+## Commands
+
+``` bash
+# List every gem which provides skills:
+bake agent:skills:list
+
+# List skills from one gem:
+bake agent:skills:list --gem sus
+
+# Show a skill's SKILL.md:
+bake agent:skills:show --gem sus --skill ruby-testing
+
+# Install all discovered skills:
+bake agent:skills:install
+
+# Install skills from one gem:
+bake agent:skills:install --gem sus
+```
+
+## Context
+
+This gem provides contextual documentation in `context/` for use with [`agent-context`](https://github.com/socketry/agent-context).
+
+## Contributing
+
+We welcome contributions. Please add tests for behavioral changes and run the test suite before opening a pull request.
+
+### Developer Certificate of Origin
+
+Contributors must comply with the [Developer Certificate of Origin](https://developercertificate.org/).

data/releases.md

@@ -0,0 +1,7 @@
+# Releases
+
+## v0.0.0
+
+  - Initial release.
+  - Discover and validate skills provided by Ruby gems.
+  - Install project-scoped skills with ownership and collision protection.

data/specification.md

@@ -0,0 +1,101 @@
+# Agent Skills Packaging Specification
+
+## 1. Purpose
+
+This specification defines how Ruby gems can distribute reusable agent skills and how consuming projects install those skills.
+
+The packaging convention complements the Agent Skills format: it describes transport through Ruby gems, ownership, and installation without redefining the internal semantics of a skill.
+
+## 2. Provider Layout
+
+A provider gem MUST place skills in a top-level `skills/` directory. Each immediate child directory represents one skill and MUST contain `SKILL.md`.
+
+```text
+package-root/
+├── skills/
+│   ├── first-skill/
+│   │   ├── SKILL.md
+│   │   └── references/
+│   └── second-skill/
+│       ├── SKILL.md
+│       └── scripts/
+├── lib/
+└── package.gemspec
+```
+
+The provider MUST include the complete `skills/` tree in the packaged gem.
+
+## 3. Skill Metadata
+
+`SKILL.md` MUST begin with YAML frontmatter containing:
+
+- `name`: A lowercase, hyphen-separated identifier.
+- `description`: A concise explanation of when the skill applies.
+
+The declared `name` MUST match the name of the skill directory.
+
+Additional metadata MAY be present and is preserved as part of the installed skill.
+
+## 4. Consumer Layout
+
+Skills are installed into `.agents/skills/` at the consuming project root:
+
+```text
+project-root/
+└── .agents/
+    └── skills/
+        ├── first-skill/
+        ├── second-skill/
+        └── .agent-skills.yaml
+```
+
+Skills are installed directly beneath `.agents/skills/` because skill names form a shared project-level namespace.
+
+## 5. Discovery
+
+An installer discovers provider gems by:
+
+1. Enumerating installed Ruby gem specifications.
+2. Finding top-level `skills/` directories.
+3. Finding immediate child directories containing `SKILL.md`.
+4. Parsing and validating required frontmatter.
+
+Directories without `SKILL.md` are not considered skills.
+
+## 6. Installation
+
+Installation MUST copy the entire skill directory and preserve its internal structure.
+
+Before modifying the destination, the installer MUST verify that:
+
+- No other provider in the same operation supplies the same skill name.
+- An existing destination is recorded as belonging to the same provider.
+- A project-authored or otherwise unmanaged destination will not be overwritten.
+
+When a provider is reinstalled, skills formerly owned by that provider but no longer present MAY be removed.
+
+## 7. Ownership Registry
+
+The `.agents/skills/.agent-skills.yaml` file records installed skill ownership. Its initial format is:
+
+```yaml
+version: 1
+skills:
+  ruby-testing:
+    gem: sus
+    version: 1.0.0
+```
+
+The registry MUST NOT claim ownership of pre-existing project-authored skills.
+
+## 8. Security
+
+Skills can contain scripts and instructions which cause agents to execute commands or modify files. Installation SHOULD therefore be an explicit project action.
+
+Consumers SHOULD review provider skills and dependency changes before installation. Installers MUST reject ambiguous ownership rather than selecting a provider implicitly.
+
+## 9. Version Control
+
+Projects SHOULD exclude the generated `.agents/` directory from version control and run installation as part of setup and CI when skills are required.
+
+Installed skills and the ownership registry MUST contain only reproducible content which can be regenerated from installed packages.

metadata

@@ -0,0 +1,67 @@
+--- !ruby/object:Gem::Specification
+name: agent-skills
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Samuel Williams
+- Shopify Inc.
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.23'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.23'
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- bake/agent/skills.rb
+- context/getting-started.md
+- context/index.yaml
+- lib/agent/skills.rb
+- lib/agent/skills/definition.rb
+- lib/agent/skills/installer.rb
+- lib/agent/skills/registry.rb
+- lib/agent/skills/version.rb
+- license.md
+- readme.md
+- releases.md
+- specification.md
+homepage: https://github.com/socketry/agent-skills
+licenses:
+- MIT
+metadata:
+  documentation_uri: https://socketry.github.io/agent-skills/
+  funding_uri: https://github.com/sponsors/ioquatix/
+  source_code_uri: https://github.com/socketry/agent-skills.git
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: Install and manage agent skills from Ruby gems.
+test_files: []