AI Skill

Building on Forest with an AI agent? Install the official Forest skills — our developer docs packaged as Agent Skills your assistant loads on demand. html-playkit teaches the agent the Playkit two-surface trust model, display-vs-base-unit amounts, the verified-identity handshake, and the full RPC surface — so it writes correct code instead of guessing. portfolio teaches it to read positions, PnL, and live prices across Forest tokens through the REST API and plan rebalances or take-profit moves (read-and-plan only — no trade execution). More Forest skills land in the same package over time.

Source: github.com/Forest-Protocol/forest-skills.

Install

npx skills add Forest-Protocol/forest-skills

What it covers

Once installed, ask your agent to build against Forest and it will pull in the right knowledge:

• The iframe (client) vs trusted-backend trust boundary
• Swaps and user-approved swap sessions
• Game Balance, burns, and game-action settlement
• The verified Player Identity handshake
• The RPC request/response envelope and error codes
• Standing up a live database for stats, metrics, and game state on your backend
• Reading positions, cost basis, PnL, and live prices across Forest tokens via the REST API
• Planning rebalances and take-profit moves from that data (execution stays in the Forest UI)

Persistent game data

Beyond the economic ledger, most games need somewhere to keep score. The skill teaches the agent how to stand up and maintain a live database for three kinds of data:

• Stats — per-player counters that only go up: games played, wins, kills, items collected.
• Metrics — aggregate or time-series data you query later: session length, daily active players, average score per match.
• Live game state — a mutable "save file" per player that the game reads and overwrites as they play: current level, inventory, board position, in-progress run.

The agent sets this up on your trusted backend — the same server that holds the Settlement Signing Secret (see Game Actions) — never in the iframe.

Schema shape

The skill defaults to three tables (or collections), keyed by the verified player identity from the Player Identity handshake — never the display-only wallet address:

-- append-only, one row per event
CREATE TABLE stats (
  player_id  TEXT NOT NULL,
  stat_key   TEXT NOT NULL,
  value      BIGINT NOT NULL,
  created_at TIMESTAMPTZ DEFAULT now()
);

-- one row per player, overwritten in place
CREATE TABLE game_state (
  player_id  TEXT PRIMARY KEY,
  state      JSONB NOT NULL,
  updated_at TIMESTAMPTZ DEFAULT now()
);

-- aggregates, refreshed on a schedule or on write
CREATE TABLE metrics (
  metric_key TEXT NOT NULL,
  period     DATE NOT NULL,
  value      BIGINT NOT NULL,
  PRIMARY KEY (metric_key, period)
);

stats stays append-only so history isn't lost. game_state is the one table the agent updates in place — it's the "living" file the game reads on load and writes on every meaningful change. metrics is for rollups your dashboard or leaderboard reads, kept separate so heavy aggregate queries don't lock the live tables.

Where writes happen

Stat and state writes follow the same shape as a settlement, but they are not settlements — writing to game_state does not move Game Balance:

HTML game
  -> forest.game.action.authorize({ actionId, debitLimitAmount })
  -> your backend validates the gameplay result
  -> your backend signs and submits the settlement to Forest
  -> your backend writes to stats / game_state / metrics
  -> HTML game reads state back from your backend's API

Ask the agent to wire database writes into the same backend handler that signs the settlement, so a confirmed match always updates both the ledger and your stats in one place.

Provider shortlist

If you don't already run a database, the agent can scaffold against any of these:

Tell the agent which one you're using (or let it default to Railway) and it will generate the connection setup, migrations, and the backend handler above.