agent-context 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 11e3e6b44ae4b564cf5a70031206df479edcc02e716c0c6eadc74e36f8118bd8
-  data.tar.gz: fe26f5e667e56ab362581df7b8e591d570a7f666638b12d31baa41daef4667f7
+  metadata.gz: '002181a9d06d9d2521d09d29a8bddb03ef5ffa46aefd7bea19dc36246db4c53b'
+  data.tar.gz: 4e495d06b1988bd25da07a298e16f9e857081d17a726755fc90d12bcaa8376f0
 SHA512:
-  metadata.gz: 49995cbd0a102933c17760bf7d11b39d788e1bc91a1b0da6db3ff5cc70b6d047f5d806bf822a3a4e12073ba3cc244b60204ea84466b41d4155ffdb2da940fc83
-  data.tar.gz: fdad0c51486de3e66bdd3a7e2eeb9dfd0485dbcaec56256f95e9942489d38270ad9d972640de11f6be3d3de21cdbf2e195e608381153281e0ef31bfe0f6cbd1e
+  metadata.gz: dc5ef49aaba4d1997680396829585ec70b7f3a37911f8b7fc39900acf51e62134a68cde878ee6475cafba7afe2edb72a7d3425f26e6eb7ea0ce15b4964f684ad
+  data.tar.gz: 824601f7c4d450ba62e05b8973f5d8ea39ecc16c6e399118abef78c08b57ef0f8216c5ee2dfc81f9b40502a5a763c884a13aecc94ecac521625d8281fb612825

checksums.yaml.gz.sig

@@ -1 +1,6 @@
-�m���ѧ�h���Dv
"ĵ'U��nn?{�)k���@�����������Cl^*��KєH��N#z�inho,z0�A-ӵp`M�
�D›G�dnDLc�q��.�/��$��=��=Ē�\x���fÇ�et„��ِ�O�.,T/
�\�Q���ıVF�Hz,�\��&�i�b_@���6��X���]�`JN�*'������L�9/p8��b)�͆���+�Ė�W��+0*��{��o�#�T26_�$ؽo|��;��ǀ��Ԩf'�#�o�C�LEȒ���/�]E�aԻ���OLH���)��b�8�G�"!����|�o[>���یg�b`j�}�����D
+&��b
+H{�9���h~���S�4�֍�n"��ת�Ė���(Wz��F0/��:�
+y�\����h�K���k��L���1��J�y�=��,ε�mO���a$�R���Եs�����ɵ�N���q����1�}:F-m��'�c��{����O�w՝��[���4|7[�q���͠:	(�g�
+�|I	��5�������	qw�7j/& ��D#O��:�+h����z!G�yu_V	�M�S�Z_��YEv՜�����b���?j*�u��F�\?��q���6d�ͪ�
��������C�dž���
+�H���\���X�brK�
+�=j�H�

data/bake/agent/context.rb

@@ -1,11 +1,10 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2025, by Shopify Inc.
-# Copyright, 2025, by Samuel Williams.
+# Copyright, 2025-2026, by Shopify Inc.
+# Copyright, 2025-2026, by Samuel Williams.
 
 require_relative "../../lib/agent/context/installer"
-require_relative "../../lib/agent/context/index"
 
 include Agent::Context
 
@@ -17,26 +16,25 @@ end
 
 attr :installer
 
-# List all gems that have context available.
-# @parameter gem [String] Optional specific gem name to list context files for.
+# List providers and their context definitions, including skills.
+# @parameter gem [String | Nil] An optional provider gem.
 def list(gem: nil)
 	if gem
-		files = @installer.list_context_files(gem)
-		if files
+		provider = @installer.find_provider(gem)
+		if provider && !provider.definitions.empty?
 			puts "Context files for gem '#{gem}':"
-			files.each do |file|
-				relative_path = Pathname.new(file).relative_path_from(Pathname.new(@installer.find_gem_with_context(gem)[:path]))
-				puts "  #{relative_path}"
+			provider.definitions.each do |definition|
+				puts "  #{definition.display_name}"
 			end
 		else
 			puts "No context found for gem '#{gem}'"
 		end
 	else
-		gems = @installer.find_gems_with_context
+		gems = @installer.providers.reject{|provider| provider.definitions.empty?}
 		if gems.any?
 			puts "Gems with context available:"
-			gems.each do |gem_info|
-				puts "  #{gem_info[:name]} (#{gem_info[:version]})"
+			gems.each do |provider|
+				puts "  #{provider.name} (#{provider.version})"
 			end
 		else
 			puts "No gems with context found"
@@ -44,9 +42,9 @@ def list(gem: nil)
 	end
 end
 
-# Show the content of a specific context file.
+# Show one context definition from a provider.
 # @parameter gem [String] The gem name.
-# @parameter file [String] The context file name.
+# @parameter file [String] The source filename or skill name.
 def show(gem:, file:)
 	content = @installer.show_context_file(gem, file)
 	if content
@@ -56,33 +54,10 @@ def show(gem:, file:)
 	end
 end
 
-# Install context files from gems into the current project.
-# @parameter gem [String] Optional specific gem name to install context from.
+# Install ordinary context and skills.
+# @parameter gem [String | Nil] An optional provider gem.
 def install(gem: nil)
-	if gem
-		if @installer.install_gem_context(gem)
-			puts "Installed context from gem '#{gem}'"
-		else
-			puts "No context found for gem '#{gem}'"
-		end
-	else
-		installed = @installer.install_all_context
-		if installed.any?
-			puts "Installed context from #{installed.length} gems:"
-			installed.each {|gem_name| puts "  #{gem_name}"}
-		else
-			puts "No gems with context found"
-		end
-	end
-	
-	# Update agents.md after installing context
-	index = Agent::Context::Index.new(@installer.context_path)
-	index.update_agents_md
-end
-
-# Update or create AGENTS.md in the project root with context section
-# This follows the AGENTS.md specification for agentic coding tools
-def agents_md(path = "agents.md")
-	index = Agent::Context::Index.new(@installer.context_path)
-	index.update_agents_md(path)
+	installed = @installer.install(gem: gem)
+	puts "Installed context from: #{installed[:context].join(", ")}" unless installed[:context].empty?
+	puts "Installed skills: #{installed[:skills].join(", ")}" unless installed[:skills].empty?
 end

data/context/getting-started.md

@@ -1,6 +1,6 @@
 # Getting Started
 
-This guide explains how to use `agent-context`, a tool for discovering and installing contextual information from Ruby gems to help AI agents.
+This guide explains how to install package guidance and skills using `agent-context`.
 
 ## Overview
 
@@ -37,26 +37,35 @@ bake agent:context:list --gem async
 
 # View a specific context file
 bake agent:context:show --gem async --file thread-safety
+
+# List, show, or install a skill through the context tasks
+bake agent:context:list --gem provider
+bake agent:context:show --gem provider --file workflow
+bake agent:context:install --gem provider
 ```
 
-## Understanding context/ vs .context/
+## Understanding context/ vs .agents/context/
 
 **Important distinction:**
 - **`context/`** (no dot) = Directory in gems that contains context files to share.
-- **`.context/`** (with dot) = Directory in your project where context gets installed.
+- **`.agents/context/`** (with dot) = Directory in your project where context gets installed.
 
 ### What happens when you install context?
 
 When you run `bake agent:context:install`, the tool:
 
-1. Scans all installed gems for `context/` directories (in the gem's root).
-2. Creates a `.context/` directory in your current project.
-3. Copies context files organized by gem name.
+1. Scans resolved project gems for `context/` directories (in the gem's root).
+2. Creates a `.agents/context/` directory in your current project.
+3. Copies ordinary context files organized by gem name.
+4. Installs metadata-declared skills and their resources into `.agents/skills/`.
+5. Updates local Git exclusions for installed context and dependency skills.
+
+Discover installed Markdown guides by listing files under `.agents/context/GEM/`. Repository instructions can direct agents to read the guides relevant to their task.
 
 For example:
 ```
 your-project/
-├── .context/           # ← Installed context (with dot)
+├── .agents/context/           # ← Installed context (with dot)
 │   ├── async/          # ← From the 'async' gem's context/ directory
 │   │   ├── thread-safety.md
 │   │   └── performance.md
@@ -87,9 +96,10 @@ async-gem/
 
 ### Key Points for Users
 
-- Run `bake agent:context:install` to copy context to `.context/` (with dot).
-- The `.context/` directory is where installed context lives in your project.
-- Don't edit files in `.context/` - they get completely replaced when you reinstall.
+- Run `bake agent:context:install` to copy context to `.agents/context/` (with dot).
+- The `.agents/context/` directory is where installed context lives in your project.
+- Installation maintains local Git exclusions for generated context and dependency-owned skills. Track project-owned instructions and skills under `.agents/` and remove blanket `/.agents/` ignore rules.
+- Edit provider sources and reinstall to update generated files in `.agents/context/`.
 
 ## Providing Context (For Gem Authors)
 
@@ -109,7 +119,7 @@ your-gem/
 └── your-gem.gemspec
 ```
 
-**Important:** This is different from `.context/` (with dot) which is where context gets installed in user projects.
+**Important:** This is different from `.agents/context/` (with dot) which is where context gets installed in user projects.
 
 #### 2. Add context files
 
@@ -141,6 +151,8 @@ Available context files:
 
 #### 4. File format and content guidelines
 
+Use descriptive filenames, a clear heading, and an introduction for each Markdown guide. Link related guides so agents can follow them when they need more detail.
+
 Context files can be in any format, but `.md` is commonly used for documentation. The content should be:
 
 - **Practical** - Include real examples and working code.
@@ -155,6 +167,30 @@ Context files can be in any format, but `.md` is commonly used for documentation
 - Put helpful guides for users of your gem there.
 - Focus on practical usage, not API documentation.
 
+## Providing Skills
+
+To provide a skill, put a Markdown document directly inside `context/`:
+
+```markdown
+---
+metadata:
+  type: skill
+description: Follow the workflow when setting up this package.
+---
+
+# Workflow
+
+Follow the setup instructions.
+```
+
+`context/workflow.md` in gem `provider` defaults to `provider-workflow/SKILL.md`. An authored `name` is preserved and used as the installed directory name. The matching `context/workflow/` directory supplies resources. The generated instructions include additional skill metadata. Installed names must use lowercase ASCII letters, digits and single hyphens, with at most 64 characters. Descriptions must contain 1–1,024 characters.
+
+Include the complete source directories in your gem's packaged files. Skill documents and resource trees are installed under `.agents/skills/`.
+
+## 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.
+
 ## Example Context Files
 
 For examples of well-structured context files, see the existing files in this directory:
@@ -186,4 +222,4 @@ Before publishing, test your context files:
 ## Summary
 
 - **`context/`** = source (in gems).
-- **`.context/`** = destination (in your project).
+- **`.agents/context/`** = destination (in your project).

data/context/index.yaml

@@ -1,13 +1,15 @@
 # Automatically generated context index for Utopia::Project guides.
 # Do not edit then files in this directory directly, instead edit the guides and then run `bake utopia:project:agent:context:update`.
 ---
-description: Install and manage context files from Ruby gems.
+description: Install and manage context files and skills from Ruby gems.
 metadata:
+  bug_tracker_uri: https://github.com/ioquatix/agent-context/issues
+  changelog_uri: https://github.com/ioquatix/agent-context/blob/main/releases.md
   documentation_uri: https://ioquatix.github.io/agent-context/
   funding_uri: https://github.com/sponsors/ioquatix/
   source_code_uri: https://github.com/ioquatix/agent-context.git
 files:
 - path: getting-started.md
   title: Getting Started
-  description: This guide explains how to use `agent-context`, a tool for discovering
-    and installing contextual information from Ruby gems to help AI agents.
+  description: This guide explains how to install package guidance and skills using
+    `agent-context`.

data/context/usage.md

@@ -0,0 +1,73 @@
+---
+metadata:
+  type: skill
+description: Install and navigate guidance and skills from Ruby gem dependencies, or publish context and skills from a gem using agent-context.
+---
+
+# Using and Providing Context
+
+Use `agent-context` to find practical guidance shipped by Ruby gem dependencies and make package guidance available to downstream agents.
+
+## Use Dependency Guidance
+
+Follow the repository's agent instructions and discover installed dependency guidance by listing Markdown files under `.agents/context/GEM/`. Use descriptive filenames to select relevant guides, then read them before changing code that uses the package. For example, `rg --files --hidden --no-ignore .agents/context -g "*.md"` lists the installed Markdown files.
+
+If relevant installed files are missing, run `bundle exec bake agent:context:install` from the consuming project. Run it again after changing dependencies. It installs ordinary context and skills from resolved dependency gems.
+
+To inspect or install guidance from a specific provider:
+
+```bash
+bundle exec bake agent:context:list
+bundle exec bake agent:context:list --gem async
+bundle exec bake agent:context:show --gem async --file thread-safety
+bundle exec bake agent:context:install --gem async
+```
+
+`show` reads the provider's source file; the `.md` extension is optional. `install --gem NAME` installs both ordinary context and skills from that provider.
+
+Ordinary context is copied to `.agents/context/GEM/`. Repository instructions can direct agents to discover and read relevant guides there.
+
+Source filenames take precedence over installed skill names. The `show` command returns authored content, including for skills; generated installation metadata is available in the installed `SKILL.md`.
+
+## Use Dependency Skills
+
+Skills contain procedures for particular tasks and are installed under `.agents/skills/`. Use the matching skill's instructions and resources when its description applies to the work.
+
+```bash
+bundle exec bake agent:context:list --gem agent-context
+bundle exec bake agent:context:show --gem agent-context --file usage
+bundle exec bake agent:context:install
+bundle exec bake agent:context:install --gem agent-context
+```
+
+The context list marks skill documents with `(skill)`. Show them by their source filename, and install them together with ordinary context. An authored skill name determines its installed directory; a missing name defaults to `<gem>-<filename>`. This document installs as `agent-context-usage/SKILL.md`.
+
+## Keep Sources and Installed Files Separate
+
+The provider's tracked `context/` directory is source content. Installed dependency copies under `.agents/context/` and `.agents/skills/` are generated; edit provider sources and reinstall to update them. Keep repository-only instructions and project-owned skills in the consuming repository.
+
+Installation maintains local Git exclusions for generated context and exact dependency-installed skill directories. Track project-owned skills under `.agents/skills/` and remove blanket `/.agents/` ignore rules when adopting this layout.
+
+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.
+
+## Publish Context and Skills
+
+Put focused Markdown guides in the gem's `context/` directory, using descriptive lowercase filenames. Give each guide a clear heading and introduction, and link related guides together.
+
+To publish a skill, add `context/workflow.md` with metadata describing when to use it:
+
+```markdown
+---
+metadata:
+  type: skill
+description: Set up a project using this gem's conventions.
+---
+
+# Workflow
+
+Follow the setup instructions.
+```
+
+For this example, gem `provider` derives the missing name and installs the document as `.agents/skills/provider-workflow/SKILL.md`. Put companion resources in `context/workflow/`; they are copied alongside the generated instructions. The installer preserves an authored `name` and derives a missing name from the provider package and filename. It retains the description, additional metadata, and original Markdown body, and adds resolved provenance under `metadata`. The top-level resource name `SKILL.md` is reserved for generated instructions.
+
+Include `context/**/*` in the gemspec's packaged files. Installed skill names must use lowercase ASCII letters, digits, and single hyphens, with at most 64 characters. Descriptions must contain 1–1,024 characters and explain the task that should activate the skill.

data/design.md

@@ -0,0 +1,78 @@
+# Agent Context Design
+
+The Ruby `agent-context` gem and Rust `bake-agent-context` crate share a portable installation contract. The [specification](specification.md) defines file formats and observable behavior; this guide maps the implementation responsibilities.
+
+Choose the simplest structure that makes the behavior, state, and responsibilities easy to follow.
+
+## Responsibilities
+
+| Concern | Ruby | Rust |
+| --- | --- | --- |
+| Resolved package specification | `Gem::Specification`, retained by `Package` | `Specification`, resolved by `Installer::discover` |
+| Parsed Markdown | `Document` | `Document` in `document.rs` |
+| Loaded provider | `Package` wrapping `Gem::Specification` | `Package` wrapping `Specification` |
+| Provider lookup | `Installer#providers`, `#find_provider` | `Installer::providers`, `find_provider` |
+| Definition lookup | `Package#find_definition` | `Package::find_definition` |
+| Ordinary file | `Definition` | `FileDefinition` |
+| All definition variants | `Definition` and `Skills::Definition < Definition` | `Definition::File(FileDefinition)` or `Definition::Skill(SkillDefinition)` |
+| Installation workflow | `Installer#install` | `Installer::install` |
+| Installed provenance | `Skills::Ownership` | `ownership` module |
+| Local Git exclusions | `Exclusion` | `exclude` module |
+| Command presentation | Bake task adapters | Bake task adapters |
+| Errors | `Agent::Context::Error`, `InvalidError`, `ConflictError` | `bake::Error` returned through `Result` |
+
+Each parser, metadata rule, and file format has one owner. Document parsing interprets Markdown and YAML; skill definitions apply name and description rules; ownership interprets installed provenance; installers select destinations and change files. Constructors retain supplied state. Reading, parsing, discovery, and installation have explicit entry points.
+
+Ruby's loaded `Package` retains its `Gem::Specification` and definitions. Rust's resolved `Specification` carries Cargo metadata and the context path; loaded `Package` wraps that specification with its definitions. Both apply the same document and installation rules.
+
+Ruby uses the gem name as its package selector. Rust uses the crate name when unique and `crate@version` when multiple versions provide context. These selectors identify providers in commands and installed context directories. “Provider” is the domain role of a package that supplies context. Both installers expose `providers` and `find_provider`, returning loaded packages. A provider with an existing empty `context/` directory has an empty definition collection; a dependency without that directory is absent from provider lookup. Listing commands show providers with available definitions. Rust additionally exposes resolved Cargo metadata through `specifications` and `find_specification`.
+
+## Documents and Front Matter
+
+`Document.load(path)` and `Document::load(path)` read the source and delegate to `parse`. The parsed value retains the source path, original Markdown, decoded YAML mapping, and the Markdown parser's front matter node or source boundary.
+
+Both implementations use their Markdown parser's front matter node to read and serialize front matter: Markly in Ruby and `socketry-markdown` in Rust. The document layer decodes and encodes YAML through the node's raw value and classifies context using the nested `metadata.type` field. The skill predicate matches `skill`; all other values follow the ordinary context path. Only a `metadata` mapping is interpreted as context metadata; other authored values remain intact in the source. Ordinary guides can carry their own top-level fields. Front matter uses YAML by default or with the explicit `yaml` language hint. Other front matter languages remain opaque.
+
+A skill definition validates its top-level name and description. It preserves an authored name and uses it for the installed directory. When the name is omitted, it derives `<package>-<filename>`. Resource directories follow the source filename. Description validation trims whitespace to measure the value; the authored value is retained.
+
+To generate installed instructions, the definition merges resolved `ecosystem`, `package`, and `version` into the nested metadata mapping and supplies a missing name. The document writes the YAML into a copy of its front matter AST node and asks the Markdown library to serialize that node. It appends the original body using the parser's source boundary. Links, code blocks, spacing, Unicode, and body line endings retain their original bytes.
+
+The portable YAML form uses `---` delimiters. Rust also recognizes the additional front matter forms supported by `socketry-markdown`, such as a leading YAML code fence, and retains their delimiter style. Markly's supported syntax defines the Ruby parsing boundary.
+
+## Discovery and Loading
+
+For each provider, load Markdown documents before descending into subdirectories. Root-level skill declarations identify companion resource directories. Keep those resources opaque, including Markdown-looking assets.
+
+The loaded package stores ordinary definitions and skills in one collection. Ruby uses `Definition` for ordinary files and `Skills::Definition < Definition` for skills. Rust represents the same alternatives with a `Definition` enum: `File(FileDefinition)` carries the provider-relative destination path, source path, and optional parsed `Document`; `Skill(SkillDefinition)` carries skill-specific metadata and resources. Both implementations use `Document` for parsed Markdown.
+
+Listing, showing, and installation use this classification. Each definition's `path` is relative to the provider's `context/` directory; `source_path` locates the authored file. A skill's `name` identifies its installed directory. Definition lists are ordered by source path.
+
+`Package.find_definition(file)` checks the exact source path, then appends `.md` when no extension was given, and finally checks installed skill names. The lookup uses the loaded definitions. `content` and the `show` command return authored content for every definition. Skill definitions retain their parsed `Document` and resolved specification, and expose generated instructions as `installation_content`.
+
+The main installation operation resolves providers and loads each provider once, then applies the ordinary or skill destination rules to each definition. `Package.install_files(destination)` refreshes ordinary files in a package directory. A skill definition's `install(destination)` writes generated instructions and resources into its skill directory. Ruby's ordinary `Definition#write_to(path)` writes authored content to a file path, including when called on a skill definition.
+
+## Installation Flow
+
+The library owns orchestration. Bake tasks translate arguments, call the library, and present installed provider and skill names. Installation results contain package selectors under `context` and plain installed skill names under `skills`; presentation formatting belongs in task adapters.
+
+1. Resolve the selected providers and load their definitions.
+2. Validate and install skills under `.agents/skills/`, reconcile stale entries within the selected scope, and refresh Git exclusions.
+3. Install ordinary definitions under `.agents/context/`.
+
+Generated files use direct `File.write` or `std::fs::write`. Completed steps remain in place if a later operation fails. Report the relevant path and let the caller resolve the failure and rerun. Cleanup around a failed instruction write removes the incomplete destination; a later resource-copy failure retains the completed instructions and their provenance.
+
+Loading and writing are separate operations over a loaded snapshot. `Document.load(path).write(destination)` expresses that contract. Installation is a local, rerunnable workflow with incremental progress.
+
+## Ownership and Git Exclusions
+
+Installed `SKILL.md` metadata carries the resolved ecosystem, package, and version. Scanning direct skill directories supplies the names used for reconciliation and local Git exclusions. Ownership recognition requires `metadata.type: skill` and an explicit ecosystem before validating the complete tuple. Project skills can use unrelated metadata such as a version without claiming installation ownership.
+
+A full refresh selects one ecosystem; a package refresh selects one ecosystem and package. Destination collisions are reported. Other owned scopes and project skills remain available.
+
+Git exclusion handling locates and reads the local exclusion file, replaces the consuming project's marked block, and writes the result directly. Prefixes distinguish nested projects sharing a repository. The block lists generated context and exact installed skill directories from all ecosystems.
+
+## Readability and Verification
+
+Multi-step operations group related calculations and effects under short behavioral comments, separated by blank lines. Method documentation explains single-step operations. Helpers represent distinct responsibilities or independently meaningful operations.
+
+Both implementations exercise the shared `SKILL.md` fixture. Compare decoded metadata for format rules and exact body bytes for preservation. Tests cover classification, authored and derived names, metadata preservation, ownership scopes, opaque resources, Git exclusions, failures, and a successful retry. Keep the specification and this component mapping aligned when behavior or responsibilities change.

data/lib/agent/context/definition.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Shopify Inc.
+
+require "fileutils"
+
+module Agent
+	module Context
+		# Represents one ordinary file provided in a package's context directory.
+		class Definition
+			# Initialize a context definition from its paths and parsed document.
+			# @parameter path [String] The path relative to the provider's context directory.
+			# @parameter source_path [String] The source file path.
+			# @parameter document [Document | Nil] The parsed Markdown document, when applicable.
+			def initialize(path, source_path, document = nil)
+				@path = path
+				@source_path = source_path
+				@document = document
+			end
+			
+			# @attribute [String] The path relative to the provider's context directory.
+			attr_reader :path
+			
+			# @attribute [String] The source file path.
+			attr_reader :source_path
+			
+			# Whether this definition installs as an Agent Skill.
+			# @returns [bool] `false` for ordinary context definitions.
+			def skill?
+				false
+			end
+			
+			# Read the definition's Markdown content or opaque file contents.
+			# @returns [String] The source content.
+			def content
+				@document ? @document.content : File.read(@source_path)
+			end
+			
+			# Return the relative name displayed by the context list.
+			# @returns [String] The path relative to the provider context directory.
+			def display_name
+				@path
+			end
+			
+			# Write the definition to its installation destination.
+			# @parameter destination [String] The target file path.
+			def write_to(destination)
+				FileUtils.mkdir_p(File.dirname(destination))
+				if @document
+					@document.write(destination)
+				else
+					FileUtils.copy_file(@source_path, destination, true)
+				end
+			end
+		end
+	end
+end

data/lib/agent/context/document.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Shopify Inc.
+
+require "markly"
+require "yaml"
+require "date"
+require_relative "errors"
+
+module Agent
+	module Context
+		# Represents a Markdown source and its parsed front matter.
+		class Document
+			# Read and parse a Markdown document.
+			def self.load(path)
+				parse(File.read(path), path)
+			end
+			
+			# Parse YAML front matter using Markdown's native syntax tree.
+			def self.parse(content, path)
+				# Let Markly identify the front matter and its source boundary:
+				first = Markly.parse(content, flags: Markly::FRONT_MATTER).first_child
+				node = first if first&.type == :front_matter
+				language = node&.fence_info&.split&.first
+				
+				# Interpret YAML metadata, keeping other formats opaque:
+				frontmatter = {}
+				if node && [nil, "yaml"].include?(language)
+					frontmatter = YAML.safe_load(node.string_content, permitted_classes: [Date, Time], aliases: false, fallback: {})
+					raise InvalidError, "Context frontmatter must be a mapping: #{path}" unless frontmatter.is_a?(Hash)
+				end
+				
+				# Interpret only mappings as context metadata, retaining other authored values:
+				metadata = frontmatter["metadata"]
+				metadata = {} unless metadata.is_a?(Hash)
+				new(path, content, node, frontmatter, metadata)
+			rescue Psych::Exception => error
+				raise InvalidError, "Invalid YAML frontmatter in #{path}: #{error.message}"
+			end
+			
+			# Retain the source and its parsed representation.
+			def initialize(path, content, node, frontmatter, metadata)
+				@path = path
+				@content = content
+				@node = node
+				@frontmatter = frontmatter
+				@metadata = metadata
+			end
+			
+			# @attribute [String] The document source path.
+			attr_reader :path
+			
+			# @attribute [String] The original Markdown source.
+			attr_reader :content
+			
+			# @attribute [Hash] The decoded YAML front matter.
+			attr_reader :frontmatter
+			
+			# The extensible metadata mapping within front matter.
+			attr_reader :metadata
+			
+			# Whether the document declares a skill.
+			def skill?
+				metadata["type"] == "skill"
+			end
+			
+			# The original body following the parser's front matter boundary.
+			def body
+				return @content unless @node
+				
+				@content.lines.drop(@node.source_position[:end_line]).join
+			end
+			
+			# Serialize edited front matter through its AST node, preserving the body.
+			def render(frontmatter)
+				node = @node.dup
+				node.string_content = YAML.dump(frontmatter).delete_prefix("---\n")
+				node.to_markdown + body
+			end
+			
+			# Write the loaded source to its destination.
+			def write(path)
+				File.write(path, @content)
+			end
+		end
+	end
+end

data/lib/agent/context/errors.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Shopify Inc.
+
+module Agent
+	module Context
+		# Base class for errors raised while loading or installing context.
+		class Error < StandardError
+		end
+		
+		# Raised when provider content or installation metadata is invalid.
+		class InvalidError < Error
+		end
+		
+		# Raised when providers or installation destinations conflict.
+		class ConflictError < Error
+		end
+	end
+end