skill 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d71981592f86798fc080114f847e07e7889bbe32b3cd7d6e41f1830e9c9be3f7
+  data.tar.gz: e7aa70524f1d82775670aa06c9bddb7073e337f5be30fa27b8f039f8b9b02dc1
+SHA512:
+  metadata.gz: 8d880355668cece71955dc47f5cce34ac20dfa4155b8fdc66239ba7e5b4de3dc50c5b46ca05c9ceb608e5f14341c58484f7618485891ba4333229d1e6021d508
+  data.tar.gz: 0a9e6294de982fc8c93464b436b24d31e217f6d9fc3d85d74c89fa2edeab98088470819fc22c41ab1260de1edb4555b103def81ffdf2c2b695a6bd0c3a70ac53

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+Each release's notes are in [`packaging/release-notes/`](packaging/release-notes) and on [GitHub Releases](https://github.com/crmne/skill/releases).
+
+## 0.1.0 (2026-10-17)
+
+The first release: `add`, `list`, `update`, `remove`, `find`, and `agents`. See [the notes](packaging/release-notes/v0.1.0.md).

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Carmine Paolino
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,280 @@
+<div align="center">
+
+# skill
+
+<strong>Install Agent Skills into RubyLLM apps and coding agents, from Ruby</strong>
+
+[![CI](https://github.com/crmne/skill/actions/workflows/ci.yml/badge.svg)](https://github.com/crmne/skill/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+<img src="docs/demo.gif" alt="gem exec skill finds the pdf skill on skills.sh and installs it globally from the home folder, then installs it into app/skills of a new Rails app that uses RubyLLM and shows skills.lock" width="800">
+
+</div>
+
+---
+
+[Agent Skills](https://agentskills.io/specification) are folders of instructions, scripts, and reference files that teach a model a workflow. People publish them in GitHub repositories and plugin marketplaces. `skill` copies the ones you pick into the folder your app or agent reads them from, records where each came from, and shows you what changes before it updates them.
+
+```sh
+gem exec skill find pdf                    # search skills.sh
+gem exec skill add anthropics/skills@pdf   # install one
+```
+
+```
+✓ Installed pdf → app/skills/pdf, .claude/skills/pdf
+  Recorded in skills.lock
+```
+
+It is the Ruby counterpart of [`npx skills`](https://github.com/vercel-labs/skills): the same sources, the same agent folders, the same [skills.sh](https://skills.sh) directory. [RubyLLM](https://rubyllm.com) is a first-class target, and it adds a lockfile with commits, updates that wait for your yes, and refusals instead of guesses. No runtime dependencies, Ruby 3.1 or newer, and it starts in about the time Ruby itself takes.
+
+## Running it
+
+With RubyGems 3.5 or newer (Ruby 3.3 ships it), run it without installing:
+
+```sh
+gem exec skill add owner/repo
+```
+
+`gem exec` asks RubyGems for the newest version on every run. Pass `--conservative` to use the version you already have, without the lookup:
+
+```sh
+gem exec --conservative skill list
+```
+
+Depending on your RDoc version, `gem exec` may print `Done installing documentation for  after 0 seconds` before the output, even when it installed nothing. That line comes from RDoc's RubyGems hook, not from `skill`, and is harmless.
+
+Or install it once:
+
+```sh
+gem install skill
+skill add owner/repo
+```
+
+In a Gemfile, add it with `require: false`, so it never loads into your app:
+
+```ruby
+gem "skill", require: false, group: :development
+```
+
+## Adding skills
+
+Name a repository, and pick skills from it:
+
+```sh
+skill add anthropics/skills --list            # what it holds, installs nothing
+skill add anthropics/skills@pdf               # one skill
+skill add anthropics/skills@pdf,xlsx          # several
+skill add anthropics/skills --skill pdf --skill docx
+skill add anthropics/skills --plugin document-skills
+skill add anthropics/skills --all             # every valid skill
+```
+
+A repository with one skill installs it directly. A repository with several asks you to pick: `skill` never installs a whole repository you did not ask for.
+
+Sources:
+
+| Source | Meaning |
+| --- | --- |
+| `owner/repo` | A GitHub repository, at its default branch |
+| `owner/repo@pdf` | The skill named `pdf` in it |
+| `owner/repo/skills/pdf` | One folder of it |
+| `owner/repo#v1.2.0` | A branch, a tag, or a full 40-character commit SHA (also `--ref`) |
+| `owner/repo#v1.2.0@pdf` | Both |
+| `https://github.com/owner/repo/tree/main/skills/pdf` | A GitHub address |
+| `./path/to/skills` | A folder on your computer |
+
+`skill` finds skills where `npx skills` does: a `SKILL.md` at the top, `skills/` and the agents' own folders up to three levels deep, the plugins of a marketplace file (Claude Code's `.claude-plugin/marketplace.json`, Codex's `.agents/plugins/marketplace.json`, Cursor's `.cursor-plugin/marketplace.json`), and when those hold nothing, the whole repository. `--full-depth` searches the whole repository anyway.
+
+Private repositories work with a token in `GITHUB_TOKEN` or `GH_TOKEN`.
+
+## Where skills go
+
+`skill` looks at your project and installs into every folder it shows signs of using:
+
+| Target | `--agent` | Project folder | Global folder | Detected by |
+| --- | --- | --- | --- | --- |
+| RubyLLM | `rubyllm` | `app/skills` | none | `ruby_llm` in the Gemfile or lockfile, or an `app/skills` folder |
+| Claude Code | `claude-code` | `.claude/skills` | `~/.claude/skills` | `.claude/` or `CLAUDE.md` |
+| Codex | `codex` | `.agents/skills` | `~/.agents/skills` | `.codex/` or `AGENTS.md` |
+| Cursor | `cursor` | `.agents/skills` | `~/.cursor/skills` | `.cursor/` or `.cursorrules` |
+| Gemini CLI | `gemini-cli` | `.agents/skills` | `~/.gemini/skills` | `.gemini/` or `GEMINI.md` |
+| GitHub Copilot | `github-copilot` | `.agents/skills` | `~/.copilot/skills` | `.github/copilot-instructions.md` |
+| ...and 74 more | | | | their own folders |
+
+When it finds none, it uses `.agents/skills`, the folder many agents share. `skill agents` lists all 80 targets. Folders several agents share get one copy.
+
+Choose instead of detecting:
+
+```sh
+skill add anthropics/skills@pdf --agent rubyllm
+skill add anthropics/skills@pdf --agent claude-code,cursor
+skill add anthropics/skills@pdf --dir vendor/skills
+```
+
+### Project or global
+
+Inside a project, `skill` installs into the project. Outside one, it installs globally, into your home folder, for the agents you have installed:
+
+```sh
+cd ~
+skill add anthropics/skills@pdf
+```
+
+```
+✓ Installed pdf → ~/.claude/skills/pdf (global)
+  Recorded in ~/.local/state/skill/skills.lock
+```
+
+A project is the nearest folder from where you run `skill` up that holds a `skills.lock`, a `Gemfile`, a `gems.rb`, a `.git`, or a `package.json`, or else an agent's folder or instructions (`.claude`, `.agents`, `.cursor`, `AGENTS.md`, `CLAUDE.md`, and the like). Your home folder never counts, since agents keep their global folders there. `list`, `update`, and `remove` decide the same way.
+
+Choose instead of deciding:
+
+```sh
+skill add anthropics/skills@pdf --global    # -g: the home folder, even inside a project
+skill add anthropics/skills@pdf --project   # -p: this folder as a project, even outside one
+```
+
+Once installed in `app/skills`, RubyLLM finds a skill by name:
+
+```ruby
+chat = RubyLLM.chat.with_skills(:pdf)
+```
+
+## The lockfile
+
+`skills.lock`, at the root of your project, records each skill's source, ref, commit, folder in the repository, the digest of its files, and where it is installed. Commit it with the skills.
+
+```json
+{
+  "version": 1,
+  "skills": {
+    "pdf": {
+      "source": "anthropics/skills",
+      "ref": null,
+      "ref_type": "branch",
+      "commit": "dbd4588f9e1033efb41dad4bef2f7947c8993d44",
+      "path": "skills/pdf",
+      "plugin": "document-skills",
+      "digest": "sha256-3a9465d4...",
+      "executable": false,
+      "targets": [".claude/skills", "app/skills"]
+    }
+  }
+}
+```
+
+Entries are sorted and carry no timestamps, so two branches adding different skills merge cleanly. The global lockfile lives in `~/.local/state/skill/skills.lock` (or `$XDG_STATE_HOME/skill`).
+
+## Updating
+
+```sh
+skill update            # every skill
+skill update pdf        # one
+skill update --dry-run  # only show what would change
+skill update --yes      # apply without asking
+```
+
+`update` fetches each source again at the ref you installed:
+
+* **A commit** never moves. The skill is skipped.
+* **A tag** is checked again. If someone moved it, `update` says so before anything else.
+* **A branch** moves forward. `update` shows the commit range, a compare link, and every file added, changed, or removed:
+
+```
+pdf: anthropics/skills dbd4588f9e10..5d6e7f8a9b0c
+  https://github.com/anthropics/skills/compare/dbd4588f9e10...5d6e7f8a9b0c
+  + scripts/merge.py
+  ~ SKILL.md
+Apply this update? [y/N]
+```
+
+Nothing changes until you answer yes, or pass `--yes`. Without a terminal and without `--yes`, `update` exits with status 1, so a scheduled job can tell you an update is waiting. When nothing moved, `update` makes one small request per repository and downloads nothing.
+
+To move to another ref, add the skill again with it: `skill add anthropics/skills#v2@pdf`.
+
+## Listing and removing
+
+```sh
+skill list              # installed skills, and any that were edited or are missing
+skill list --json
+skill remove pdf        # from every folder it was installed into
+skill remove pdf --agent claude-code
+```
+
+`list` also names skill folders `skill` did not install. `remove` deletes only what `skill` installed.
+
+## Finding skills
+
+`find` searches [skills.sh](https://skills.sh), the directory `npx skills` uses:
+
+```sh
+skill find rails
+```
+
+```
+rails-expert                jeffallan/claude-skills  4.6K installs
+                            skill add jeffallan/claude-skills@rails-expert
+```
+
+`--owner` keeps one GitHub owner's skills.
+
+## Safety
+
+A skill's instructions steer a model and its scripts run with whatever your sandbox grants, so review a skill like any code you add. `skill` keeps the copying itself safe:
+
+* **Every `SKILL.md` is checked** against the [specification](https://agentskills.io/specification) with the same rules as RubyLLM: front matter with a `name` of lowercase letters, digits, and single hyphens, at most 64 characters, and a `description` of at most 1,024. Invalid skills are listed and never installed.
+* **Archives are extracted defensively.** A path that is absolute, holds `..`, or leaves its folder fails the whole download. Links are never written or followed, and a skill holding one is refused.
+* **Sizes are capped.** GitHub sends a whole commit as one archive, so the download and extraction limits fit large repositories like `crmne/ruby_llm` and `heygen-com/hyperframes`, and both stream to disk rather than memory. Only the skills you pick are installed, so their limits stay tight. Raise any of them for sources you trust:
+
+  | Limit | Default | Variable |
+  | --- | --- | --- |
+  | Download | 512 MB | `SKILL_MAX_DOWNLOAD_BYTES` |
+  | Extracted archive | 2 GB | `SKILL_MAX_EXTRACT_BYTES` |
+  | Files in the archive | 100,000 | `SKILL_MAX_EXTRACT_FILES` |
+  | One skill | 16 MB | `SKILL_MAX_SKILL_BYTES` |
+  | Files in one skill | 2,000 | `SKILL_MAX_SKILL_FILES` |
+* **Executable bits are dropped,** with a warning naming the files, unless you pass `--keep-executable`. RubyLLM runs a skill's scripts through an interpreter, so they need none.
+* **Installs are atomic.** Copies are built beside their folders and swapped in once all are ready. A failure leaves everything as it was.
+* **Skills stay where they belong.** `add`, `update`, and `remove` write only inside the project, or when global inside your home folder (and any agent folder you moved elsewhere with its environment variable). Folders are checked with `..` and symbolic links resolved, so a `skills.lock` entry, a `--dir`, or a linked folder that leads elsewhere is refused with an error naming it, and nothing changes.
+* **Your edits are yours.** A skill edited since it was installed, or a folder `skill` did not install, is replaced or removed only with `--force`.
+* **No downloads at run time.** `skill` reaches the network only in `add`, `update`, and `find`. What it installs is plain files in your project.
+* **GitHub without its API.** Refs come from git's own HTTP endpoint and files from one archive of the exact commit, so there is no rate limit and no git needed. A token, when set, goes only to GitHub.
+
+## Environment
+
+| Variable | Use |
+| --- | --- |
+| `GITHUB_TOKEN`, `GH_TOKEN` | Read private repositories |
+| `XDG_CONFIG_HOME`, `CLAUDE_CONFIG_DIR`, `CODEX_HOME` | Where agents keep their global folders |
+| `XDG_STATE_HOME` | Where the global lockfile lives |
+| `INSTALL_INTERNAL_SKILLS` | Include skills whose front matter sets `metadata.internal: true` in `--all` |
+| `SKILLS_API_URL` | Another server with the skills.sh search endpoint |
+| `SKILL_MAX_*` | The limits above |
+| `NO_COLOR` | Plain output on a terminal too. Output that is not a terminal is always plain |
+
+## Compared with `npx skills`
+
+| | `npx skills` | `skill` |
+| --- | --- | --- |
+| Runs with | Node.js | Ruby 3.1+, no dependencies |
+| RubyLLM `app/skills` | No | Detected and first |
+| Lockfile | Folder hash, no commit | Source, ref, commit, digest, folders |
+| Updating | Installs the new version | Shows the commits and files, waits for yes; commits never move, moved tags are called out |
+| Installs | Symlinks to one copy, or copies | Copies, swapped in atomically |
+| Project or global | Asks on a terminal, else the project | The project when there is one, else global, and says which |
+| Hosts | GitHub, GitLab, any git, well-known URLs | GitHub and local folders |
+
+The agent folders and discovery rules follow [vercel-labs/skills](https://github.com/vercel-labs/skills) (MIT), so both tools install a skill to the same place.
+
+## Development
+
+```sh
+bundle install
+bundle exec rake    # tests and RuboCop
+```
+
+The tests never touch the network: a fake GitHub serves refs and archives built in the tests.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

data/exe/skill

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift File.expand_path('../lib', __dir__)
+require 'skill'
+
+Skill::CLI.start(ARGV)

data/lib/skill/agents.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+module Skill
+  # The places each target reads skills from, in a project and in the home
+  # folder. RubyLLM comes first; the coding agents follow the table of
+  # vercel-labs/skills (https://github.com/vercel-labs/skills), so both
+  # tools install a skill to the same folder.
+  module Agents
+    Agent = Struct.new(:key, :name, :project_dir, :global_dir, keyword_init: true) do
+      def global?
+        !global_dir.nil?
+      end
+    end
+
+    # A global folder may start with a placeholder for a folder an
+    # environment variable can move: +{config}+ is +XDG_CONFIG_HOME+, and the
+    # others are the agents' own variables, such as +CLAUDE_CONFIG_DIR+.
+    HOMES = {
+      'config' => ['XDG_CONFIG_HOME', '~/.config'],
+      'claude' => ['CLAUDE_CONFIG_DIR', '~/.claude'],
+      'autohand' => ['AUTOHAND_HOME', '~/.autohand'],
+      'grok' => ['GROK_HOME', '~/.grok'],
+      'hermes' => ['HERMES_HOME', '~/.hermes'],
+      'vibe' => ['VIBE_HOME', '~/.vibe']
+    }.freeze
+
+    ROWS = [
+      ['rubyllm', 'RubyLLM', 'app/skills', nil],
+      ['aider-desk', 'AiderDesk', '.aider-desk/skills', '~/.aider-desk/skills'],
+      ['amp', 'Amp', '.agents/skills', '{config}/agents/skills'],
+      ['antigravity', 'Antigravity', '.agents/skills', '~/.gemini/antigravity/skills'],
+      ['antigravity-cli', 'Antigravity CLI', '.agents/skills', '~/.gemini/antigravity-cli/skills'],
+      ['astrbot', 'AstrBot', 'data/skills', '~/.astrbot/data/skills'],
+      ['autohand-code', 'Autohand Code CLI', '.autohand/skills', '{autohand}/skills'],
+      ['augment', 'Augment', '.augment/skills', '~/.augment/skills'],
+      ['bob', 'IBM Bob', '.bob/skills', '~/.bob/skills'],
+      ['claude-code', 'Claude Code', '.claude/skills', '{claude}/skills'],
+      ['openclaw', 'OpenClaw', 'skills', '~/.openclaw/skills'],
+      ['cline', 'Cline', '.agents/skills', '~/.agents/skills'],
+      ['codearts-agent', 'CodeArts Agent', '.codeartsdoer/skills', '~/.codeartsdoer/skills'],
+      ['codebuddy', 'CodeBuddy', '.codebuddy/skills', '~/.codebuddy/skills'],
+      ['codemaker', 'Codemaker', '.codemaker/skills', '~/.codemaker/skills'],
+      ['codestudio', 'Code Studio', '.codestudio/skills', '~/.codestudio/skills'],
+      ['codex', 'Codex', '.agents/skills', '~/.agents/skills'],
+      ['command-code', 'Command Code', '.commandcode/skills', '~/.commandcode/skills'],
+      ['continue', 'Continue', '.continue/skills', '~/.continue/skills'],
+      ['cortex', 'Cortex Code', '.cortex/skills', '~/.snowflake/cortex/skills'],
+      ['crush', 'Crush', '.crush/skills', '~/.config/crush/skills'],
+      ['cursor', 'Cursor', '.agents/skills', '~/.cursor/skills'],
+      ['deepagents', 'Deep Agents', '.agents/skills', '~/.deepagents/agent/skills'],
+      ['devin', 'Devin for Terminal', '.devin/skills', '{config}/devin/skills'],
+      ['dexto', 'Dexto', '.agents/skills', '~/.agents/skills'],
+      ['droid', 'Droid', '.agents/skills', '~/.factory/skills'],
+      ['eve', 'Eve', 'agent/skills', nil],
+      ['firebender', 'Firebender', '.agents/skills', '~/.firebender/skills'],
+      ['forgecode', 'ForgeCode', '.forge/skills', '~/.forge/skills'],
+      ['fx', 'fx', '.agents/skills', '~/.agents/skills'],
+      ['gemini-cli', 'Gemini CLI', '.agents/skills', '~/.gemini/skills'],
+      ['github-copilot', 'GitHub Copilot', '.agents/skills', '~/.copilot/skills'],
+      ['goose', 'Goose', '.goose/skills', '{config}/goose/skills'],
+      ['grok', 'Grok Build', '.grok/skills', '{grok}/skills'],
+      ['hermes-agent', 'Hermes Agent', '.hermes/skills', '{hermes}/skills'],
+      ['inference-sh', 'inference.sh', '.inferencesh/skills', '~/.inferencesh/skills'],
+      ['jazz', 'Jazz', '.jazz/skills', '~/.jazz/skills'],
+      ['junie', 'Junie', '.junie/skills', '~/.junie/skills'],
+      ['iflow-cli', 'iFlow CLI', '.iflow/skills', '~/.iflow/skills'],
+      ['kilo', 'Kilo Code', '.agents/skills', '~/.kilo/skills'],
+      ['kimchi', 'Kimchi', '.kimchi/skills', '~/.config/kimchi/harness/skills'],
+      ['kimi-code-cli', 'Kimi Code CLI', '.agents/skills', '~/.agents/skills'],
+      ['kiro-cli', 'Kiro CLI', '.kiro/skills', '~/.kiro/skills'],
+      ['kode', 'Kode', '.kode/skills', '~/.kode/skills'],
+      ['lingma', 'Lingma', '.lingma/skills', '~/.lingma/skills'],
+      ['loaf', 'Loaf', '.agents/skills', '~/.agents/skills'],
+      ['mcpjam', 'MCPJam', '.mcpjam/skills', '~/.mcpjam/skills'],
+      ['minimax-code', 'MiniMax Code', '.minimax/skills', '~/.minimax/skills'],
+      ['mistral-vibe', 'Mistral Vibe', '.vibe/skills', '{vibe}/skills'],
+      ['moxby', 'Moxby', '.moxby/skills', '~/.moxby/skills'],
+      ['mux', 'Mux', '.mux/skills', '~/.mux/skills'],
+      ['opencode', 'OpenCode', '.agents/skills', '{config}/opencode/skills'],
+      ['openhands', 'OpenHands', '.openhands/skills', '~/.openhands/skills'],
+      ['ona', 'Ona', '.ona/skills', '~/.ona/skills'],
+      ['pi', 'Pi', '.agents/skills', '~/.agents/skills'],
+      ['posit-assistant', 'Posit Assistant', '.posit/assistant/skills', '~/.posit/assistant/skills'],
+      ['qoder', 'Qoder', '.qoder/skills', '~/.qoder/skills'],
+      ['qoder-cn', 'Qoder CN', '.qoder/skills', '~/.qoder-cn/skills'],
+      ['qwen-code', 'Qwen Code', '.qwen/skills', '~/.qwen/skills'],
+      ['replit', 'Replit', '.agents/skills', '{config}/agents/skills'],
+      ['reasonix', 'Reasonix', '.reasonix/skills', '~/.reasonix/skills'],
+      ['rovodev', 'Rovo Dev', '.rovodev/skills', '~/.rovodev/skills'],
+      ['roo', 'Roo Code', '.roo/skills', '~/.roo/skills'],
+      ['sarvam-code', 'Sarvam Code', '.agents/skills', '~/.agents/skills'],
+      ['tabnine-cli', 'Tabnine CLI', '.tabnine/agent/skills', '~/.tabnine/agent/skills'],
+      ['terramind', 'Terramind', '.terramind/skills', '~/.terramind/skills'],
+      ['tinycloud', 'Tinycloud', '.tinycloud/skills', '~/.tinycloud/skills'],
+      ['trae', 'Trae', '.trae/skills', '~/.trae/skills'],
+      ['trae-cn', 'Trae CN', '.trae/skills', '~/.trae-cn/skills'],
+      ['warp', 'Warp', '.agents/skills', '~/.agents/skills'],
+      ['windsurf', 'Windsurf', '.windsurf/skills', '~/.codeium/windsurf/skills'],
+      ['zed', 'Zed', '.agents/skills', '~/.agents/skills'],
+      ['zcode', 'ZCode', '.zcode/skills', '~/.zcode/skills'],
+      ['zencoder', 'Zencoder', '.zencoder/skills', '~/.zencoder/skills'],
+      ['zenflow', 'Zenflow', '.zencoder/skills', '~/.zencoder/skills'],
+      ['neovate', 'Neovate', '.neovate/skills', '~/.neovate/skills'],
+      ['pochi', 'Pochi', '.pochi/skills', '~/.pochi/skills'],
+      ['promptscript', 'PromptScript', '.agents/skills', nil],
+      ['adal', 'AdaL', '.adal/skills', '~/.adal/skills'],
+      ['universal', 'Universal', '.agents/skills', '{config}/agents/skills']
+    ].freeze
+
+    ALIASES = {
+      'ruby_llm' => 'rubyllm', 'ruby-llm' => 'rubyllm', 'rails' => 'rubyllm',
+      'claude' => 'claude-code', 'copilot' => 'github-copilot', 'gemini' => 'gemini-cli'
+    }.freeze
+
+    ALL = ROWS.to_h do |key, name, project_dir, global_dir|
+      [key, Agent.new(key: key, name: name, project_dir: project_dir, global_dir: global_dir).freeze]
+    end.freeze
+
+    class << self
+      # Returns every Agent, RubyLLM first.
+      def all
+        ALL.values
+      end
+
+      # Returns the Agent called +key+ or one of its aliases. Raises
+      # UsageError for an unknown name.
+      def fetch(key)
+        name = key.to_s.strip.downcase
+        ALL.fetch(ALIASES.fetch(name, name)) do
+          raise UsageError, "Unknown agent #{key.inspect}. Run `skill agents` for the list"
+        end
+      end
+
+      # Returns the absolute global folder of +agent+, or +nil+ when it has
+      # none, reading placeholders from +env+ and +~+ as +home+.
+      def global_path(agent, env:, home:)
+        return unless agent.global?
+
+        path = agent.global_dir.sub(/\A\{(\w+)\}/) do
+          variable, default = HOMES.fetch(Regexp.last_match(1))
+          value = env[variable].to_s.strip
+          value.empty? ? default : value
+        end
+        File.expand_path(path.sub(%r{\A~(?=/|\z)}, home))
+      end
+    end
+  end
+end

data/lib/skill/archive.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'rubygems/package'
+require 'tempfile'
+require 'zlib'
+
+module Skill
+  # Extracts a gzipped tarball of a repository, as GitHub serves it, into a
+  # folder. Only regular files and folders are written. Links are never
+  # written or followed: their paths are returned, so a skill holding one
+  # can be refused. Any path that is absolute, holds +..+, or would leave
+  # the folder fails the whole archive, as does going over the limits.
+  class Archive
+    Result = Struct.new(:commit, :links, keyword_init: true)
+
+    FILE_TYPES = ['0', "\0", ''].freeze
+    LINK_TYPES = %w[1 2].freeze
+
+    def initialize(limits: Limits.new)
+      @limits = limits
+    end
+
+    # Extracts the gzipped tarball at +path+ into the folder +into+, dropping
+    # the top folder every GitHub archive has. Returns a Result with the
+    # commit git recorded in the archive's pax header, if any.
+    def extract(path, into)
+      Tempfile.create(['skill', '.tar'], binmode: true) do |tar|
+        gunzip(path, tar)
+        tar.rewind
+        read(tar, File.realpath(into))
+      end
+    end
+
+    private
+
+    def gunzip(path, tar)
+      size = 0
+      Zlib::GzipReader.open(path) do |gzip|
+        while (chunk = gzip.read(1024 * 1024))
+          size += chunk.bytesize
+          if size > @limits.extract_bytes
+            raise UnsafeError,
+                  Limits.exceeded(:extract_bytes, "The archive expands to more than #{@limits.extract_bytes} bytes")
+          end
+
+          tar.write(chunk)
+        end
+      end
+    rescue Zlib::Error
+      raise UnsafeError, 'The download is not a gzip archive'
+    end
+
+    def read(tar, into)
+      state = { commit: nil, links: [], files: 0, long_name: nil }
+      Gem::Package::TarReader.new(tar).each { |entry| visit(entry, into, state) }
+      Result.new(commit: state[:commit], links: state[:links].uniq.freeze)
+    rescue Gem::Package::TarInvalidError, ArgumentError => e
+      raise UnsafeError, "The download is not a valid tar archive (#{e.class})"
+    end
+
+    def visit(entry, into, state)
+      type = entry.header.typeflag
+      case type
+      when 'g' then state[:commit] ||= pax(entry.read.to_s)['comment']&.then { |sha| sha[/\A\h{40}\z/] }
+      when 'x' then state[:long_name] = pax(entry.read.to_s)['path']
+      when 'L' then state[:long_name] = entry.read.to_s.delete("\0")
+      else store(entry, type, into, state)
+      end
+    end
+
+    def store(entry, type, into, state)
+      name = state[:long_name] || entry.full_name
+      state[:long_name] = nil
+      parts = relative_parts(name)
+      return if parts.empty?
+
+      if FILE_TYPES.include?(type)
+        state[:files] += 1
+        if state[:files] > @limits.extract_files
+          raise UnsafeError,
+                Limits.exceeded(:extract_files, "The archive holds more than #{@limits.extract_files} files")
+        end
+
+        write(File.join(into, *parts), entry)
+      elsif type == '5'
+        directory(File.join(into, *parts))
+      elsif LINK_TYPES.include?(type)
+        state[:links] << parts.join('/')
+      end
+    end
+
+    # Splits an archive path into the parts below the archive's top folder,
+    # refusing anything that could land outside the extraction folder.
+    def relative_parts(name)
+      text = name.to_s.dup.force_encoding(Encoding::UTF_8)
+      if !text.valid_encoding? || text.include?("\0") || text.include?('\\') || text.start_with?('/') ||
+         text.match?(/\A[A-Za-z]:/)
+        raise UnsafeError, "The archive holds an unsafe path, #{name.inspect}"
+      end
+
+      parts = text.split('/').reject { |part| part.empty? || part == '.' }
+      raise UnsafeError, "The archive holds an unsafe path, #{name.inspect}" if parts.include?('..')
+
+      parts.drop(1)
+    end
+
+    def write(path, entry)
+      FileUtils.mkdir_p(File.dirname(path))
+      raise UnsafeError, "The archive writes #{path} twice" if File.symlink?(path) || File.directory?(path)
+
+      File.open(path, 'wb', 0o644) do |file|
+        while (chunk = entry.read(1024 * 1024))
+          file.write(chunk)
+        end
+      end
+      File.chmod(entry.header.mode.to_i.anybits?(0o111) ? 0o755 : 0o644, path)
+    rescue SystemCallError => e
+      raise UnsafeError, "The archive could not be extracted: #{e.class}"
+    end
+
+    def directory(path)
+      FileUtils.mkdir_p(path)
+    rescue SystemCallError => e
+      raise UnsafeError, "The archive could not be extracted: #{e.class}"
+    end
+
+    # Reads pax extended header records: "<length> <key>=<value>\n".
+    def pax(data)
+      records = {}
+      data = data.dup.force_encoding(Encoding::BINARY)
+      until data.empty?
+        length = data[/\A\d+/].to_i
+        break if length <= 0 || length > data.bytesize
+
+        key, value = data.byteslice(0, length).sub(/\A\d+ /, '').chomp.split('=', 2)
+        records[key] = value.to_s.force_encoding(Encoding::UTF_8) if key
+        data = data.byteslice(length..)
+      end
+      records
+    end
+  end
+end

data/lib/skill/boundary.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Skill
+  # The folders a command may write skills into. A path is inside when,
+  # with +..+ and symbolic links resolved, it lies in one of them, so a
+  # lockfile or a link cannot lead an install or a removal elsewhere.
+  class Boundary
+    attr_reader :name
+
+    # +folders+ are the folders allowed; +name+ says what they are, as
+    # people read it ("the project").
+    def initialize(folders, name:)
+      @folders = folders.filter_map { |folder| self.class.real_path(File.expand_path(folder)) }.uniq
+      @name = name
+    end
+
+    # Returns whether +path+ really lies inside one of the folders.
+    def include?(path)
+      real = self.class.real_path(File.expand_path(path))
+      return false unless real
+
+      @folders.any? { |folder| real == folder || real.start_with?("#{folder}/") }
+    end
+
+    # Returns +path+ with the deepest part that exists resolved and the
+    # rest appended, or +nil+ when a link in it leads nowhere.
+    def self.real_path(path)
+      missing = []
+      current = path
+      until File.exist?(current) || File.symlink?(current)
+        parent = File.dirname(current)
+        return path if parent == current
+
+        missing.unshift(File.basename(current))
+        current = parent
+      end
+      File.join(File.realpath(current), *missing)
+    rescue SystemCallError
+      nil
+    end
+  end
+end