Align context and metadata-declared skills with Rust.

.gitignore

@@ -1,5 +1,3 @@
-/agents.md
-/.agents/
 /.context
 /.bundle
 /pkg

agent-context.gemspec

@@ -6,7 +6,7 @@ Gem::Specification.new do |spec|
 	spec.name = "agent-context"
 	spec.version = Agent::Context::VERSION
 
-	spec.summary = "Install and manage context files from Ruby gems."
+	spec.summary = "Install and manage context files and skills from Ruby gems."
 	spec.authors = ["Samuel Williams", "Shopify Inc."]
 	spec.license = "MIT"
 
@@ -28,4 +28,5 @@ Gem::Specification.new do |spec|
 	spec.required_ruby_version = ">= 3.3"
 
 	spec.add_dependency "bake", ">= 0.23"
+	spec.add_dependency "markly", "~> 0.16"
 end

bake/agent/context.rb

@@ -5,7 +5,6 @@
 # Copyright, 2025, by Samuel Williams.
 
 require_relative "../../lib/agent/context/installer"
-require_relative "../../lib/agent/context/index"
 
 include Agent::Context
 
@@ -17,36 +16,35 @@ def initialize(context)
 
 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"
 		end
 	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 "\t#{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

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,6 +37,11 @@ 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 .agents/context/
@@ -49,9 +54,13 @@ bake agent:context:show --gem async --file thread-safety
 
 When you run `bake agent:context:install`, the tool:
 
-1. Scans all installed gems for `context/` directories (in the gem's root).
+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 context files organized by gem name.
+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:
 ```
@@ -89,8 +98,8 @@ async-gem/
 
 - 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.
-- Ignore the generated `.agents/` directory in version control.
-- Don't edit files in `.agents/context/` - they get completely replaced when you reinstall.
+- 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)
 
@@ -142,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.
@@ -156,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:

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.