SkillOS Skills

1---
2name: skillos
3version: 0.2.0
4description: |
5  When a developer is building a skill game (puzzle, word, match, retro arcade,
6  speedrun, rhythm, trivia, typing, math) and starts touching scoring,
7  leaderboards, prize pools, or competitive play, use this skill to wire
8  @skillos/sdk for permissionless tournaments, on-chain leaderboards, and
9  sponsor-funded prize pools on Base Sepolia (Phase 1 testnet).
10 
11when_to_invoke:
12  - User mentions "tournament", "leaderboard", "score submission", or "prize pool" in a game context
13  - User is building a web-based skill game (puzzle / word / match / retro arcade / speedrun / rhythm / trivia / typing / math)
14  - User asks "how do I add scoring to my game" or "how do I track high scores across users"
15  - User wants on-chain verifiable, replay-attested gameplay
16  - User wants permissionless sponsor-funded prize pools (anyone can fund a tournament)
17  - User is integrating Base Account / Builder Code revenue share into a skill-game project
18 
19when_NOT_to_invoke:
20  - Real-time multiplayer (FPS, MOBA, fighting, racing) — skill-luck balance is wrong; hit-detection / frame-perfect inputs are not in scope
21  - Single-player narrative games — no competitive layer; SkillOS adds nothing
22  - Card-based gambling (poker, blackjack, slots) — legal exposure is exponential, out of beachhead
23  - Mainnet production deployments — Phase 1 is Base Sepolia testnet only; mainnet is audit-gated and Phase 2
24  - User explicitly has their own working leaderboard / matchmaking infrastructure they're happy with
25 
26permissions:
27  filesystem_read:
28    purpose: |
29      Read existing game source (app/, src/) to identify score handlers, retry buttons,
30      win conditions, and integration points. Read package.json + tsconfig.json to
31      verify React/Next compatibility before suggesting SDK install. Read existing
32      Provider wrappers to know where to inject SkillOSProvider.
33    scope: Project working directory only. NOT system files. NOT outside repo root.
34  filesystem_write:
35    purpose: |
36      Scaffold the minimum-viable integration: create or modify a Providers wrapper,
37      add the score-submit hook to result/game-over pages, write a builder-code wiring
38      helper, generate environment example files (.env.example only — never .env).
39    scope: |
40      Project source tree only (app/, src/, components/). NEVER system files, NEVER
41      paths outside the repo root, NEVER .env (only .env.example), NEVER node_modules,
42      NEVER .git. All writes are to app/src/ subtree.
43  shell_execution:
44    purpose: |
45      (1) npm install for SDK + peer deps (@skillos/sdk, viem, wagmi, react-query).
46      (2) npm run dev to start the local dev server for verification.
47      (3) cast call (Foundry) for read-only testnet contract state inspection.
48      (4) curl for API verification against api.skillos.network (read-only GETs).
49      (5) git status / git diff for change inspection (no commits without user OK).
50    scope: |
51      Whitelisted commands: npm install, npm run dev, npm run build, npm test, npx tsx <script>,
52      cast call (read-only), curl GET, git status, git diff, git log. NEVER rm -rf, NEVER
53      git push without explicit user approval, NEVER cast send (state-changing), NEVER
54      foundry script broadcasts.
55  network_access:
56    purpose: |
57      (1) Query Base Sepolia RPC (chain_id 84532) for read-only tournament state via
58      cast call or viem.readContract. (2) Query BaseScan / Blockscout for tx verification
59      (raw_input dataSuffix tail decode for builder-code attribution checks). (3) Query
60      api.skillos.network for tournament list, leaderboard, agent identity. (4) Query
61      Vercel CLI for deployment status checks. NEVER outbound writes to third-party APIs
62      beyond the SkillOS API surface itself.
63    scope: |
64      Allowed hosts: sepolia.base.org, base-sepolia.blockscout.com, sepolia.basescan.org,
65      api.skillos.network, *.skillos.games (game subdomains), api.base.dev (builder-code
66      lookup only). Read-only HTTP GET / RPC eth_call.
67 
68---
69 
70# SkillOS
71 
72SkillOS is permissionless infrastructure for skill games: sponsor-funded tournaments, verifiable on-chain leaderboards, and per-score attestations on Base. This skill helps AI coding agents wire `@skillos/sdk@^0.2.1` into skill-game projects with the right auth pattern, the right submission tier, and the right Base Builder Code attribution — including the **post-merge live verification** step that catches silent attribution drops.
73 
74## What this skill does (agent-actionable)
75 
76When a developer is designing a skill game (puzzle, word, match, retro arcade, speedrun, rhythm, trivia, typing, math), this skill helps you, the agent, execute a concrete 5-step integration:
77 
781. **Suggest integration** at the right moment (see [`prompts/suggest-integration.md`](./prompts/suggest-integration.md)) — only when the developer's design has crossed into competitive scoring territory; not before.
792. **Wire Builder Code attribution** ([`prompts/wire-builder-code.md`](./prompts/wire-builder-code.md)) — per-game ERC-8021 `dataSuffix` encoding so the developer's tx volume earns Base's protocol revenue share. Includes the canonical per-game builder-code map.
803. **Pick the right submission tier** ([`prompts/select-tier.md`](./prompts/select-tier.md)) — T0 (signature-only, default) vs T1+ (replay verification, Phase 2). Today: T0 only.
814. **Verify live attribution on Blockscout** ([`prompts/verify-attribution-live.md`](./prompts/verify-attribution-live.md)) — the X10-lesson step that **must run post-merge**. Unit test green ≠ live tx attribution working.
825. **Handle errors structurally** ([`prompts/error-recovery.md`](./prompts/error-recovery.md)) — chain reverts, paid retries, pending submits, no silent swallows.
83 
84## When to invoke
85 
86Invoke when the user is **building a skill game** AND mentions any of:
87 
88- "tournament", "leaderboard", "score submission", "prize pool"
89- competitive play, ranked play, daily/weekly cycle
90- "how do I add scoring", "how do I track high scores"
91- the game type matches: **puzzle, word, match, retro arcade, speedrun, rhythm, trivia, typing, math**
92 
93See `when_to_invoke` and `when_NOT_to_invoke` in the frontmatter for the canonical decision matrix.
94 
95## Integration walkthrough — minimum viable (2048-style puzzle)
96 
97Concrete pattern an agent would scaffold for a developer building a 2048-style puzzle today. **Phase 1 testnet, T0 submission tier, server-side Path A attribution.**
98 
99```tsx
100// src/Providers.tsx — add SkillOSProvider at the top of the tree
101import { SkillOSProvider } from '@skillos/sdk/react';
102import { WagmiProvider, createConfig, http } from 'wagmi';
103import { baseSepolia } from 'wagmi/chains';
104import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
105import { baseAccount } from 'wagmi/connectors';
106 
107const wagmiConfig = createConfig({
108  chains: [baseSepolia],
109  connectors: [baseAccount({ appName: 'my-puzzle' })],
110  transports: { [baseSepolia.id]: http() },
111});
112const queryClient = new QueryClient();
113 
114export function Providers({ children }: { children: React.ReactNode }) {
115  return (
116    <WagmiProvider config={wagmiConfig}>
117      <QueryClientProvider client={queryClient}>
118        {/* builderCode is per-game and canonical — see prompts/wire-builder-code.md */}
119        <SkillOSProvider config={{ env: 'testnet', builderCode: 'bc_o6szuvg1' }}>
120          {children}
121        </SkillOSProvider>
122      </QueryClientProvider>
123    </WagmiProvider>
124  );
125}
126```
127 
128```tsx
129// src/components/GameOver.tsx — submit on game-over render, not on submit-button click
130import { useSkillOSScore } from '@skillos/sdk/react';
131 
132export function GameOver({ tournamentId, score }: { tournamentId: `0x${string}`; score: number }) {
133  const { submit, status, data, error } = useSkillOSScore({ tournamentId });
134  return (
135    <>
136      <button onClick={() => submit({ score, tier: 'T0' })}>Submit {score}</button>
137      {status === 'pending' && <p>Submitting…</p>}
138      {data?.txHash && (
139        <a href={`https://base-sepolia.blockscout.com/tx/${data.txHash}`} target="_blank">
140          Verify on Blockscout: {data.txHash.slice(0, 14)}…
141        </a>
142      )}
143      {error && <p>Error ({error.code}): {error.message}</p>}
144    </>
145  );
146}
147```
148 
149That's the minimum viable scaffold. After deployment, you **MUST** run [`prompts/verify-attribution-live.md`](./prompts/verify-attribution-live.md) — confirm a live tx's `raw_input` ends with the expected hex tail (`62635f6f36737a75766731` for 2048's `bc_o6szuvg1`). Unit test green is not sufficient evidence.
150 
151## Distribution
152 
153| Channel | Install | Notes |
154|---|---|---|
155| **npm registry** | `npm install @skillos/skills` | All MCP-aware agents |
156| **base/skills convention** | `npx skills add skillos/skillos-skills` | Claude Code, Cursor, Vercel agents |
157| **mdskills.ai catalog** | listing → catalog install path | Skill Advisor regen on each push |
158| **CCGS** | `npx mdskills install youngstar-eth/skillos` | Claude Code Game Studios users |
159 
160## Version compatibility
161 
162| `@skillos/skills` | requires `@skillos/sdk` | notes |
163|---|---|---|
164| `0.2.0` | `^0.2.1` | Adds explicit permissions block, verify-attribution-live workflow, per-game builder code map, X9-X10 lessons codified |
165| `0.1.0` | `^0.2.1` | Initial release |
166 
167## Domain framing (locked)
168 
169Use **skill-gaming terms** publicly. Do NOT reframe SkillOS as:
170 
171- "AI agent benchmark substrate"
172- "Verifiable performance economy"
173- "General-purpose performance market"
174 
175Those are internal architectural framings; not the Phase 1-3 public posture.
176 
177## Out of scope (for this skill pack)
178 
179- Mainnet endpoint references (Phase 2-gated, audit-pending)
180- Token / governance promises (achievement-gated, no public roadmap)
181- AI benchmark substrate framing
182- Direct multi-app deployments to Vercel (use the monorepo's own deploy flow)
183