diff --git a/agent-skills.gemspec b/agent-skills.gemspec index 8140a9d..686503f 100644 --- 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 index 8d3d7a3..bd96ee7 100644 --- 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 index 00941ac..4b796c3 100644 --- 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 index 8d3d7a3..bd96ee7 100644 --- 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 index 6a186f9..aa68bb1 100644 --- 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 diff --git a/specification.md b/specification.md index a30728e..c309eea 100644 --- a/specification.md +++ b/specification.md @@ -1,101 +1,3 @@ -# Agent Skills Packaging Specification +# Agent Context 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. +`agent-skills` is deprecated. The maintained [Agent Context specification](https://github.com/socketry/agent-context/blob/main/specification.md) defines context documents, metadata-declared skills, and the shared installation ownership index. Use [`agent-context`](https://github.com/socketry/agent-context) for Ruby projects and [`bake-agent-context-rust`](https://github.com/socketry/bake-agent-context-rust) for Cargo projects.