feat: add near jsonrpc skill

jolestar · jolestar · commit fc1d506a59db · 2026-03-18T18:04:11.000+08:00
diff --git a/docs/skills.md b/docs/skills.md
@@ -45,6 +45,8 @@ This repository ships one canonical skill for UXC (Universal X-Protocol CLI) and
   - Wrapper for Helius Wallet API wallet intelligence reads via UXC + curated OpenAPI schema and API-key auth.
 - `skills/blocknative-openapi-skill`
   - Wrapper for Blocknative gas price and fee intelligence reads via UXC + curated OpenAPI schema and API-key auth.
+- `skills/near-jsonrpc-skill`
+  - Wrapper for NEAR JSON-RPC reads via UXC + provider-aware public RPC default and deprecated-endpoint guardrails.
 - `skills/alchemy-openapi-skill`
   - Wrapper for Alchemy Prices API read workflows via UXC + curated OpenAPI schema and path-templated API-key auth.
 - `skills/chainbase-openapi-skill`
@@ -89,7 +91,7 @@ python ~/.codex/skills/.system/skill-installer/scripts/install-skill-from-github
   --path skills/deepwiki-mcp-skill
 ```
 
-Replace `skills/deepwiki-mcp-skill` with `skills/context7-mcp-skill`, `skills/okx-mcp-skill`, `skills/dune-mcp-skill`, `skills/thegraph-mcp-skill`, `skills/thegraph-token-mcp-skill`, `skills/etherscan-mcp-skill`, `skills/notion-mcp-skill`, `skills/discord-openapi-skill`, `skills/slack-openapi-skill`, `skills/matrix-openapi-skill`, `skills/line-openapi-skill`, `skills/feishu-openapi-skill`, `skills/whatsapp-openapi-skill`, `skills/dingtalk-openapi-skill`, `skills/coingecko-openapi-skill`, `skills/defillama-openapi-skill`, `skills/blockscout-openapi-skill`, `skills/chainbase-openapi-skill`, `skills/moralis-openapi-skill`, `skills/alchemy-openapi-skill`, `skills/coinapi-openapi-skill`, `skills/dexscreener-openapi-skill`, `skills/helius-openapi-skill`, `skills/blocknative-openapi-skill`, `skills/binance-web3-openapi-skill`, or `skills/binance-spot-openapi-skill` as needed.
+Replace `skills/deepwiki-mcp-skill` with `skills/context7-mcp-skill`, `skills/okx-mcp-skill`, `skills/dune-mcp-skill`, `skills/thegraph-mcp-skill`, `skills/thegraph-token-mcp-skill`, `skills/etherscan-mcp-skill`, `skills/notion-mcp-skill`, `skills/discord-openapi-skill`, `skills/slack-openapi-skill`, `skills/matrix-openapi-skill`, `skills/line-openapi-skill`, `skills/feishu-openapi-skill`, `skills/whatsapp-openapi-skill`, `skills/dingtalk-openapi-skill`, `skills/coingecko-openapi-skill`, `skills/defillama-openapi-skill`, `skills/blockscout-openapi-skill`, `skills/chainbase-openapi-skill`, `skills/moralis-openapi-skill`, `skills/alchemy-openapi-skill`, `skills/coinapi-openapi-skill`, `skills/dexscreener-openapi-skill`, `skills/helius-openapi-skill`, `skills/blocknative-openapi-skill`, `skills/near-jsonrpc-skill`, `skills/binance-web3-openapi-skill`, or `skills/binance-spot-openapi-skill` as needed.
 
 After installation, restart Codex to load new skills.
 
@@ -208,6 +210,12 @@ bash skills/helius-openapi-skill/scripts/validate.sh
 bash skills/blocknative-openapi-skill/scripts/validate.sh
 ```
 
+- Validate NEAR wrapper docs when touched:
+
+```bash
+bash skills/near-jsonrpc-skill/scripts/validate.sh
+```
+
 - Validate Alchemy wrapper docs when touched:
 
 ```bash
diff --git a/skills/near-jsonrpc-skill/SKILL.md b/skills/near-jsonrpc-skill/SKILL.md
@@ -0,0 +1,98 @@
+---
+name: near-jsonrpc-skill
+description: Operate NEAR JSON-RPC reads through UXC with a public provider default, provider-override guidance, and read-only guardrails.
+---
+
+# NEAR JSON-RPC Skill
+
+Use this skill to run NEAR JSON-RPC operations through `uxc` + JSON-RPC.
+
+Reuse the `uxc` skill for shared execution and error-handling guidance.
+
+## Prerequisites
+
+- `uxc` is installed and available in `PATH`.
+- Network access to a working NEAR RPC provider.
+- This skill defaults to `https://free.rpc.fastnear.com`, which is listed on the official NEAR RPC providers page.
+
+## Scope
+
+This skill covers a safe read-first NEAR RPC surface:
+
+- chain status
+- account state query
+- finalized block lookup
+- chunk lookup by chunk hash
+- gas price lookup
+- validator set lookup
+
+This skill does **not** cover:
+
+- transaction submission methods
+- signing or wallet flows
+- archival assumptions for very old blocks or chunks
+- deprecated `near.org` or `pagoda.co` public RPC endpoints
+
+## Endpoint And Provider Choice
+
+This skill uses the public FastNear mainnet RPC by default:
+
+- `https://free.rpc.fastnear.com`
+
+The official NEAR docs now treat `near.org` and `pagoda.co` RPC endpoints as deprecated. Do not use those old hosts as the default for new automation.
+
+If the user already has a preferred provider from the official NEAR providers page, relink the same command to that provider instead of reusing the deprecated endpoints.
+
+## Authentication
+
+The default FastNear public RPC used by this skill does not require authentication.
+
+If the user switches to a private NEAR provider, verify its auth model before reusing this skill unchanged.
+
+## Core Workflow
+
+1. Use the fixed link command by default:
+   - `command -v near-jsonrpc-cli`
+   - If missing, create it:
+     `uxc link near-jsonrpc-cli https://free.rpc.fastnear.com`
+   - `near-jsonrpc-cli -h`
+
+2. Inspect host help first, then run known read methods:
+   - `near-jsonrpc-cli -h`
+   - `near-jsonrpc-cli status`
+   - `near-jsonrpc-cli gas_price '[null]'`
+
+3. Prefer narrow validation before deeper queries:
+   - `near-jsonrpc-cli status`
+   - `near-jsonrpc-cli block '{"finality":"final"}'`
+   - `near-jsonrpc-cli query '{"request_type":"view_account","finality":"final","account_id":"near"}'`
+
+4. Execute with positional JSON for structured params:
+   - `near-jsonrpc-cli gas_price '[null]'`
+   - `near-jsonrpc-cli validators '[null]'`
+   - `near-jsonrpc-cli chunk '{"chunk_id":"75cewvnKFLrJshoUft1tiUC9GriuxWTc4bWezjy2MoPR"}'`
+
+## Recommended Read Operations
+
+- `status`
+- `query`
+- `block`
+- `chunk`
+- `gas_price`
+- `validators`
+
+## Guardrails
+
+- Keep automation on the JSON output envelope; do not use `--text`.
+- Parse stable fields first: `ok`, `kind`, `protocol`, `data`, `error`.
+- Stay on the read-only method surface by default.
+- Do not use this skill for transaction submission, signing, or wallet-authenticated flows.
+- The official NEAR docs mark the old `near.org` and `pagoda.co` public RPC endpoints as deprecated. Prefer providers from the official RPC providers page instead.
+- Public providers can differ in archival retention and rate limits. If `chunk` or older `block` lookups fail with unknown or garbage-collected errors, switch to a provider that explicitly supports the needed history.
+- `near-jsonrpc-cli <operation> ...` is equivalent to `uxc https://free.rpc.fastnear.com <operation> ...`.
+
+## References
+
+- Usage patterns: `references/usage-patterns.md`
+- NEAR RPC introduction: https://docs.near.org/api/rpc/introduction
+- NEAR RPC providers: https://docs.near.org/api/rpc/providers
diff --git a/skills/near-jsonrpc-skill/agents/openai.yaml b/skills/near-jsonrpc-skill/agents/openai.yaml
@@ -0,0 +1,4 @@
+interface:
+  display_name: "NEAR JSON-RPC"
+  short_description: "Operate NEAR mainnet JSON-RPC reads via UXC with a provider-aware public RPC default"
+  default_prompt: "Use $near-jsonrpc-skill to discover and execute NEAR JSON-RPC read-only operations through UXC with a provider-aware public RPC default and deprecated-endpoint guardrails."
diff --git a/skills/near-jsonrpc-skill/references/usage-patterns.md b/skills/near-jsonrpc-skill/references/usage-patterns.md
@@ -0,0 +1,45 @@
+# NEAR JSON-RPC Skill - Usage Patterns
+
+## Link Setup
+
+```bash
+command -v near-jsonrpc-cli
+uxc link near-jsonrpc-cli https://free.rpc.fastnear.com
+near-jsonrpc-cli -h
+```
+
+## Read Examples
+
+```bash
+# Read node and chain status
+near-jsonrpc-cli status
+
+# Read the latest finalized block
+near-jsonrpc-cli block '{"finality":"final"}'
+
+# Read an account state
+near-jsonrpc-cli query '{"request_type":"view_account","finality":"final","account_id":"near"}'
+
+# Read gas price for the latest block context
+near-jsonrpc-cli gas_price '[null]'
+
+# Read validator sets
+near-jsonrpc-cli validators '[null]'
+
+# Read a chunk by chunk hash
+near-jsonrpc-cli chunk '{"chunk_id":"75cewvnKFLrJshoUft1tiUC9GriuxWTc4bWezjy2MoPR"}'
+```
+
+## Provider Override
+
+```bash
+# Relink the same command to another provider from the official NEAR RPC providers page
+uxc link near-jsonrpc-cli https://<near-rpc-provider-host>
+```
+
+Do not relink to deprecated `near.org` or `pagoda.co` public RPC hosts.
+
+## Fallback Equivalence
+
+- `near-jsonrpc-cli <operation> ...` is equivalent to
+  `uxc https://free.rpc.fastnear.com <operation> ...`.
diff --git a/skills/near-jsonrpc-skill/scripts/validate.sh b/skills/near-jsonrpc-skill/scripts/validate.sh
@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../.." && pwd)"
+SKILL_DIR="${ROOT_DIR}/skills/near-jsonrpc-skill"
+SKILL_FILE="${SKILL_DIR}/SKILL.md"
+OPENAI_FILE="${SKILL_DIR}/agents/openai.yaml"
+USAGE_FILE="${SKILL_DIR}/references/usage-patterns.md"
+
+fail() {
+  printf '[validate] error: %s\n' "$*" >&2
+  exit 1
+}
+
+need_cmd() {
+  command -v "$1" >/dev/null 2>&1 || fail "required command not found: $1"
+}
+
+need_cmd rg
+
+for file in "${SKILL_FILE}" "${OPENAI_FILE}" "${USAGE_FILE}"; do
+  [[ -f "${file}" ]] || fail "missing required file: ${file}"
+done
+
+rg -q '^name:\s*near-jsonrpc-skill\s*$' "${SKILL_FILE}" || fail 'invalid skill name'
+rg -q '^description:\s*.+' "${SKILL_FILE}" || fail 'missing description'
+rg -q 'command -v near-jsonrpc-cli' "${SKILL_FILE}" || fail 'missing link-first command check'
+rg -q 'uxc link near-jsonrpc-cli https://free.rpc.fastnear.com' "${SKILL_FILE}" "${USAGE_FILE}" || fail 'missing fixed link create command'
+rg -q 'near.org' "${SKILL_FILE}" || fail 'missing deprecated endpoint warning'
+rg -q 'status' "${SKILL_FILE}" || fail 'missing status method guidance'
+rg -q 'gas_price' "${SKILL_FILE}" || fail 'missing gas_price method guidance'
+rg -q 'validators' "${SKILL_FILE}" || fail 'missing validators method guidance'
+rg -q 'read-only' "${SKILL_FILE}" || fail 'missing read-only guardrail'
+
+if rg -q -- "--args\\s+'\\{" "${SKILL_FILE}" "${USAGE_FILE}"; then
+  fail 'found banned legacy JSON argument pattern'
+fi
+
+rg -q '^\s*display_name:\s*"NEAR JSON-RPC"\s*$' "${OPENAI_FILE}" || fail 'missing display_name'
+rg -q '^\s*short_description:\s*".+"\s*$' "${OPENAI_FILE}" || fail 'missing short_description'
+rg -q '^\s*default_prompt:\s*".*\$near-jsonrpc-skill.*"\s*$' "${OPENAI_FILE}" || fail 'default_prompt must mention $near-jsonrpc-skill'
+
+echo "skills/near-jsonrpc-skill validation passed"
