Verified human + agent skill arena protocol. Phase 1 testnet is live on Base Sepolia: six games, on-chain tournament settlement, three AI features, and permissionless sponsor-funded prize pools. Pure infrastructure — no custody, no protocol-level KYC, sweepstakes-safe at the storage layer. The marketing site (https://www.skillos.games) lives in a separate repo — skillos-apex — and is not part of t
Add this skill
npx mdskills install youngstar-eth/skillosComprehensive project documentation lacking actionable agent instructions or skills
Skill economy infrastructure for the agent era.
Verified human + agent skill arena protocol. Phase 1 testnet is live on Base Sepolia: six games, on-chain tournament settlement, three AI features, and permissionless sponsor-funded prize pools. Pure infrastructure — no custody, no protocol-level KYC, sweepstakes-safe at the storage layer.
Brand evolution: the public-facing rebrand to SkillOS is queued for the Phase 2 mainnet cutover window.
The marketing site (https://www.skillos.games) lives in a separate repo — skillos-apex — and is not part of this monorepo.
SkillOS is a 5-actor protocol:
SponsorshipModule. Soulbound SponsorReceipt (ERC-5192) issued per sponsorship.Architectural invariants — non-negotiable, see CLAUDE.md for the full list:
TournamentPool. Foundation treasury never funds prize pools. A buggy module physically cannot corrupt segregated accumulators.trustedSigner attestation. Phase 1 reality. Decentralizes through Phase 5.apps/
2048 — reference implementation; hosts public x402 endpoints
wordle, sudoku, minesweeper, clicker, match3
— solo-tournament flow, mirror 2048 architecture
sponsor — permissionless prize-pool funding dashboard
packages/
ai-coach — Claude prompt library (Coach / Recap / Anti-Cheat per-game)
contracts — ABIs + addresses + game-slug helpers (re-exports from /contracts/out)
duel-backend — solo + duel API handlers, settle, settle-guard, cron
game-types — shared TypeScript types (Duel state, status enums)
lib-shared — Supabase client, http helpers, attestation, RPC utilities
sp-engine — Skill Points calculation engine
ui — design system + shared components
contracts/ — Foundry workspace (Solidity 0.8.26)
src/ — Solidity sources
test/ — Foundry tests (extend the settle-guard tripwire pattern)
lib/ — vendored deps (openzeppelin-contracts, forge-std)
deployments/ — chain deploy artifacts (e.g. sponsor-stack-base-sepolia.json)
supabase/migrations/ — Postgres migration files (forward-only)
docs/ — sponsor-flow.md, audit/, superpowers/
reports/ — point-in-time audits
scripts/ — backfill-sp, jury-tournaments seed, x402-smoke
@skillos/sdk — planned Phase 2 public release. Not yet scaffolded on disk;
do not import from this name yet.
2048 · Wordle · Sudoku · Minesweeper · Clicker · Match3
Each lives at .skillos.games. 2048 is the reference implementation and currently hosts the public x402 endpoints; the other five mirror its solo-tournament flow.
| Feature | Role | Model |
|---|---|---|
| AI Coach | Post-match tactical feedback | Claude Sonnet 4.6 |
| AI Recap | Match summary | Claude Haiku 4.5 |
| AI Anti-Cheat | Server-side plausibility check on submit | Claude Haiku 4.5 |
Generation lives in packages/ai-coach. Per-flow handlers live in packages/duel-backend/src/api. AI is exposed via per-app routes at /api/tournaments/solo/[runId]/{coach,recap,plausibility} and POSTed from the result-page mount, not from the submission path. AI prompt formulations and anti-cheat detection methods are intentionally not documented in this README — see packages/ai-coach source.
Foundry workspace at /contracts/. Solidity 0.8.26, optimizer 200 runs, no via_ir. Chain ID 84532.
Deployed v2.1 stack (April 29, 2026). Authoritative addresses live in contracts/deployments/sponsor-stack-base-sepolia.json:
| Contract | Address | Notes |
|---|---|---|
TournamentPool v2.1 | 0x52049b812780134d2F69D6c20C2ef881D49702da | Prize pool escrow, retry-fee collection, settlement (storage-segregated) |
SponsorshipModule | 0xD76670adB574A4C8D06dfF47127e7143d780ff87 | Permissionless prize-pool funding |
SponsorReceiptSBT | 0xCCC183c72D666A16E03bf38E8c2DFa8a68b2e768 | Soulbound receipt, ERC-5192 |
MockSanctionsOracle | 0x0CB38F0A0511aF07FC34A20DCaB9e2Fc8061B1CC | Pre-tx sanctions screen (mock; mainnet-gated swap) |
Verification: all four contracts verified on Blockscout (https://base-sepolia.blockscout.com/). Etherscan V2 API previously rejected bytecode-identical compilations; the deployment artifact records the switch.
Other Solidity sources in-tree (not part of the deployed v2.1 stack): ChallengeEscrow.sol (async-duel stake escrow, currently paused), SkillbaseAnchor.sol (daily SP-ledger snapshot anchor), ArcadePool.sol.
ABIs and address constants are exported from @skillos/contracts.
Tests: 156 Foundry tests passing across 6 test suites (forge test). The settle-guard suite is the tripwire for the storage-segregation invariant — extend, don't skip.
v2.2 (Phase 2): developer fee splitter with on-chain 70/30 enforcement and a Foundry invariant test for accumulator reconciliation. Full spec deferred to docs/adr/0001-v22-fee-splitter.md when the ADR system activates in Phase 2 — implementation details will follow contract auditor consultation. Mainnet deployment is audit-gated; see Phase 2 below.
Economic flows (Phase 1). 1 USDC retry fees split 70/30 dev/platform (off-chain accounting in Phase 1; moves on-chain in v2.2). Permissionless sponsor funding routes directly into segregated prize-pool slots via SponsorshipModule. AI-lab data licensing settles per-call via x402 micropayments — no subscription tier.
On-chain. See Smart contracts above.
Off-chain. Next.js App Router on Vercel + Postgres on Supabase.
simpl3s-projects. Shared code lives in /packages. Turborepo 2.3.3 orchestrates dev/build/lint/typecheck across the workspace./api/cron/* routes drive tournament create + settle (signed by STUDIO_PRIVATE_KEY, gated on CRON_SECRET). Cron is the only writer of tournament state./api/tournaments/solo/[runId]/{coach,recap,plausibility}. AI is fire-on-mount — Coach/Recap components POST only when the result page is viewed.apps/sponsor) is the dashboard for prize-pool funding; it indexes SponsorshipModule events via a daily cron.Two numbering systems coexist in the codebase: a product roadmap (Phase 1 → 5, this section) and engineering-internal contract versions (v2.0 → v2.1 → v2.2, Smart Contracts section above). Don't reconcile — the audiences differ. See CLAUDE.md.
@skillos/sdk public release, agent player-class API, SkillOS rebrand cutover, sponsor onboarding pipeline. Mainnet contingent on sweepstakes legal review. Public timeline tracks apex (skillos-apex); internal sprints may target tighter dates.Deferred to Phase 2 v2.2 mainnet cutover:
@skillos/* package names remain locked until v2.2 deploy + Vercel project rename + DNS migration@skillos/sdk) will be minted directly under the new namespace at publication time*.skillos.games URLs locked until DNS cutoverSkillbaseAnchor.sol and other contract identifier renames locked until v2.2 deployapps/2048 x402 paid-API response strings (via-skillbase → via-skillos) flip with route handler changesRequirements:
forge, cast, anvilInstall + dev:
npm install # workspace install (all apps + packages)
npm run dev # turbo runs every app in parallel
npm run dev:2048 # 2048 only (convenience alias)
npm run dev -w @skillos/app-wordle # any other game
Health check (any app, after dev): http://localhost:3000/api/health.
Environment variables. Each app has its own .env.local.example — there is no root-level template. Copy per app:
cp apps/2048/.env.local.example apps/2048/.env.local
# repeat for each app you intend to run
cp contracts/.env.example contracts/.env # Foundry RPC + signer
Required keys (per app, see each .env.local.example for the canonical list): Supabase URL + service-role key, STUDIO_PRIVATE_KEY, CRON_SECRET, CDP / x402 facilitator keys (2048 only).
Foundry tests:
cd contracts
forge test # 156 tests, 6 suites
forge test --match-contract TournamentPool # focused suite
Database (Supabase). Migrations are forward-only and live in supabase/migrations/ (currently 11 files, v2_*.sql lineage starting 2026-04-21). Apply via the Supabase REST API or supabase db push.
Vercel deployment. Each app is its own Vercel project; install/build commands are pinned via per-app vercel.json (Vercel UI parsing has historically truncated workspace-relative install commands — do not rely on the dashboard for these). See CLAUDE.md for the canonical git author identity required for pushes to Vercel-linked branches.
No CI today. .github/workflows/ does not exist. PR checks are honor-system in Phase 1; required typecheck + lint + Foundry test gates land with the Phase 2 discipline transition.
vercel, gh, cast, forge, supabase, npm over dashboard manual work.docs/adr/) for major decisions, pre-commit hooks (typecheck + secret scan), integration test expansion.See CLAUDE.md for the full operational playbook.
Currently private. License decisions deferred to the Phase 2 mainnet / SDK launch window.
apps/2048/src/app/api/public/README.md, live tx proof at reports/x402-live-proof.md.CLAUDE.md — agent-operational guidance, architectural invariants, decision priority orderdocs/sponsor-flow.md — sponsorship architecture, sanctions oracle, end-user flowdocs/superpowers/specs/2026-04-21-skillbase-v2-backend-design.md — V2 backend spec (locked)docs/audit/task-10-v2-cutover/README.md — V2 cutover reconciliationreports/codebase-hygiene-20260424-1532.md — pre-submission code audit (categories A–L)Install via CLI
npx mdskills install youngstar-eth/skillosSkillOS is a free, open-source AI agent skill. Verified human + agent skill arena protocol. Phase 1 testnet is live on Base Sepolia: six games, on-chain tournament settlement, three AI features, and permissionless sponsor-funded prize pools. Pure infrastructure — no custody, no protocol-level KYC, sweepstakes-safe at the storage layer. The marketing site (https://www.skillos.games) lives in a separate repo — skillos-apex — and is not part of t
Install SkillOS with a single command:
npx mdskills install youngstar-eth/skillosThis downloads the skill files into your project and your AI agent picks them up automatically.
SkillOS works with Claude Code, Claude Desktop, Cursor, Vscode Copilot, Windsurf, Continue Dev, Codex, Gemini Cli, Amp, Roo Code, Goose, Opencode, Trae, Qodo, Command Code. Skills use the open SKILL.md format which is compatible with any AI coding agent that reads markdown instructions.