LoopSkill

LoopSkill

Una CLI local para las habilidades que ya tienes, más un registro auto-alojable para obtener más. Empieza con la CLI — no necesita cuenta y no realiza ninguna llamada de red para import/diff.

---

60 segundos: ve la deriva de habilidades, de forma reproducible

Esta es una transcripción literal y autocontenida. Pega cada comando a continuación en una shell limpia — fabrica dos instalaciones falsas de "habilidades", edita una y elimina la otra para simular deriva, luego compara. Obtendrás exactamente esta salida; nada aquí depende de habilidades que ya tengas instaladas.

git clone https://github.com/wisechef-ai/loopskill-api && cd loopskill-api
python3 -m venv .venv && ./.venv/bin/pip install ./cli
alias loopskill=./.venv/bin/loopskill   # or add ./.venv/bin to PATH
loopskill --version

# --- fabricate a "machine" with two skills, take a snapshot ---
mkdir -p /tmp/loopskill-demo/home/.claude/skills/agent-reach
mkdir -p /tmp/loopskill-demo/home/.claude/skills/recipes
cat > /tmp/loopskill-demo/home/.claude/skills/agent-reach/SKILL.md <<'EOF'
---
name: agent-reach
description: Give your agent eyes on the internet.
---
Body v1.
EOF
cat > /tmp/loopskill-demo/home/.claude/skills/recipes/SKILL.md <<'EOF'
---
name: recipes
description: Recipe search skill.
---
Body.
EOF
loopskill 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-reach
description: Give your agent eyes on the internet.
---
Body v2 — updated tool list.
EOF
rm -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.0
loopskill 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

El código de salida es 1 — se encontró deriva, apto para scripts y CI. Ejecuta loopskill diff again with nothing changed and exit code is 0. Esa es toda la propuesta: dos instantáneas, un comando, deriva visible en el tiempo que tomó leer este párrafo — en las habilidades que realmente tienes, no una demo, una vez que elimines --home.

import y diff hacen cero llamadas de red — esto no es una promesa en un docstring, es una garantía estructural: el código con capacidad de red vive en exactamente un módulo (loopskill.pull) que import/diff nunca importan, y cli/tests/test_loopskill_cli.py::test_import_and_diff_make_zero_network_calls lo demuestra rompiendo socket.socket durante la duración de esos comandos.

Referencia completa de la CLI, formato de lockfile, y pull/apply (los dos comandos que SÍ tocan la red, opt-in): cli/README.md.

---

Qué es realmente este repositorio

Dos cosas, y la CLI es con la que debes empezar:

1. cli/ — una herramienta local, offline por construcción, para las habilidades que ya tienes en disco. Sin cuenta, sin servidor, sin dependencia de LoopSkill para import/diff. Apúntala a cualquier registro que sirva la misma forma bien conocida de índice de paquetes para pull/apply, o nunca llames a esos comandos en absoluto.
2. app/ — un registro FastAPI auto-alojable (este repositorio) con el que la CLI pull/apply puede hablar opcionalmente, y que también sirve un catálogo navegable en loopskill.io. El registro no es la razón para empezar aquí — la CLI funcionando en tu propia máquina, antes de que crees una cuenta, lo es.

Bucles: dos límites declarados de antemano

El registro también sirve 10 bucles verificados (scripts/seed_starter_catalog.py). POST /api/loops/{slug}/run es síncrono y funciona en cualquier lugar. Poner un bucle en un miembro de flota para que se dispare en un horario es un segundo camino con dos restricciones que vale la pena conocer antes de construir sobre él:

1. Un bucle no reporta nada a menos que su propio prompt lo diga. La telemetría existe solo porque el prompt del bucle llama a scripts/loopskill-emit-run.sh. Nada más observa un disparo — ni el programador, ni el servidor. Omite esa línea y el bucle se ejecuta para siempre mientras cada panel muestra cero. Esta es la razón por la que loop_runs se mantuvo en 1 durante un año.
2. La materialización de cron es solo para Hermes. app/loop_apply.py escribe el ~/.hermes/cron/jobs.json del programador de Hermes, y nada más habla ese formato todavía. En hosts de Codex, Claude u OpenCode, scripts/install-loop-apply.sh se niega en lugar de instalar un cron que nunca puede converger. El camino de habilidades es multiplataforma; el camino de bucles programados no lo es.

Ambos están cubiertos de principio a fin en docs/SELF_HOST.md.

Auto-aloja el registro (opcional, para pull/apply contra tu propia instancia)

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

Configuración cero: SQLite, secretos de desarrollo autogenerados, un catálogo inicial sembrado. Tu clave de API de desarrollo se imprime en el primer arranque. Guía completa, incluida la ruta de Postgres/producción: docs/SELF_HOST.md.

Luego ejecuta un bucle — el ejecutor está activo (no se necesita LLM para el modo de verificación):

# the zero-config Docker Compose stack always boots with this dev key
# (override via WR_API_KEY in production) — same value the boot banner prints
curl -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, ...}

Un registro nuevo que no solo lista un bucle — ejecuta la verificación de éxito del bucle bajo límites impuestos y te entrega un veredicto.

---

Qué hay realmente en este código (y la respuesta honesta a "por qué es tan grande")

314 archivos de aplicación Python, 77,366 líneas de código de aplicación, 115 migraciones de Alembic, 442 archivos de prueba (conteos de checkout limpio; el árbol local lleva una migración basura sin rastrear + prueba que CI nunca ve), 2 estrellas de GitHub, 0 forks (medido 2026-08-21 vía gh repo view wisechef-ai/loopskill-api --json stargazerCount,forkCount).

Esa proporción es real y no es buena. Issue #68 preguntó al respecto; la respuesta honesta — incluyendo por qué el código creció desde el stack probado de auth/Stripe/sandbox de un producto funcional de búsqueda de recetas en lugar de desde un registro en blanco, y los recortes concretos comprometidos como resultado — está en docs/decisions/2026-08-11-bundles0811-p4-issue-68-codebase-size.md. Cada número anterior se verifica contra una medición en vivo del sistema de archivos por tests/test_readme_claims.py en cada ejecución — falla la compilación si este párrafo se desvía de la realidad como lo hicieron los números originales de #68.

---

Superficie de API principal (registro auto-alojado)

Método	Ruta	Descripción
GET	/api/healthz	Verificación de salud de la base de datos
GET	/api/skills/search	Búsqueda híbrida de habilidades de texto completo + vectorial
GET	/api/skills/{slug}	Detalle de habilidad + versiones
GET	/api/bundles/discover	Explorar paquetes públicos
GET	/api/loops	Listar bucles (con sus contratos de seguridad)
GET	/api/loops/{slug}	Detalle de bucle — contrato, conteo de ejecuciones, calificación
POST	/api/loops	Publicar un bucle (valida el contrato)
POST	/api/loops/{slug}/run	Ejecutar la verificación del bucle → aprobado/fallido objetivo
POST	/api/loops/{slug}/rate	Calificar un bucle 1–5 (señal de prueba social)
GET	/api/personalities	Listar personalidades desplegables

Nativo de MCP: los agentes (Claude Code, Cursor, cualquier cosa que hable MCP) descubren e instalan a través del protocolo. También hay una ruta de tarball con URL firmada para obtención directa.

Arquitectura

FastAPI + SQLAlchemy. La misma cadena de migraciones de alembic se ejecuta en SQLite (auto-alojado) y Postgres (alojado) — sin deriva de create_all; el arranque de SQLite reproduce las migraciones reales, así que lo que auto-alojas es lo que ejecuta producción. Diseño completo de módulos: AGENTS.md.

Flujo de autenticación

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

Las claves de API tienen prefijo rec_ y se pasan en el encabezado x-api-key. La mayoría de los endpoints de lectura (búsqueda, detalle, descubrimiento) no están autenticados. Las habilidades de nivel gratuito se instalan anónimamente sin clave (200 + tarball); instalar una habilidad de nivel de pago, publicar, ejecutar y calificar requieren una clave.

---

Desarrollo

python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
pre-commit install                       # ruff, bandit, mypy --strict, actionlint, yamllint

pytest -q                                # fast run
pytest -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 (solo Linux): el sandbox del kernel (app/sandbox/) necesita firejail o bubblewrap. Donde ninguno es funcional (macOS, contenedores endurecidos), el ejecutor de bucles recurre al modo acotado — rlimits POSIX + entorno depurado + espacio de trabajo aislado — para que los bucles aún se ejecuten; la respuesta declara qué nivel de confinement logró. Los propietarios de flotas multiinquilino establecen WR_LOOP_RUN_REQUIRE_SANDBOX=true para rechazar la ejecución en modo acotado y requerir un sandbox de kernel real.

Guía de contribución para agentes de IA: AGENTS.md.

---

Por qué open-core

Todo el registro es el producto OSS (MPL-2.0). Auto-alójalo en cualquier lugar — docker compose up es la experiencia completa, no un adelanto, y nada llama a casa. El plan alojado es "no lo ejecutes tú mismo", nunca una puerta de funciones. Misma postura que n8n / PostHog / Supabase.

Licencia

MPL-2.0 — ver LICENSE. Todo el registro es de código abierto; solo cobramos por alojarlo.

Enlaces

• CLI (empieza aquí): cli/README.md
• Inicio: loopskill.io
• Guía de auto-alojamiento: docs/SELF_HOST.md
• Respuesta al Issue #68: docs/decisions/2026-08-11-bundles0811-p4-issue-68-codebase-size.md
• Contribución (agentes de IA): AGENTS.md