LoopSkill

io.github.wisechef-aiv0.9.65Updated Oct 11, 2026

Search, install and compose AI agent skills, loops and bundles from the LoopSkill marketplace.

VerifiedStreamable HTTPWeb executableDeveloper ToolsProductivity & WorkflowKnowledge & Memory

Overview

AI-generated overview

Lets an assistant search, install and compose AI agent skills, loops and bundles from the LoopSkill marketplace over MCP.

What it does
LoopSkill exposes a remote MCP endpoint backed by a registry of agent skills, loops and bundles. Assistants can search skills with hybrid full-text and vector search, fetch skill details and versions, browse public bundles, list loops with their safety contracts, and run a loop's verification to get an objective pass or fail. Publishing, running and rating loops, and installing paid-tier skills, require an API key; most read endpoints are unauthenticated.
When to use it
Use it when an assistant should discover and pull reusable skills or bundles from a catalog, or when you want to run a loop's built-in success check and get a pass/fail verdict. It is also relevant if you want to self-host the same registry and point the CLI at your own instance.
Requirements
A remote MCP endpoint at the provider's hosted URL, reachable over the network. An API key is passed in the x-api-key header; keys start with rec_ and are required for publishing, running, rating and paid-tier installs. Free-tier skills install anonymously. A free key can be obtained by agent self-enrolment or by creating one on the provider's site.
Before you install
The x-api-key header carries a credential; treat it as a secret. Installing paid-tier skills, publishing, running and rating loops require that key and may involve account or payment implications. Running a loop executes its verification under enforced bounds, and on non-Linux hosts it falls back to a weaker bounded mode rather than a kernel sandbox. Scheduled loops report nothing unless the loop's own prompt emits telemetry, and cron materialization is limited to one host format.

Installation

In SourceWeft

  1. Open LoopSkill in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Other MCP clients

Add this to your client's mcpServers config.

{
  "mcpServers": {
    "loopskill": {
      "type": "http",
      "url": "https://app.loopskill.io/api/mcp/http/"
    }
  }
}

README

LoopSkill

A local CLI for skills you already have, plus a self-hostable registry to pull more from. Start with the CLI — it needs no account and makes no network call for import/diff.

[CI] [License: MPL-2.0] [Stars] [loopskill.io] [MCP native]

60 seconds: see skill drift, reproducibly

This is a literal, self-contained transcript. Paste every command below into a clean shell — it fabricates two fake "skill" installs, edits one and deletes the other to simulate drift, then diffs. You will get exactly this output; nothing here depends on skills you already have installed.

sh
git clone https://github.com/wisechef-ai/loopskill-api && cd loopskill-apipython3 -m venv .venv && ./.venv/bin/pip install ./clialias loopskill=./.venv/bin/loopskill   # or add ./.venv/bin to PATHloopskill --version
# --- fabricate a "machine" with two skills, take a snapshot ---mkdir -p /tmp/loopskill-demo/home/.claude/skills/agent-reachmkdir -p /tmp/loopskill-demo/home/.claude/skills/recipescat > /tmp/loopskill-demo/home/.claude/skills/agent-reach/SKILL.md <<'EOF'---name: agent-reachdescription: Give your agent eyes on the internet.---Body v1.EOFcat > /tmp/loopskill-demo/home/.claude/skills/recipes/SKILL.md <<'EOF'---name: recipesdescription: Recipe search skill.---Body.EOFloopskill import --home /tmp/loopskill-demo/home -o /tmp/loopskill-demo/machine-a.lock.json
# --- simulate drift: edit one skill, delete the other ---cat > /tmp/loopskill-demo/home/.claude/skills/agent-reach/SKILL.md <<'EOF'---name: agent-reachdescription: Give your agent eyes on the internet.---Body v2 — updated tool list.EOFrm -rf /tmp/loopskill-demo/home/.claude/skills/recipes
loopskill diff /tmp/loopskill-demo/machine-a.lock.json - --home /tmp/loopskill-demo/home
loopskill 0.3.0loopskill import: wrote /tmp/loopskill-demo/machine-a.lock.json (2 skill(s) across 1 client(s))loopskill diff: /tmp/loopskill-demo/machine-a.lock.json  vs  <live scan>
[claude] DRIFT DETECTED  - only in /tmp/loopskill-demo/machine-a.lock.json: recipes  ~ changed:          agent-reach[codex] in sync (0 skill(s))[cursor] in sync (0 skill(s))[hermes] in sync (0 skill(s))
DRIFT FOUND

Exit code is 1 — drift found, script- and CI-friendly. Run loopskill diff again with nothing changed and exit code is 0. That's the whole pitch: two snapshots, one command, drift visible in the time it took to read this paragraph — on the skills you actually have, not a demo, once you drop --home.

import and diff make zero network calls — this isn't a promise in a docstring, it's a structural guarantee: the network-capable code lives in exactly one module (loopskill.pull) that import/diff never import, and cli/tests/test_loopskill_cli.py::test_import_and_diff_make_zero_network_calls proves it by breaking socket.socket for the duration of those commands.

Full CLI reference, lockfile format, and pull/apply (the two commands that DO touch the network, opt-in): cli/README.md.

What this repo actually is

Two things, and the CLI is the one to start with:

  1. cli/ — a local, offline-by-construction tool for the skills you already have on disk. No account, no server, no LoopSkill dependency for import/diff. Point it at any registry that serves the same well-known bundle-index shape for pull/apply, or never call those commands at all.
  2. app/ — a self-hostable FastAPI registry (this repo) that the CLI's pull/apply can optionally talk to, and that also serves a browsable catalog at loopskill.io. The registry is not the reason to start here — the CLI working on your own machine, before you've made an account, is.

Loops: two limits stated up front

The registry also serves 10 vetted loops (scripts/seed_starter_catalog.py). POST /api/loops/{slug}/run is synchronous and works anywhere. Putting a loop on a fleet member so it fires on a schedule is a second path with two constraints worth knowing before you build on it:

  1. A loop reports nothing unless its own prompt says to. Telemetry exists only because the loop's prompt calls scripts/loopskill-emit-run.sh. Nothing else observes a fire — not the scheduler, not the server. Omit that line and the loop runs forever while every dashboard shows zero. This is the reason loop_runs sat at 1 for a year.
  2. Cron materialization is Hermes-only. app/loop_apply.py writes the Hermes scheduler's ~/.hermes/cron/jobs.json, and nothing else speaks that format yet. On Codex, Claude or OpenCode hosts scripts/install-loop-apply.sh refuses rather than installing a cron that can never converge. The skill path is cross-vendor; the scheduled-loop path is not.

Both are covered end to end in docs/SELF_HOST.md.

Self-host the registry (optional, for pull/apply against your own instance)

sh
git clone https://github.com/wisechef-ai/loopskill-apicd loopskill-api && docker compose up

Zero-config: SQLite, auto-generated dev secrets, a seeded starter catalog. Your dev API key is printed on first boot. Full guide, including the Postgres/production path: docs/SELF_HOST.md.

Then run a loop — the runner is live (no LLM needed for verify-mode):

sh
# the zero-config Docker Compose stack always boots with this dev key# (override via WR_API_KEY in production) — same value the boot banner printscurl -X POST localhost:8200/api/loops/hello-world-loop/run \  -H "x-api-key: rec_dev_wiserecipes_local_testing_key"# → {"passed": true, "confinement": "bounded", "duration_seconds": 0.03, ...}

A fresh registry that doesn't just list a loop — it executes the loop's success check under enforced bounds and hands you a verdict.

What's actually in this codebase (and the honest answer to "why so big")

333 app Python files, 81,817 lines of app code, 118 Alembic migrations, 482 test files (clean-checkout counts; the local tree carries one untracked junk test that CI never sees), 2 GitHub stars, 0 forks (measured 2026-08-21 via gh repo view wisechef-ai/loopskill-api --json stargazerCount,forkCount).

That ratio is real and it isn't a good one. Issue #68 asked about it; the honest answer — including why the codebase grew from a working recipe-search product's battle-tested auth/Stripe/sandbox stack rather than from a blank registry, and the concrete cuts committed as a result — is in docs/decisions/2026-08-11-bundles0811-p4-issue-68-codebase-size.md. Every number above is checked against a live filesystem measurement by tests/test_readme_claims.py on every run — it fails the build if this paragraph drifts from reality the way #68's original numbers did.

Core API surface (self-hosted registry)

MethodPathDescription
GET/api/healthzDB health check
GET/api/skills/searchFull-text + vector hybrid skill search
GET/api/skills/{slug}Skill detail + versions
GET/api/bundles/discoverBrowse public bundles
GET/api/loopsList loops (with their safety contracts)
GET/api/loops/{slug}Loop detail — contract, run count, rating
POST/api/loopsPublish a loop (validates the contract)
POST/api/loops/{slug}/runRun the loop's verification → objective pass/fail
POST/api/loops/{slug}/rateRate a loop 1–5 (social-proof signal)
GET/api/personalitiesList deployable personalities

MCP-native: agents (Claude Code, Cursor, anything speaking MCP) discover and install over the protocol. There's also a signed-URL tarball path for direct fetch.

Architecture

FastAPI + SQLAlchemy. The same alembic migration chain runs on SQLite (self-host) and Postgres (hosted) — no create_all drift; the SQLite boot replays the real migrations, so what you self-host is what production runs. Full module layout: AGENTS.md.

Auth flow

APIKeyMiddleware.dispatch()  └─ validate_key(db, x-api-key)       └─ request.state.auth_ctx = AuthContext(scope, user_id, tier, …)            └─ REST routes / MCP tools / runner call authz.can_*() predicates

API keys are rec_-prefixed and passed in the x-api-key header. Most read endpoints (search, detail, discover) are unauthenticated. Free-tier skills install anonymously with no key (200 + tarball); installing a paid-tier skill, publishing, running, and rating all require a key.

Develop

bash
python -m venv .venv && source .venv/bin/activatepip install -r requirements.txtpre-commit install                       # ruff, bandit, mypy --strict, actionlint, yamllint
pytest -q                                # fast runpytest -n auto --cov=app --cov-fail-under=80   # the CI gate
alembic upgrade head                     # apply migrations before first start (non-SQLite)uvicorn app.main:app --reload --port 8201

Sandbox (Linux only): the kernel sandbox (app/sandbox/) needs firejail or bubblewrap. Where neither is functional (macOS, hardened containers), the loop runner falls back to bounded mode — POSIX rlimits + scrubbed env + isolated workspace — so loops still run; the response declares which confinement level it achieved. Multi-tenant fleet owners set WR_LOOP_RUN_REQUIRE_SANDBOX=true to refuse bounded-mode execution and require a real kernel sandbox.

Contributor guide for AI agents: AGENTS.md.

Why open-core

The whole registry is the OSS product (MPL-2.0). Self-host it anywhere — docker compose up is the complete experience, not a teaser, and nothing phones home. The hosted plan is "don't run it yourself," never a feature gate. Same posture as n8n / PostHog / Supabase.

License

MPL-2.0 — see LICENSE. The whole registry is open source; we only charge for hosting it.

Links

Source: README.md at commit 2e141d1

Tools

0
Tool metadata has not been indexed yet.

Version history

1
  1. v0.9.65LatestOct 11, 2026