LoopSkill

LoopSkill

すでにお持ちのスキルを扱うローカル CLI と、追加のスキルを取得できるセルフホスト可能なレジストリです。 まずは CLI から始めましょう。アカウントは不要で、import／diff ではネットワーク通信を行いません。

---

コーディングエージェントで始める

以下を Claude Code、Codex、Cursor、またはシェルを使える任意のコーディングエージェントに貼り付けてください。

Clone https://github.com/wisechef-ai/loopskill-api, read AGENT_SETUP.md in it,
and follow it to install the loopskill CLI and verify it with the drift demo.
Only set up the self-hosted registry (Docker) if I ask for it.
Ask me before deleting any data, stopping containers or processes, using sudo,
or writing into my real skill directories. Never paste API keys or tokens
into this chat. When it works, show me the verify output and what to do next.

エージェントは次のことを行います。

• まず Python、venv、デモ用ディレクトリを確認し、削除または上書きが必要なものがあれば停止します。
• CLI をプロジェクト内の .venv にインストールし、パスを指定して実行します。
• 以下のドリフトデモで動作を確認します（ドリフトを検出した後、同期済みの状態になります）。
• 実際のスキルで使う次のコマンドと、ネットワーク通信またはファイル書き込みを行うコマンドを案内します。

---

60 秒でスキルのドリフトを再現可能な形で確認

以下は、文字どおりそのまま実行できる、自己完結したログです。以下のコマンドをすべてクリーンなシェルに貼り付けてください。2 つの偽の「スキル」インストールを作成し、片方を編集し、もう片方を削除してドリフトを再現し、差分を表示します。すでにインストール済みのスキルには一切依存せず、出力はまったく同じになります。

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

終了コードは 1 です。ドリフトが検出されたことを示し、スクリプトや CI での使用にも適しています。何も変更せずに loopskill diff をもう一度実行すると、終了コードは 0 になります。これが要点です。2 つのスナップショットを 1 つのコマンドで比較し、この段落を読む間にドリフトを確認できます。--home を外せば、デモではなく実際にお使いのスキルを対象にできます。

import と diff はネットワーク通信を一切行いません。これはドックストリングでの約束ではなく、構造上保証されています。ネットワーク通信を行うコードはただ 1 つのモジュール（loopskill.pull）に置かれており、import／diff から読み込まれることはありません。また、 cli/tests/test_loopskill_cli.py::test_import_and_diff_make_zero_network_calls では、これらのコマンドの実行中に socket.socket を無効化して、このことを実証しています。

CLI の完全なリファレンス、ロックファイル形式、およびネットワークに接続する 2 つのオプトインコマンド pull／apply については、cli/README.md をご覧ください。

---

このリポジトリの実態

機能は 2 つあります。まずは CLI から始めてください。

1. cli/ — すでにディスク上にあるスキルを扱う、オフラインで動作するよう設計されたローカルツールです。アカウントもサーバーも不要で、import／diff に LoopSkill は必要ありません。pull／apply では、同じ既知のバンドルインデックス形式を提供する任意のレジストリを指定できます。また、これらのコマンドをまったく使わないこともできます。
2. app/ — FastAPI ベースのセルフホスト可能なレジストリです（このリポジトリ）。CLI の pull／apply から任意で接続でき、loopskill.io で閲覧可能なカタログも提供します。このレジストリがここから始める理由ではありません。アカウントを作成する前でも、自分のマシンで CLI を使えることが理由です。

ループ：最初に知っておくべき2つの制約

レジストリでは、審査済みのループ10件も提供しています（scripts/seed_starter_catalog.py）。 POST /api/loops/{slug}/run は同期処理で、どこでも動作します。 フリートメンバーにループを設定してスケジュール実行する方法には、導入前に知っておくべき2つの制約があります。

1. ループは、独自のプロンプトに指示がなければ何も報告しません。 テレメトリーが記録されるのは、ループのプロンプトが scripts/loopskill-emit-run.sh を呼び出す場合だけです。実行を監視するものはほかにありません。スケジューラーもサーバーも監視しません。この行を省くと、ループは実行され続ける一方、すべてのダッシュボードの表示はゼロのままです。loop_runs が1のまま1年間変わらなかったのは、このためです。
2. Cron の生成に対応しているのは Hermes のみです。 app/loop_apply.py は Hermes スケジューラーの ~/.hermes/cron/jobs.json に書き込みます。現時点で、この形式に対応しているのは Hermes だけです。Codex、Claude、OpenCode のホストでは、収束することのない Cron をインストールしないよう、scripts/install-loop-apply.sh が処理を拒否します。スキルの仕組みはベンダー横断で使えますが、スケジュール実行するループの仕組みはそうではありません。

どちらもdocs/SELF_HOST.mdで、最初から最後まで説明しています。

レジストリをセルフホストする（任意。独自のインスタンスで pull／apply を使う場合）

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

設定不要で、SQLite、自動生成される開発用シークレット、シード済みスターターカタログを利用できます。 開発用 API キーは初回起動時に表示されます。Postgres／本番環境での手順を含む完全なガイドは、**docs/SELF_HOST.md**を参照してください。

次はループを実行しましょう — ランナーは稼働中です（verify-mode では LLM は不要です）。

# 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, ...}

ループをただ一覧表示するだけでなく、強制された範囲内で成功判定を実行し、結果を返す新しいレジストリです。

---

このコードベースの実態（そして「なぜこんなに大きいのか」への率直な回答）

アプリの Python ファイルは347個、アプリコードは85,076行、Alembic マイグレーションは119件、テストファイルは506個（クリーンチェックアウト時の数）です。GitHub スターは2個、フォークは0件です（2026-08-21に gh repo view wisechef-ai/loopskill-api --json stargazerCount,forkCount で測定）。

この比率は事実ですが、好ましいものではありません。Issue #68でこの点が問われました。率直な回答 — このコードベースが空のレジストリからではなく、実運用で検証済みの認証／Stripe／サンドボックスのスタックを持つレシピ検索製品から成長した理由と、その結果として実施した具体的な削減内容を含む — は docs/decisions/2026-08-11-bundles0811-p4-issue-68-codebase-size.mdに記載しています。 上記の数値はすべて、実行のたびに tests/test_readme_claims.py がライブのファイルシステム計測値と照合します。#68で当初の数値が現実と食い違ったように、この段落の内容が実態からずれていれば、ビルドは失敗します。

---

コア API の概要（セルフホストのレジストリ）

Method	Path	Description
GET	/api/healthz	DB のヘルスチェック
GET	/api/skills/search	全文検索とベクトル検索を組み合わせたスキル検索
GET	/api/skills/{slug}	スキルの詳細とバージョン
GET	/api/bundles/discover	公開バンドルの閲覧
GET	/api/loops	ループの一覧（安全性の契約を含む）
GET	/api/loops/{slug}	ループの詳細 — 契約、実行回数、評価
POST	/api/loops	ループの公開（契約を検証）
POST	/api/loops/{slug}/run	ループの検証を実行 → 目標の達成／未達成
POST	/api/loops/{slug}/rate	ループを1～5で評価（社会的証明のシグナル）
GET	/api/personalities	デプロイ可能なパーソナリティの一覧

MCP ネイティブ対応です。エージェント（Claude Code、Cursor、MCP を話すあらゆるもの）は、プロトコル経由で検出してインストールできます。直接取得するための署名付き URL を使った tarball の方法もあります。

アーキテクチャ

FastAPI + SQLAlchemy を使用しています。同じ Alembic マイグレーションチェーンが、SQLite（セルフホスト）と Postgres（ホスト環境）の両方で動作します。create_all による差異はありません。SQLite の起動時には実際のマイグレーションが再適用されるため、セルフホスト環境で動作するものが本番環境でも動作します。モジュール構成の全容は**AGENTS.md**を参照してください。

認証フロー

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 キーには rec_ というプレフィックスが付き、x-api-key ヘッダーで渡します。ほとんどの 読み取りエンドポイント（検索、詳細、検出）は認証不要です。無料プランの スキルはキーなしで匿名インストールできます（200 + tarball）。有料プランのスキルのインストール、 公開、実行、評価にはすべてキーが必要です。

---

開発

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

サンドボックス（Linux のみ）： カーネルサンドボックス（app/sandbox/）には firejail または bubblewrap が必要です。 どちらも機能しない環境（macOS、セキュリティ強化コンテナー）では、ループランナーは 制限付き モードにフォールバックします。POSIX rlimits + 環境変数の除去 + ワークスペースの分離により、 ループを引き続き実行できます。レスポンスには、達成した confinement レベルが示されます。マルチテナントのフリート運用者は WR_LOOP_RUN_REQUIRE_SANDBOX=true を設定することで、制限付きモードでの実行を拒否し、実際のカーネルサンドボックスを必須にできます。

AI エージェント向けのコントリビューターガイド：AGENTS.md。

---

オープンコアを採用する理由

レジストリ全体が OSS 製品（MPL-2.0）です。どこでもセルフホストでき、 docker compose up ですべての機能を利用できます。これはお試し版ではなく、外部への 情報送信もありません。ホステッドプランは「自分で運用しない」という選択肢であり、機能を 制限するものではありません。n8n / PostHog / Supabase と同じ方針です。

ライセンス

MPL-2.0 — 詳細は LICENSE をご覧ください。レジストリ全体がオープンソースであり、ホスティングの料金のみをいただきます。

リンク

• CLI（まずはこちら）： cli/README.md
• ホーム： loopskill.io
• セルフホストガイド： docs/SELF_HOST.md
• Issue #68 の回答： docs/decisions/2026-08-11-bundles0811-p4-issue-68-codebase-size.md
• コントリビューション（AI エージェント向け）： AGENTS.md