agent-context 0.3.0 → 0.4.0

data/lib/agent/context/skills/definition.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Shopify Inc.
+
+require "fileutils"
+require_relative "../definition"
+require_relative "../errors"
+require_relative "ownership"
+
+module Agent
+	module Context
+		module Skills
+			# Represents a dependency skill declared by a context document and its resources.
+			class Definition < Agent::Context::Definition
+				# Build instructions from a parsed skill document and its provider.
+				def self.from_document(source, specification)
+					# Preserve authored names and derive missing names from the provider and file:
+					file = source.path
+					local_name = File.basename(file, File.extname(file))
+					installed_name = source.frontmatter.fetch("name"){"#{specification.name.downcase.tr("_", "-")}-#{local_name}"}
+					
+					# Add the resolved provider identity to the authored front matter:
+					frontmatter = source.frontmatter.merge("name" => installed_name)
+					frontmatter["metadata"] = source.metadata.merge(
+						"ecosystem" => "gem",
+						"package" => specification.name,
+						"version" => specification.version.to_s,
+					)
+					validate_metadata(frontmatter, file)
+					
+					# Resolve resources using the source filename:
+					assets = File.join(File.dirname(file), local_name)
+					if File.exist?(assets) || File.symlink?(assets)
+						unless File.lstat(assets).directory?
+							raise InvalidError, "Skill resources must be a regular directory: #{assets}"
+						end
+					else
+						assets = nil
+					end
+					
+					installation_content = source.render(frontmatter)
+					
+					new(source, specification, installed_name, frontmatter["description"], assets, installation_content)
+				end
+				
+				# Validate an installed directory name.
+				def self.validate_name(name, file)
+					unless name.is_a?(String) && name.match?(Ownership::NAME_PATTERN) && name.length <= 64
+						raise InvalidError, "Invalid skill name in #{file}: #{name.inspect}"
+					end
+				end
+				
+				# Validate the required authored skill fields.
+				def self.validate_metadata(frontmatter, file)
+					validate_name(frontmatter["name"], file)
+					
+					description = frontmatter["description"]
+					unless description.is_a?(String)
+						raise InvalidError, "Invalid skill description in #{file}"
+					end
+					
+					description = description.strip
+					if description.empty? || description.length > 1024
+						raise InvalidError, "Invalid skill description in #{file}"
+					end
+				end
+				
+				# Retain the source document, specification, and prepared skill instructions.
+				def initialize(document, specification, name, description, resources, installation_content)
+					super(File.basename(document.path), document.path, document)
+					@specification = specification
+					@name = name
+					@description = description
+					@resources = resources
+					@installation_content = installation_content
+				end
+				
+				# @attribute [Gem::Specification] The resolved package specification.
+				attr_reader :specification
+				
+				# @attribute [String] The installed skill name.
+				attr_reader :name
+				
+				# @attribute [String] When to use the skill.
+				attr_reader :description
+				
+				# @attribute [String | Nil] The companion resource directory.
+				attr_reader :resources
+				
+				# @attribute [String] The generated instructions with resolved provenance.
+				attr_reader :installation_content
+				
+				# Whether this definition installs as an Agent Skill.
+				# @returns [bool] `true` for skill definitions.
+				def skill?
+					true
+				end
+				
+				# Return the filename shown by the context list with its skill marker.
+				# @returns [String] The source filename and skill marker.
+				def display_name
+					"#{File.basename(@path, File.extname(@path))} (skill)"
+				end
+				
+				# Write instructions before resources so ownership is available during refresh.
+				# @parameter destination [String] The installed skill directory.
+				def install(destination)
+					FileUtils.mkdir_p(destination)
+					begin
+						File.write(File.join(destination, "SKILL.md"), @installation_content)
+					rescue
+						FileUtils.rm_rf(destination)
+						raise
+					end
+					copy_resources(@resources, destination, true) if @resources
+				end
+				
+				private
+				
+				def copy_resources(source, destination, top_level)
+					Dir.children(source).sort.each do |name|
+						from = File.join(source, name)
+						to = File.join(destination, name)
+						metadata = File.lstat(from)
+						
+						if metadata.symlink? || (!metadata.file? && !metadata.directory?)
+							raise InvalidError, "Skill resources must be regular files or directories: #{from}"
+						end
+						
+						if top_level && name.downcase == "skill.md"
+							raise InvalidError, "#{name} is reserved for generated skill files: #{from}"
+						end
+						
+						if metadata.directory?
+							FileUtils.mkdir_p(to)
+							copy_resources(from, to, false)
+						else
+							FileUtils.copy_file(from, to, true)
+						end
+					end
+				end
+			end
+		end
+	end
+end

data/lib/agent/context/skills/ownership.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Shopify Inc.
+
+require_relative "../document"
+require_relative "../errors"
+
+module Agent
+	module Context
+		module Skills
+			# Represents installation ownership recorded in each skill directory.
+			class Ownership
+				FILE_NAME = "SKILL.md"
+				NAME_PATTERN = /\A[a-z0-9]+(?:-[a-z0-9]+)*\z/
+				
+				# Read a skill's installation ownership.
+				# @parameter directory [String] The installed skill directory.
+				# @returns [Hash | Nil] Ownership when the skill has an installation record.
+				def self.load(directory)
+					path = File.join(directory, FILE_NAME)
+					
+					begin
+						stat = File.lstat(path)
+					rescue Errno::ENOENT
+						return
+					end
+					
+					raise InvalidError, "Skill ownership must be a regular file: #{path}" unless stat.file?
+					
+					metadata = Document.load(path).metadata
+					fields = ["ecosystem", "package", "version"]
+					return unless metadata["type"] == "skill" && metadata.key?("ecosystem")
+					
+					unless fields.all?{|field| metadata[field].is_a?(String) && !metadata[field].strip.empty?}
+						raise InvalidError, "Invalid skill ownership: #{path}"
+					end
+					
+					metadata.slice(*fields)
+				end
+				
+				# Collect ownership from installed skill directories.
+				# @parameter directory [String] The installed skills root.
+				# @returns [Hash(String, Hash)] Skill names and their installation records.
+				def self.scan(directory)
+					begin
+						stat = File.lstat(directory)
+					rescue Errno::ENOENT
+						return {}
+					end
+					
+					raise InvalidError, "Skill installation path must be a regular directory: #{directory}" unless stat.directory?
+					
+					Dir.children(directory).sort.each_with_object({}) do |name, owners|
+						path = File.join(directory, name)
+						next unless File.lstat(path).directory?
+						next unless owner = load(path)
+						
+						unless name.match?(NAME_PATTERN) && name.length <= 64
+							raise InvalidError, "Invalid installed skill name: #{name.inspect}"
+						end
+						
+						owners[name] = owner
+					end
+				end
+			end
+		end
+	end
+end

data/lib/agent/context/skills.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Shopify Inc.
+
+require_relative "skills/definition"
+require_relative "skills/ownership"
+
+module Agent
+	module Context
+		# Skill definitions and installation ownership for dependency context.
+		module Skills
+		end
+	end
+end

data/lib/agent/context/version.rb

@@ -6,6 +6,6 @@
 
 module Agent
 	module Context
-		VERSION = "0.3.0"
+		VERSION = "0.4.0"
 	end
 end 

data/lib/agent/context.rb

@@ -1,12 +1,13 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2025, by Shopify Inc.
+# Copyright, 2025-2026, by Shopify Inc.
 # Copyright, 2025, by Samuel Williams.
 
 require_relative "context/version"
+require_relative "context/paths"
+require_relative "context/skills"
 require_relative "context/installer"
-require_relative "context/index"
 
 # @namespace
 module Agent

data/license.md

@@ -1,7 +1,7 @@
 # MIT License
 
-Copyright, 2025, by Shopify Inc.  
-Copyright, 2025, by Samuel Williams.  
+Copyright, 2025-2026, 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

data/post.md

@@ -1,5 +1,7 @@
 # Ruby and Claude's Great Adventure: How We Made Gems AI-Friendly
 
+This article describes the original release. See the [current usage guide](guides/getting-started/readme.md) for dependency context and skill installation.
+
 *Once upon a time, in the bustling world of software development, Ruby and Claude were having a conversation that would change everything...*
 
 ## The Problem: A Tale of Miscommunication
@@ -28,7 +30,7 @@
 
 **Claude:** "So how does this work in practice?"
 
-**Ruby:** "Let me show you! When a developer runs `bake agent:context:install`, it scans all my installed gems for `context/` directories, copies the files to a `.context/` folder in their project, and generates an `agents.md` file that gives you a comprehensive overview."
+**Ruby:** "Let me show you! When a developer runs `bake agent:context:install`, it scans all my installed gems for `context/` directories, copies the files to a `.agents/context/` folder in their project, and generates an `agents.md` file that gives you a comprehensive overview."
 
 **Claude:** "That sounds perfect! What does this `agents.md` file look like?"
 
@@ -45,7 +47,7 @@ Context files from installed gems providing documentation and guidance for AI ag
 
 Code analysis for documentation generation.
 
-#### [Getting Started with Decode](.context/decode/getting-started.md)
+#### [Getting Started with Decode](.agents/context/decode/getting-started.md)
 
 The Decode gem provides programmatic access to Ruby code structure...
 
@@ -53,7 +55,7 @@ The Decode gem provides programmatic access to Ruby code structure...
 
 A fast and scalable test runner.
 
-#### [Using Sus Testing Framework](.context/sus/usage.md)
+#### [Using Sus Testing Framework](.agents/context/sus/usage.md)
 
 Sus is a modern Ruby testing framework...
 ```

data/readme.md

@@ -1,14 +1,14 @@
 # Agent::Context
 
-Provides tools for installing and managing context files from Ruby gems for AI agents, and generating `agents.md` files following the <https://agents.md> specification.
+Provides tools for installing and managing context files and skills from Ruby gems for AI agents.
 
-[![Development Status](https://github.com/ioquatix/agent-context/workflows/Test/badge.svg)](https://github.com/ioquatix/agent-context/actions?workflow=Test)
+[![Development Status](https://github.com/socketry/agent-context/workflows/Test/badge.svg)](https://github.com/socketry/agent-context/actions?workflow=Test)
 
 ## Overview
 
 This gem allows you to install and manage context files from other gems. Gems can provide context files in a `context/` directory in their root, which can contain documentation, configuration examples, migration guides, and other contextual information for AI agents.
 
-When you install context from gems, they are placed in the `.context/` directory and an `agents.md` file is generated or updated to provide a comprehensive overview for AI agents.
+When you install context from gems, ordinary guides are placed in `.agents/context/` and dependency skills in `.agents/skills/`. Browse `.agents/context/GEM/` or use the list/show commands to find relevant guides.
 
 ## Quick Start
 
@@ -22,23 +22,23 @@ $ bake agent:context:install
 This workflow:
 
   - Adds the `agent-context` gem to your project.
-  - Installs context files from all gems into `.context/`.
-  - Generates or updates `agents.md` with a comprehensive overview.
-  - Follows the <https://agents.md> specification for agentic coding tools.
+  - Installs context files from all gems into `.agents/context/`.
+  - Installs metadata-declared skills into `.agents/skills/`.
 
 ## Context
 
 This gem provides its own context files in the `context/` directory, including:
 
-  - `usage.md` - Comprehensive guide for using and providing context files.
+  - `getting-started.md` - Comprehensive guide for using and providing context files and skills.
+  - [`usage.md`](context/usage.md) - Agent instructions for finding dependency guidance and managing context and skills, installed as the `agent-context-usage` skill.
 
-When you install context from other gems, they will be placed in the `.context/` directory and referenced in `agents.md`.
+When you install context from other gems, they will be placed in `.agents/context/`.
 
 ## Usage
 
 Please see the [project documentation](https://ioquatix.github.io/agent-context/) for more details.
 
-  - [Getting Started](https://ioquatix.github.io/agent-context/guides/getting-started/index) - This guide explains how to use `agent-context`, a tool for discovering and installing contextual information from Ruby gems to help AI agents.
+  - [Getting Started](https://ioquatix.github.io/agent-context/guides/getting-started/index) - This guide explains how to install package guidance and skills using `agent-context`.
 
 ### Installation
 
@@ -52,7 +52,7 @@ $ bundle add agent-context
 
 #### Install Context (Primary Command)
 
-Install context from all available gems and update `agents.md`:
+Install ordinary context and skills from all available gems:
 
 ``` bash
 $ bake agent:context:install
@@ -86,13 +86,13 @@ Show the content of a specific context file:
 $ bake agent:context:show --gem async --file thread-safety
 ```
 
+The context list marks skill documents with `(skill)`, and the show and install tasks handle them alongside ordinary context. `agent-context` includes skill discovery and installation directly. Use it for Ruby dependency skills; the standalone `agent-skills` gem is deprecated.
+
 ## Version Control
 
-Both `.context/` and `agents.md` should be committed to git:
+In your repository instructions, direct agents to read relevant Markdown guides under `.agents/context/GEM/` and apply matching skills from `.agents/skills/`. Run installation after changing dependencies.
 
-  - `agents.md` is user-facing documentation that should be versioned.
-  - `.context/` files are referenced by `agents.md` and needed for AI agents to function properly.
-  - This ensures AI agents in CI have access to the full context.
+Installation maintains a marked block in the local Git exclude file, discovered through `git rev-parse --git-path info/exclude`. It excludes generated context, ownership files, and exact dependency-installed skill directories. Track project-owned instructions and skills under `.agents/`. Remove any blanket `/.agents/` rule from your project's `.gitignore` when adopting this layout. Re-run installation in each checkout.
 
 ## Providing Context in Your Gem
 
@@ -102,33 +102,52 @@ To provide context files in your gem, create a `context/` directory in your gem'
     ├── context/
     │   ├── getting-started.md
     │   ├── usage.md
-    │   ├── configuration.md
-    │   └── index.yaml (optional)
+    │   └── configuration.md
     ├── lib/
     └── your-gem.gemspec
 
-### Optional: Custom Index File
+Use descriptive filenames and focused Markdown guides. Agents find the installed files through directory listing and the list/show commands.
+
+### Providing Skills
+
+A root-level context document can declare a skill:
 
-You can provide a custom `index.yaml` file to control ordering and metadata:
+``` markdown
+---
+metadata:
+  type: skill
+description: Run the provider's workflow when preparing a new project.
+license: MIT
+---
 
-``` yaml
-description: "Your gem description from gemspec"
-version: "1.0.0"
-files:
-  - path: getting-started.md
-    title: "Getting Started"
-    description: "Quick start guide"
-  - path: usage.md
-    title: "Usage Guide"
-    description: "Detailed usage instructions"
+# Workflow
+
+Follow these instructions.
 ```
 
-If no `index.yaml` is provided, one will be generated automatically from your gemspec and markdown files.
+`context/workflow.md` from gem `provider` defaults to `.agents/skills/provider-workflow/SKILL.md`. Resources in `context/workflow/` are copied alongside the instructions. Installed names have a 64-character limit; descriptions have a 1,024-character limit. The generated instructions include additional skill metadata.
+
+Skills are discovered through `metadata.type: skill` metadata in `context/*.md`, matching `bake-agent-context-rust`. Include `context/**/*` in your gem's file list. Authored skill names are preserved; missing names default to `<package>-<filename>`.
+
+## Ownership and Updates
+
+Installed `SKILL.md` front matter records `metadata.type: skill` and the resolved `metadata.ecosystem`, `metadata.package`, and `metadata.version`. Ruby refreshes reconcile skills within their selected ecosystem and package scope. A full refresh also removes skills from removed or empty providers. After resolving an installation error, rerun the command to refresh generated files.
+
+See [the portable specification](specification.md) and [Getting Started](guides/getting-started/readme.md).
 
 ## Releases
 
 Please see the [project releases](https://ioquatix.github.io/agent-context/releases/index) for all releases.
 
+### v0.4.0
+
+  - Resolve context source filenames before installed skill names and show authored content consistently.
+  - Install unfamiliar context types as ordinary guidance so providers can introduce new types.
+  - Store resolved skill provenance in `SKILL.md` front matter under `metadata`, with `metadata.type: skill` declaring skills.
+  - Preserve authored names, descriptions, additional metadata, and the original Markdown body using native front matter AST nodes.
+  - Share loaded documents between context and skill installation, and use direct writes with rerunnable progress.
+  - Discover dependency guidance through installed Markdown files and the list/show commands. Remove generated indexes and the `agent:context:index` task.
+
 ### v0.3.0
 
   - Rename `agent.md` -\> `agents.md`.
@@ -152,11 +171,31 @@ Please see the [project releases](https://ioquatix.github.io/agent-context/relea
 
 We welcome contributions to this project.
 
-1.  Fork it.
+Read the [architecture design](design.md) for the current Ruby and Rust boundaries and the proposed alignment work.
+
+1.  Fork the repository.
 2.  Create your feature branch (`git checkout -b my-new-feature`).
-3.  Commit your changes (`git commit -am 'Add some feature'`).
+3.  Commit your changes (`git commit -am 'Add some feature.'`).
 4.  Push to the branch (`git push origin my-new-feature`).
-5.  Create new Pull Request.
+5.  Create a new pull request.
+
+### Running Tests
+
+To run the test suite:
+
+``` bash
+$ bundle exec sus
+```
+
+### Making Releases
+
+To prepare a release branch and open a pull request from an up-to-date `main`:
+
+``` bash
+$ bundle exec bake gem:github:release:patch # or minor or major
+```
+
+See [bake-gem-github](https://github.com/socketry/bake-gem-github) for setup, remote releases, and recovery.
 
 ### Developer Certificate of Origin
 

data/releases.md

@@ -1,5 +1,14 @@
 # Releases
 
+## v0.4.0
+
+  - Resolve context source filenames before installed skill names and show authored content consistently.
+  - Install unfamiliar context types as ordinary guidance so providers can introduce new types.
+  - Store resolved skill provenance in `SKILL.md` front matter under `metadata`, with `metadata.type: skill` declaring skills.
+  - Preserve authored names, descriptions, additional metadata, and the original Markdown body using native front matter AST nodes.
+  - Share loaded documents between context and skill installation, and use direct writes with rerunnable progress.
+  - Discover dependency guidance through installed Markdown files and the list/show commands. Remove generated indexes and the `agent:context:index` task.
+
 ## v0.3.0
 
   - Rename `agent.md` -\> `agents.md`.