How it works — LoopSkill Docs

LoopSkill ships on top of Anthropic's Agent Skills standard. We didn't invent the format — we operate the marketplace on top of it.

Why it works at all

Skills load progressively. Only the frontmatter is always in context:

Level 1 — Frontmatter: always loaded. ~100 words per skill. Tells the agent the skill's name, description, trigger patterns, and tier. Costs tokens once at startup, not per-use.
Level 2 — SKILL.md body: loaded only when the skill triggers. Usually under 2k tokens. Contains the step-by-step instructions, tool calls, and output format.
Level 3 — Bundled resources: scripts, reference docs, config templates, example outputs. Zero token cost until explicitly read by an agent tool call.

So your agent can have hundreds of skills "installed" but only pay token cost for the ones it actually uses. That's the unlock that makes a marketplace possible.

The full install lifecycle

You install the meta-skill once. Permanent client — one file teaches your agent everything.
You ask for something new (e.g. "audit this site's SEO").
Agent matches against the meta-skill's description. Triggers.
Agent calls GET /api/skills/search?q=seo+audit. Returns up to 20 results ranked by quality_score + install count.
Agent picks the best match — description fit × rating × recency.
Agent calls GET /api/skills/install?slug=seo-audit-engine&mode=files. Free public skills install without a key; Pro-tier and private skills need one.
Tarball downloaded and verified. The API returns an expiring signed download URL and the tarball's sha256; the agent checks the sha256 of the downloaded bytes before writing any file to disk.
Files written locally. _meta.json records slug, version, and install timestamp.
Agent reads the new SKILL.md, follows its instructions, executes locally using your credentials and env vars.
Telemetry ping (optional). Anonymous: success/failure, duration, retry count, hashed agent class. No payload contents. Opt out at any time.

Lifecycle diagram

User ask
  │
  ▼
meta-skill frontmatter (always in context)
  │  "matches seo audit"
  ▼
Level 2: SKILL.md body loaded
  │
  ▼
GET /api/skills/search?q=seo+audit
  │  ranked results
  ▼
GET /api/skills/install?slug=seo-audit-engine&mode=files
  │  signed tarball URL + sha256
  ▼
check sha256 → write files locally
  │
  ▼
agent executes skill instructions
  │
  ▼
anonymous telemetry ping (optional)

What you control

Credentials never leave your machine. Skills hit third-party APIs directly using your env vars. LoopSkill only serves text files; it never proxies your API calls.
Optional sandbox. Skills declaring a [sandbox] block are isolated by bubblewrap or firejail (publisher's choice; host must have one available). The sandbox runner enforces a network allowlist, filesystem write paths, and an allowed executable list.
Architecture-aware install. The runtime probe refuses to install a skill on incompatible hardware — wrong OS, insufficient VRAM, missing CUDA — and suggests an alternative from the graph before any side effect happens.
You can delete any skill by removing its directory. No account-level lock-in. _meta.json is the only file LoopSkill writes outside the skill directory.

Telemetry & opt-out

By default, the meta-skill sends anonymous telemetry: install/use/result events with a hashed agent class, hashed user ID, duration in seconds, and retry count. No payload contents, no credential fingerprints, no inputs or outputs.

To opt out entirely, set the environment variable before starting your agent (RECIPES_TELEMETRY is a legacy variable name, still canonical):

export RECIPES_TELEMETRY=off

Pro subscribers can opt into pseudonymous payload sampling to improve their own skills — this is off by default and requires explicit consent in the dashboard.

Multi-agent considerations

LoopSkill is fleet-native. If you run multiple agents (e.g. Hermes on your laptop + a headless Codex on a CI server), you have two options:

Bundle sync (every tier): create a bundle, add skills to it, and run loopskill_bundle_install on each host; the agent downloads, sha256-checks and unpacks each tarball it returns. To update, re-run loopskill_bundle_install on each host — an unpinned bundle always serves the latest versions. To hold every host on the same versions, call loopskill_sync: it writes the current latest versions as the bundle's pins, and installs stay on them until you sync again.
Fleet keys (Pro tier): issue a rec_fleet_* key scoped to a specific bundle. Each agent presents the fleet key; the API enforces the bundle's skill allowlist. See Fleet guide.

A new bundle is not pinned: every install returns the latest version of each skill. Once the owner pins it with loopskill_sync, installs stay on those versions until the owner syncs again.

Catalog quality signal

LoopSkill doesn't run an editorial pick of the day. Quality surfaces instead through the public bundle leaderboard: bundles rank by real installs (test and CI keys are excluded from the count), and a verified-maintainer badge marks bundles a LoopSkill admin has reviewed. Because every tier — including Free — can publish and follow unlimited public bundles, the ranking is community curation, not a fixed rotation.

The three-level skill loading model.