somnia-agents-skills

Somnia Agents Skills

Skills that teach AI coding tools how to invoke Somnia Agents — Somnia's on-chain platform for decentralized, auditable compute jobs (oracles, deterministic LLMs, structured web extraction).

Built on the Agent Skills open standard — works with Claude Code, Cursor, VS Code/Copilot, Windsurf, Gemini CLI, Amp, Goose, Roo Code, and any other tool that supports the standard.

Use the skills interactively to invoke any base agent and read receipts — or ask your AI to write a Solidity contract that requests price feeds, runs deterministic LLM classification, or extracts structured data from a webpage on-chain.

What's in here

Knowledge skills (domain context the AI uses when writing code):

• somnia-agents — comprehensive reference: request lifecycle, two-pot gas model, Majority vs Threshold consensus, callback handling, receipts
• somnia-agents-json-fetch — the JSON API Request agent: 6 fetch functions, selector syntax, decimal scaling
• somnia-agents-llm-inference — the LLM Inference agent: 4 functions, MCP + on-chain tool calling, yield/resume pattern
• somnia-agents-llm-parse-website — the LLM Parse Website agent: search vs direct mode, structured extraction

Action skill (interactive command):

• somnia-agents-invoke — invoke any base agent from the CLI, wait for finalisation, read off-chain receipts — without writing a contract

Setup

npm install
cp .env.example .env

Edit .env and set PRIVATE_KEY to a funded Somnia wallet. Get testnet STT from the Somnia Faucet.

Loading skills into your tool

Claude Code

Add the local marketplace, then install the plugin (persists across sessions and projects):

claude plugin marketplace add /path/to/somnia-agents-skills
claude plugin install somnia-agents-skills@somnia-agents-skills --scope user

In VS Code, you can also install via the /plugins UI in the Claude panel.

Alternatively, symlink individual skills into ~/.claude/skills/:

ln -sf /path/to/somnia-agents-skills/skills/*/ ~/.claude/skills/

For local development, use the session-only flag instead:

claude --plugin-dir /path/to/somnia-agents-skills

Cursor

Add as a skill source via Settings → Features → Agent, or through the marketplace.

Other tools

Any tool supporting the Agent Skills standard can load these skills. Each skill is a SKILL.md file in a subdirectory under skills/.

Quickstart

Once PRIVATE_KEY is set, fire a one-off agent call from the terminal:

# Fetch BTC/USD price as uint256 (8 decimals)
npx tsx skills/somnia-agents-invoke/scripts/invoke.ts \
  --agent json-fetch --function fetchUint \
  --args '["https://api.coingecko.com/api/v3/simple/price?ids=bitcoin&vs_currencies=usd","bitcoin.usd",8]'

# Single-turn LLM classification with allowed values
npx tsx skills/somnia-agents-invoke/scripts/invoke.ts \
  --agent llm-inference --function inferString \
  --args '["Classify: I love this product!", "You are a sentiment classifier. Reply with one word.", false, ["positive","negative","neutral"]]'

# Web extraction in direct mode
npx tsx skills/somnia-agents-invoke/scripts/invoke.ts \
  --agent llm-parse-website --function ExtractString \
  --args '["best_drama","Title of the film that won Best Motion Picture - Drama.",[],"Best Picture winners at the 2026 Golden Globe Awards","goldenglobes.com",true,3]'

The script handles deposit sizing automatically — see skills/somnia-agents-invoke/SKILL.md for the full flag list and patterns.

Asking your AI to build something

Once the skills are loaded, describe what you want and the AI writes the code — it has full knowledge of the agent ABIs, the platform contract, deposit math, and the callback pattern. Examples:

• "Write a Solidity contract that fetches the BTC/USD price every hour and stores it on-chain via the JSON API Request agent."
• "Build a content moderation contract that uses LLM Inference to classify user posts as safe or unsafe and reverts on unsafe."
• "Create a prediction-market resolver that uses LLM Parse Website to determine the winner of a sports match from ESPN."
• "Write an agentic DeFi bot using inferToolsChat — the LLM decides which DEX swap to execute and yields the calldata back to my contract."

Network reference

Both networks share the same agent IDs. Only the platform contract address differs.