Skip to content
LoopSkill

Documentation · How it works

The three-level skill loading model.

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

  1. You install the meta-skill once. Permanent client — one file teaches your agent everything.
  2. You ask for something new (e.g. "audit this site's SEO").
  3. Agent matches against the meta-skill's description. Triggers.
  4. Agent calls GET /api/skills/search?q=seo+audit. Returns up to 20 results ranked by quality_score + install count.
  5. Agent picks the best match — description fit × rating × recency.
  6. Agent calls GET /api/skills/install?slug=seo-audit-engine&mode=files. Auth required (even free skills need a key — this is how we track installs).
  7. Tarball downloaded and verified. The API returns a signed URL; the meta-skill verifies the ed25519 signature before writing any file to disk.
  8. Files written locally. _meta.json records slug, version, and install timestamp. Subsequent syncs use this to detect stale versions.
  9. Agent reads the new SKILL.md, follows its instructions, executes locally using your credentials and env vars.
  10. 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 + ed25519 manifest
  ▼
verify signature → 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:

export RECIPES_TELEMETRY=off

Operator+ 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 (Pro tier): create a bundle in the dashboard, add skills to it, then call recipes_sync (MCP) or recipes sync (CLI) on each host. All agents stay on the same pinned versions.
  • Fleet keys (Operator+ tier): issue a rec_fleet_* key scoped to a specific cookbook. Each agent presents the fleet key; the API enforces the bundle's skill allowlist. See Fleet guide.

Skills installed from a bundle are version-pinned. The bundle owner controls when to advance the pin — agents do not auto-upgrade outside of an explicit sync call.

The 7-card carousel

Every day at 05:00 London time, the carousel refreshes with 7 new or promoted skills. Each card competes against incumbent skills for 7 days — install counts and telemetry success rates determine which cards graduate to the core catalog. The carousel is the quality filter that keeps the catalog small and excellent.