Skills on your machines
A skill is a SKILL.md a coding tool loads when the work matches its description. Claude Code,
Codex, Cursor, Copilot, OpenCode, OpenClaw, pi, omp, JetBrains and Devin Desktop read the same set;
most share ~/.agents/skills. Claude Desktop installs them as plugins from your gateway's plugin
marketplace instead, whether managed or set up with anyray-connect.
The built-in anyray skill
Every enrolled machine gets a skill in a folder named anyray. It covers routing, trimmed output,
and code that calls a model through Anyray:
| Trigger | The agent does |
|---|---|
| "is my traffic going through Anyray", "nothing shows on the dashboard", a 401 after enrollment | Runs anyray-connect doctor --json and applies the remedy it names. An agent reads /connect/self-check instead |
a truncated tool result with a ctx_ handle | Calls anyray_retrieve for the original bytes |
an anyray-hook footer naming a file in connect's hook-tee folder (~/.anyray/hook-tee; under a Codex sandbox, anyray-hook-tee-<uid> in the temp directory, fetched only by id through anyray_retrieve), or … [N line(s) omitted by anyray · lines A-B] | Fetches the omitted lines if needed, and treats the footer as Anyray's, not tampering, on a machine where connect's hook-tee folder exists |
| writing model-calling code or changing its context handling | Uses the gateway URL and key, preserves the app's context, and explains the optional exact profile |
Without it, agents call trimmed content missing or stop to warn about tampering. It updates with your gateway.
Which version each machine gets
The gateway serves the skill in three versions under one version number and one description:
| Where it lands | Version |
|---|---|
~/.claude/skills on a developer's machine | Claude Code's. Names its tools as Claude Code lists them, and reads several files with anyray_read_batch in one call |
a folder several tools share, such as ~/.agents/skills | Shared. Names only tools every connect release serves |
| Claude Desktop, through the gateway's plugin marketplace | Shared |
| every folder on an agent host (a service key), and a Claude Agent SDK app's plugin | Agent. Never stops to ask a person, puts problems in its final output, checks routing with /connect/self-check, and names only anyray_retrieve and anyray_recall |
Only Claude Code's version names anyray_read_batch. A connect older than 0.11.334 writes the
shared version everywhere on a developer's machine. The gateway picks the agent version from the
key itself, so an agent host gets it on any connect release.
Connect never writes the skill into a Claude Agent SDK app. The Anthropic agent runbook
(/agents/anthropic.md) has the app pull it from /connect/policy?tool=sdk-agent into its own
plugin. There the agent version treats a hook-tee footer as ordinary tool output and never asks the
agent to install connect.
Check it arrived
anyray-connect sync
The Skills section lists anyray. The console's Skills & Guidance card shows the gateway side:
| Card says | Meaning |
|---|---|
| Built in | The gateway is serving it |
| Not serving | The gateway could not read its Skills store in full, so it holds the Skill back and machines keep their copy |
| Needs gateway upgrade | This gateway predates the Skill |
On Machines, each person's Technical checks list has an Anyray skill row for the skills folders Connect writes:
| Row says | Meaning |
|---|---|
| passing | Installed, or the machine has nowhere to put one. A seat that never pulled it also reads passing |
| skill gone from a skills folder | It was written and then removed. Run anyray-connect sync on that machine |
Only the second shows as failing. To tell "installed" from "never pulled", read builtinSkill.kind
(with its remedy) from anyray-connect doctor --json.
Claude Desktop keeps the skill as a plugin, so it has its own Anyray skill row under Claude Desktop:
| Row says | Meaning |
|---|---|
| Installed | Desktop installed it and has it on |
| Installed, not turned on yet | Desktop has not switched it on. Quit and reopen Claude Desktop if it stays |
| Turned off in Claude Desktop | The person switched it off in Desktop's plugin settings. Fails |
| Removed in Claude Desktop | The person uninstalled it, and Desktop never reinstalls a plugin they removed. They reinstall it from the Anyray marketplace in Desktop's plugin settings. Fails |
| Not installed yet | Desktop has the Anyray marketplace and installs the skill on its next plugin sync |
| Anyray marketplace not set up | Desktop's records name no Anyray marketplace, so the skill cannot arrive. Run anyray-connect repair on that machine |
| Plugin records can't be read | Connect could not read Desktop's third-party profile |
| Not in third-party mode | Desktop has no third-party profile on that machine |
| Not reported | That machine's Connect, or your gateway, predates this row |
anyray-connect doctor prints the same state as a Claude Desktop: line under Anyray skill.
doctor --json and status --json carry it as desktopSkill on the claude-desktop tool.
To watch Desktop sync the marketplace, its log (~/Library/Logs/Claude-3p/main.log on macOS)
shows each sync as a [custom-3p:configured-marketplaces] line naming anyray-org-skills.
A skill on disk is not always one the model sees. Claude Code seats also get an Anyray skill loaded row, which the gateway sets from what that person's Claude Code requests listed to the model:
| Row says | Meaning |
|---|---|
| Loaded | A request in the last day listed it |
| On disk, not listed yet | On disk, not listed so far, for under two days or fewer than 3 requests a day |
| On disk, not loaded for a day | On disk, and 3 or more requests on each of the last two days listed none. Fails |
| Not on disk | The Anyray skill row says the file is missing |
| Runs without a skill loader | Claude Code ran with no Skill tool |
| No requests in the last day | Nothing to judge |
| Not reported | The gateway could not judge it (no evidence, or its read failed), or predates the check |
For the failing row, see troubleshooting.
For an agent, confirm on its Agents card that Anyray skill is loaded and its runtime summary
says current copy invoked.
New skills in Claude Code
Claude Code installs org skills as plugins from the gateway's marketplace (full plugins use the same one). anyray-connect sync
also installs any org skill Claude Code has turned on but not installed, so a new skill works after
the next sync. If one is still missing, anyray-connect doctor lists it under Org Skills in
Claude Code with the commands to install it by hand. The same row names an installed skill
Claude Code cannot load because its SKILL.md has no name and description front matter. Open
it under Skills in the console, choose Edit, and save.
Replace it with your own
Save a SKILL.md with name: anyray and a description in its front matter. Tools match on the
description, so use the words your developers would type. The gateway refuses a SKILL.md
without both.
In the console, open Connectors under Settings, then Skills. Choose Add, then
Upload skill. The upload keeps text files and leaves out hooks, monitors, MCP or LSP
servers, a bin folder and a plugin manifest.
The Built in row disappears and yours takes its place. Machines pick it up on their next policy sync, and Claude Desktop the next time it starts or its window comes to the front.
Removing your version brings the built-in back. There is no off switch.
Where the files are written
Connect writes <skills-dir>/<id>/SKILL.md and records the last version written in ~/.anyray, so
a re-run only touches what changed. Deleting a Skill in the console removes its folder from every
machine on the next sync. Claude Code installs organization plugins natively, so a plugin-derived
Skill is not duplicated there. Directories and the sync verb:
CLI commands.
Skill bodies download from a credential-free gateway URL. Never put credentials or anything you would not want on a contractor's laptop in one.