samuel-williams-shopify · Oct 9, 2026 · Oct 9, 2026 · Oct 9, 2026
diff --git a/agent-skills.gemspec b/agent-skills.gemspec
@@ -6,7 +6,7 @@ Gem::Specification.new do |spec|
 	spec.name = "agent-skills"
 	spec.version = Agent::Skills::VERSION
 
-	spec.summary = "Install and manage agent skills from Ruby gems."
+	spec.summary = "Deprecated: use agent-context to discover and install agent skills."
 	spec.authors = ["Samuel Williams", "Shopify Inc."]
 	spec.license = "MIT"
 

diff --git a/context/getting-started.md b/context/getting-started.md
@@ -1,54 +1,14 @@
 # Getting Started
 
-`agent-skills` discovers and installs reusable agent skills distributed by Ruby gems.
+`agent-skills` is deprecated. Use `agent-context` to install dependency guidance and skills for Ruby projects.
 
 ## Installation
 
-```bash
-$ bundle add agent-skills
-$ bundle exec bake agent:skills:list
-$ bundle exec bake agent:skills:install
-```
-
-## Providing Skills
-
-Provider gems place one or more skill packages beneath a top-level `skills/` directory:
-
-```text
-your-gem/
-├── skills/
-│   └── ruby-testing/
-│       ├── SKILL.md
-│       ├── references/
-│       └── scripts/
-├── lib/
-└── your-gem.gemspec
-```
-
-Each `SKILL.md` starts with YAML frontmatter containing a `name` and `description`. The name must match the directory.
-
-## Installing Skills
-
-Install every discovered skill:
-
-```bash
-$ bake agent:skills:install
-```
-
-Install from a particular gem:
-
-```bash
-$ bake agent:skills:install --gem sus
-```
-
-Installed skills are copied to `.agents/skills/`. An ownership registry prevents dependencies from overwriting project-authored skills or skills supplied by another gem.
-
-## Inspecting Skills
+Add `agent-context` to your project and install dependency guidance and skills:
 
-```bash
-$ bake agent:skills:list
-$ bake agent:skills:list --gem sus
-$ bake agent:skills:show --gem sus --skill ruby-testing
+```sh
+bundle add agent-context
+bundle exec bake agent:context:install
 ```
 
-Review unfamiliar skills before installing them, especially when they include scripts.
+See the [Agent Context documentation](https://github.com/socketry/agent-context) for the supported commands and provider format.
diff --git a/context/index.yaml b/context/index.yaml
@@ -1,7 +1,7 @@
 # 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 agent skills from Ruby gems.
+description: 'Deprecated: use agent-context to discover and install agent skills.'
 metadata:
   bug_tracker_uri: https://github.com/socketry/agent-skills/issues
   changelog_uri: https://github.com/socketry/agent-skills/blob/main/releases.md
@@ -11,5 +11,5 @@ metadata:
 files:
 - path: getting-started.md
   title: Getting Started
-  description: "`agent-skills` discovers and installs reusable agent skills distributed
-    by Ruby gems."
+  description: "`agent-skills` is deprecated. Use `agent-context` to install dependency
+    guidance and skills for Ruby projects."
diff --git a/guides/getting-started/readme.md b/guides/getting-started/readme.md
@@ -1,54 +1,14 @@
 # Getting Started
 
-`agent-skills` discovers and installs reusable agent skills distributed by Ruby gems.
+`agent-skills` is deprecated. Use `agent-context` to install dependency guidance and skills for Ruby projects.
 
 ## Installation
 
-```bash
-$ bundle add agent-skills
-$ bundle exec bake agent:skills:list
-$ bundle exec bake agent:skills:install
-```
-
-## Providing Skills
-
-Provider gems place one or more skill packages beneath a top-level `skills/` directory:
-
-```text
-your-gem/
-├── skills/
-│   └── ruby-testing/
-│       ├── SKILL.md
-│       ├── references/
-│       └── scripts/
-├── lib/
-└── your-gem.gemspec
-```
-
-Each `SKILL.md` starts with YAML frontmatter containing a `name` and `description`. The name must match the directory.
-
-## Installing Skills
-
-Install every discovered skill:
-
-```bash
-$ bake agent:skills:install
-```
-
-Install from a particular gem:
-
-```bash
-$ bake agent:skills:install --gem sus
-```
-
-Installed skills are copied to `.agents/skills/`. An ownership registry prevents dependencies from overwriting project-authored skills or skills supplied by another gem.
-
-## Inspecting Skills
+Add `agent-context` to your project and install dependency guidance and skills:
 
-```bash
-$ bake agent:skills:list
-$ bake agent:skills:list --gem sus
-$ bake agent:skills:show --gem sus --skill ruby-testing
+```sh
+bundle add agent-context
+bundle exec bake agent:context:install
 ```
 
-Review unfamiliar skills before installing them, especially when they include scripts.
+See the [Agent Context documentation](https://github.com/socketry/agent-context) for the supported commands and provider format.
diff --git a/readme.md b/readme.md
@@ -1,143 +1,17 @@
 # Agent Skills
 
-Provides tools for discovering and installing agent skills distributed by Ruby gems.
+`agent-skills` is deprecated. Skill discovery and installation are now part of [`agent-context`](https://github.com/socketry/agent-context), using the same context metadata format as [`bake-agent-context-rust`](https://github.com/socketry/bake-agent-context-rust).
 
-[![Development Status](https://github.com/socketry/agent-skills/workflows/Test/badge.svg)](https://github.com/socketry/agent-skills/actions?workflow=Test)
+## Agent Context
 
-## Overview
+Add `agent-context` to your project and install dependency guidance and skills:
 
-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
+```sh
+bundle add agent-context
+bundle exec bake agent:context:install
 ```
 
-## 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).
-
-## Releases
-
-Please see the [project releases](https://socketry.github.io/agent-skills/releases/index) for all releases.
-
-### v0.0.0
-
-  - Initial release.
-  - Discover and validate skills provided by Ruby gems.
-  - Install project-scoped skills with ownership and collision protection.
-
-## Contributing
-
-We welcome contributions to this project.
-
-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.'`).
-4.  Push to the branch (`git push origin my-new-feature`).
-5.  Create a new pull request.
-
-### Running Tests
-
-To run the test suite:
-
-``` bash
-$ bundle exec sus
-```
-
-### Making Releases
-
-To make a new release:
-
-``` bash
-$ bundle exec bake gem:release:patch # or minor or major
-```
+See the [Agent Context documentation](https://github.com/socketry/agent-context/blob/main/guides/getting-started/readme.md), [portable specification](https://github.com/socketry/agent-context/blob/main/specification.md), and [license](license.md).
 
 ### Developer Certificate of Origin