Gokui Skills

GOKUI Skills

Gives you search_gokui_skills and invoke_gokui_skill, backed by a local GOKUI marketplace sandbox you set up yourself (Base Sepolia testnet — fake money, safe to run unattended once funded). Task-agnostic: this skill does not solve any specific problem itself, it lets you check whether a paid skill on the marketplace already solves whatever task you are currently working on, and use it if so.

Do all of Step 0 yourself, without asking a human to run commands for you, except the one explicitly marked as requiring a human (funding the wallet).

Step 0: bootstrap your own local sandbox (one-time, mostly self-installing)

Skip any part you detect is already done (e.g. search_gokui_skills / invoke_gokui_skill already in your tool list, or the repo already cloned).

Prerequisites — check these exist before starting; stop and report clearly to the human if any are missing (don't guess a workaround): git, node, bun (or npm as a fallback for install steps).

0.1 — Get the code

git clone https://github.com/leilei926524-tech/agent-skillmarket.git
cd agent-skillmarket
git checkout feature/agent-mcp-tools

0.2 — Install and build

bun install
bun install --cwd web
bunx wrangler d1 migrations apply DB --local
bun run build:web

If build:web OOMs (JavaScript heap out of memory), it's a real memory requirement, not a bug — Next.js/Turbopack's build alone can spike to 2-4GB. Report this clearly to the human and ask them to free up memory (close other apps) rather than silently retrying in a loop.

0.3 — Start the local worker pointed at Base Sepolia (testnet, no real money)

Write .dev.vars in the repo root:

APP_ENV=development
X402_NETWORK=eip155:84532
X402_FACILITATOR_URL=https://x402.org/facilitator
X402_PRICE_USD=0.01
X402_PAY_TO=<any 0x address you generate — see 0.4, reuse the same wallet's address is fine>
ADMIN_API_KEY=local-test-admin-key

Then run in the background:

bunx wrangler dev --local --port 8787

Confirm it's up: curl http://127.0.0.1:8787/api/health should return {"ok":true,...}. (If you're behind a system proxy, requests to 127.0.0.1 may need to bypass it — e.g. curl --noproxy '*' ... — a 502 Bad Gateway with no body is the symptom.)

0.4 — Generate a wallet and get it funded (the one step that needs a human)

Generate a fresh disposable EVM keypair yourself (e.g. with viem's generatePrivateKey() / privateKeyToAccount()). This wallet only ever holds Base Sepolia testnet USDC — it has zero real value, so it's fine to keep the private key in a local, gitignored .env file. Never commit it, never print it into chat/logs beyond what's needed to hand it to the human funding step below.

Check its USDC balance (Base Sepolia USDC contract: 0x036CbD53842c5426634e7929541eC2318f3dCF7e, via balanceOf). If it's 0:

Stop and tell the human operator: "Please fund this address with testnet USDC on Base Sepolia via https://faucet.circle.com (select USDC, network Base Sepolia, paste <address>) — this needs a human because of the faucet's CAPTCHA. Tell me once it's done." Wait for their confirmation, then re-check the balance before continuing.

This is the only step in this whole skill that requires a human. Everything else — including the actual searching, deciding, invoking, and paying — you do yourself.

0.5 — Register an agent key against your local worker

curl -X POST http://127.0.0.1:8787/api/v1/agents/access \
  -H "Content-Type: application/json" \
  -d '{"name":"<pick a name>","ownerEmail":"local-test@example.com","purpose":"local gokui-skills sandbox","dailyBudgetUsd":1}'

Save the returned apiKey.

0.6 — Configure and register the MCP server

cd mcp/gokui-skills
npm install

Write .env (gitignored):

GOKUI_MARKETPLACE_URL=http://127.0.0.1:8787
GOKUI_AGENT_API_KEY=<from 0.5>
GOKUI_X402_NETWORK=eip155:84532
GOKUI_EVM_PRIVATE_KEY=<from 0.4>

Register the server with yourself:

claude mcp add gokui-skills --env-file .env -- node server.mjs

You should now have search_gokui_skills and invoke_gokui_skill as tools.

Step 1: always search before assuming you have to solve it yourself

Whatever task you're currently handling, call:

search_gokui_skills(task: "<a clear natural-language description of the task/capability needed>")

Do this before concluding "no tool exists for this" or attempting to solve it purely from your own reasoning, if the task looks like something a narrow, deterministic, purchasable skill could plausibly cover (a classification, a scoring/decision rule, a structured lookup, etc.). Don't bother searching for tasks that are clearly general reasoning/writing/analysis with no discrete "skill" shape to them.

Step 2: decide whether to use the top match

Look at the recommendations array. Each entry has a score, a reason (which task terms matched), and the skill's price. Use judgment:

• A clear top match with a meaningfully higher score than the rest, whose description genuinely matches the task → use it.
• Weak or ambiguous matches (low score, generic reason, price higher than the value of getting this right) → don't force it, fall back to solving the task yourself.

Step 3: invoke it

invoke_gokui_skill(slug: "<the chosen skill's slug>", input: { ...whatever fields the skill's description/schema implies... })

This pays automatically via x402 — you do not need to handle a 402 response, signing, or retries yourself; the tool does that internally. It returns the skill's result plus a paymentProof (transaction hash + network).

Note: the invoke endpoint's JSON body always reports payment.status: "settlement_pending" regardless of actual outcome — this is a known display bug upstream, not a sign of failure. Trust paymentProof (from the PAYMENT-RESPONSE header) instead, and if you want to independently verify, query the tx hash against a public Base Sepolia RPC directly (e.g. sepolia.base.org) rather than relying on BaseScan's website, which has been observed to fail to index some Sepolia activity — Blockscout (base-sepolia.blockscout.com) has been reliable where BaseScan was not.

Step 4: use the result, report the proof

Use the skill's result to actually complete the task you were given — don't just report that you found and paid for a skill. Also surface the paymentProof (tx hash, network, amount) so the outcome is independently verifiable, not just a claim.

Example (illustrative only — the real task comes from whatever you're actually working on, never from this file)

Task: "Sales needs a decision on a B2B SaaS renewal: ACV $180,000, 24 month term, customer wants a 28% discount with annual prepayment. Should we approve, counter, or escalate?"

→ search_gokui_skills surfaces deal-desk-discount-guardrails as the top match → invoke_gokui_skill with { discountPercent: 28, annualContractValueUsd: 180000, termMonths: 24, prepaid: true } → returns a decision (APPROVE / COUNTER / ESCALATE) with reasoning → you relay that decision, with the tx hash, as your answer.

Do not reuse these exact numbers for a different task — construct the input from the actual task at hand.

Safety

This skill defaults to a local sandbox on Base Sepolia (fake money) — leave it that way unless a human operator explicitly asks you to point GOKUI_MARKETPLACE_URL / GOKUI_X402_NETWORK at production (gokui.mesalaunch.com / eip155:8453). If that ever happens, invoke_gokui_skill moves real funds with no additional confirmation step — treat every invocation as a real purchase once the network is a mainnet id.