Final Report - Arbitrum Skills

DAO Programs & Initiatives Domain Allocator Offerings (prev Questbook)
1

Arbitrum Skills: Completion Report :clipboard:

Project 1: Arbitrum MCP Tools (Previous Completed Project: Completion Report)

Repository

arbitrum-mcp-tools

npm Command

npx arbitrum-mcp-tools

Version

v1.x → v2.0.4

What It Does

Arbitrum MCP Tools is an MCP (Model Context Protocol) toolkit that enables AI assistants — Claude, Cursor, VS Code, Gemini, and others — to perform blockchain operations on Arbitrum using natural language.

Changes Made

1. Installation System Completely Rewritten (v2.0.0)

Previous State (v1.x)

  • Separate setup scripts for each platform
  • setup-claude-server.js, setup-cursor-server.js, setup-windsurf-server.js, setup-gemini-server.js
  • Each script nearly identical
  • Adding a new platform meant writing a new script from scratch
  • Only 4 platforms supported

New State (v2.0.0+)

  • All 4 legacy setup scripts deleted (~1,029 lines removed)
  • Replaced with a single interactive CLI wizard (~2,020 lines of new code)
  • One-command installation: npx arbitrum-mcp-tools install
  • Automatic platform detection (finds which AI tools are installed on the system)

2. Supported Platforms Increased from 4 to 8

# Platform Format Status
1 Claude Desktop JSON Existed in v1, updated in v2
2 Cursor JSON Existed in v1, updated in v2
3 Windsurf JSON Existed in v1, updated in v2
4 Gemini CLI JSON Existed in v1, updated in v2
5 Claude Code JSON Added in v2.0.0 (NEW)
6 VS Code JSON Added in v2.0.0 (NEW)
7 OpenAI Codex TOML Added in v2.0.0 (NEW)
8 Antigravity JSON Added in v2.0.4 (NEW)

3. New CLI Commands

npx arbitrum-mcp-tools install     # Interactive installation wizard
npx arbitrum-mcp-tools uninstall   # Interactive uninstall wizard
npx arbitrum-mcp-tools list        # Display platform status
npx arbitrum-mcp-tools serve       # Start the MCP server
npx arbitrum-mcp-tools --help      # Help
npx arbitrum-mcp-tools --version   # Version

4. Config Structure Changed — npx-Based Execution

Before (v1.x) — used absolute paths:

{
  "command": "node",
  "args": ["/Users/username/path/to/index.js"]
}
  • Absolute paths were machine-specific and not portable
  • Required the user to clone the repo and build locally

After (v2.0+) — runs directly from npm via npx:

{
  "command": "npx",
  "args": ["-y", "arbitrum-mcp-tools", "serve"]
}
  • No local installation required
  • Cross-platform compatible (macOS, Windows, Linux)
  • Automatically fetches the latest version on every restart

5. Environment Variable Management Made Secure

Before (v1.x): API keys were embedded directly in config files (${ALCHEMY_API_KEY} syntax) — creating a security risk.

After (v2.0+):

  • Environment variables are no longer written to config files — read from process.env at runtime
  • Users set them in their shell profile (~/.zshrc or ~/.bashrc)
  • Special env_vars forwarding support for Codex (which sandboxes its shell environment)

6. Server Code Refactored (v2.0.1)

src/index.ts was split into two files:

  • src/index.ts — Entry point (only starts the server)
  • src/server.ts — MCP server setup and Alchemy configuration

This allows the CLI and server to operate independently.

7. TOML Config Support Added (for Codex)

OpenAI Codex uses TOML instead of JSON for configuration. As a result:

  • Added @iarna/toml library for TOML read/write support
  • Added env_vars support for Codex’s sandbox environment
[mcp_servers.arbitrum]
command = "npx"
args = ["-y", "arbitrum-mcp-tools", "serve"]
enabled = true
env_vars = ["ALCHEMY_API_KEY", "ARBISCAN_API_KEY", "STYLUS_PRIVATE_KEY"]

8. New Modular CLI Architecture Built from Scratch

A fully modular CLI architecture was designed:

src/cli/
├── index.ts                   # CLI entry point and command routing
├── commands/
│   ├── install.ts             # Interactive installation wizard
│   ├── uninstall.ts           # Interactive uninstall wizard
│   ├── list.ts                # Platform status list
│   └── serve.ts               # MCP server startup
├── clients/
│   ├── base.ts                # Platform config operations (read/write/delete)
│   ├── registry.ts            # 8 platform definitions and config paths
│   └── generators/
│       ├── json.ts            # JSON config read/write
│       └── toml.ts            # TOML config read/write
└── utils/
    ├── platform.ts            # OS detection (macOS/Windows/Linux)
    ├── paths.ts               # Cross-platform path resolution
    └── ui.ts                  # Terminal UI (colored output with boxen and chalk)

9. Automatic Platform Detection

The CLI automatically detects which AI tools are installed on the system:

Platform Detection Method
Claude Desktop /Applications/Claude.app or config file exists
Claude Code ~/.claude.json or ~/.claude/settings.json exists
Cursor /Applications/Cursor.app or ~/.cursor/ exists
Windsurf ~/.codeium/windsurf/ exists
VS Code /Applications/Visual Studio Code.app or ~/.vscode/ exists
Gemini CLI ~/.gemini/ exists
Antigravity ~/.gemini/antigravity/ exists
OpenAI Codex ~/.codex/ exists

10. Global and Local Installation Scopes

  • Global installation: ~/.claude.json, ~/.cursor/mcp.json, etc. — available across all projects
  • Local installation: .claude/mcp.json, .cursor/mcp.json, etc. — scoped to the current project only

11. Full MCP Tool Suite (31 Tools, 7 Categories)

All tools can be invoked using natural language. Example: “What’s the ETH balance of 0x123…?”

  • :magnifying_glass_tilted_left: Account Analysis — 6 Tools
    • getAccountBalance — Query native ETH balance
    • getTokenBalances — ERC-20 token balances
    • getNfts — NFT listing (filtering, pagination, ordering)
    • getTransactionHistory — Transaction history
    • getNftMetadata — NFT metadata information
    • getAccountProtocols — Most-interacted protocols
  • :chains: Chain Data — 6 Tools
    • getBlockNumber — Latest block number
    • getBlock — Block details
    • getTransaction — Transaction details
    • getTransactionReceipt — Transaction receipt
    • getGasParameters — Detailed gas metrics
    • getGasPrice — Current gas price
  • :scroll: Contract Interaction — 4 Tools
    • getContractCode — Contract bytecode
    • decodeTransactionCalldata — Decode transaction input data
    • getContractEvents — Query contract events
    • getTokenAllowance — ERC-20 token allowance
  • :bridge_at_night: Cross-Chain — 1 Tool
    • getTransactionLogs — Decode L1/L2 transaction logs
  • :hammer_and_wrench: Development — 2 Tools
    • simulateTransaction — Transaction simulation
    • estimateGas — Gas estimation
  • :package: Batch Operations — 2 Tools
    • getBatchBalances — Multi-address balance query
    • multiAddressAnalysis — Multi-address comparison
  • :gear: Stylus Development — 12 Tools
    • createStylusProject — Create a new Stylus project
    • initStylusProject — Initialize Stylus in current directory
    • exportStylusAbi — Export ABI
    • checkStylusContract — Pre-deployment validation
    • deployStylusContract — Deploy a contract
    • deployMultipleStylusContracts — Deploy multiple contracts
    • verifyStylusContract — Verify deployment
    • activateStylusContract — Activate a contract
    • cacheStylusContract — Cache via CacheManager
    • generateStylusBindings — Generate C code bindings
    • replayStylusTransaction — Replay in GDB debugger
    • traceStylusTransaction — Trace a transaction

12. New Dependencies Added

Package Purpose
@inquirer/prompts Interactive terminal prompts (platform selection, etc.)
@iarna/toml TOML format read/write (Codex support)
chalk Terminal color output
boxen Terminal boxes (info and success messages)

Project 2: Arbitrum Skills - Arbitrum Skill Generator (Current Project)

Repository

arbitrum-skills-generator

arbitrum-skills

Purpose

Automatically generate skill packages for LLM Code

Actual Skill collection generated by skill generator

What It Does

Processes official Arbitrum documentation, smart contract source code, and MCP tools documentation to produce a structured “skill package” that enables Claude Code to provide context-aware answers about the Arbitrum ecosystem.

Changes Made - Deliverables

1. Skill Generator Built from Scratch

A TypeScript CLI tool that automatically processes 3 independent data sources:

:books: Arbitrum Documentation

Official docs cloned from GitHub (Markdown/MDX)

:memo: Smart Contract Repos

Source code from 3 repositories:

  • OpenZeppelin Rust Contracts (ERC20, ERC721, ERC1155, access control)
  • Stylus SDK for Rust (core SDK, storage, ABI encoding)
  • Nitro Contracts / Solidity (bridge, rollup, BoLD protocol)

:wrench: MCP Tools Documentation

Tool docs fetched from GitBook

2. Advanced Documentation Processing

  • YAML frontmatter parsing
  • MDX/JSX syntax cleanup (removes imports, exports, JSX tags)
  • AsciiDoc to Markdown conversion
  • Smart title extraction (frontmatter → H1 heading → filename fallback)
  • Minimum content threshold filtering (50 chars for docs, 10 chars for code)

3. Intelligent Filtering System

Test, mock, and boilerplate files are automatically filtered out:

  • Test/mock directories are skipped
  • Cargo.toml stub files are filtered
  • mod.rs files containing only re-exports are skipped
  • Build directories (target, node_modules, cache, artifacts) are ignored

4. Generated Output Structure

output/arbitrum-skills/
├── SKILL.md                    # Main skill file (decision table, search guide)
├── NAV-docs.md                 # Complete hierarchical documentation index
├── NAV-smart-contracts.md      # Contract repos overview
├── NAV-{repo}.md               # Per-repo navigation file
├── stylus/                     # Category folders
├── sdk/
├── run-arbitrum-node/
├── build-decentralized-apps/
├── ...
└── smart-contracts/            # Organized source code files

5. CLI Options

npm run generate                         # Full pipeline
npm run generate -- ./local-docs         # Local docs path
npm run generate -- --ignore-contracts   # Skip contracts
npm run generate -- --ignore-mcp         # Skip MCP docs
npm run generate -- -o ./out -n my-skill # Custom output directory and name

6. Output Formatting and CLI Visuals Improved

  • Colored terminal output added with chalk
  • Progress bar and duration tracking
  • Category descriptions improved
  • README updated

7. Skill Installation

The generated skill package can be installed into Claude Code in multiple ways:

Option 1 — Via skills.sh (Recommended)

Usage Metrics: Arbitrum Skills has been downloaded at a weekly average of 15–35 since the day it was first published (Feb 22, 2026), according to skills.sh (https://skills.sh/utkucy/arbitrum-skills/arbitrum-skills) data.

The skill is published at skills.sh/utkucy/arbitrum-skills/arbitrum-skills and can be installed with a single command:

npx skills add utkucy/arbitrum-skills

Option 2 — Manual copy from local output

# Global (all projects)
cp -r output/arbitrum-skills ~/.claude/skills/

# Project-specific
cp -r output/arbitrum-skills .claude/skills/

Claude Code automatically detects SKILL.md and activates the skill.

Project 3: Arbitrum AI Hub Documentation

GitBook

arbitrum-ai-hub.gitbook.io/docs

Purpose

Central documentation hub for both Arbitrum AI Hub projects. This may be out of the current grant scope, but I wanted to share that both of my projects are served under Overview | Arbitrum AI Hub Documents

What It Does

Arbitrum AI Hub is the central documentation hub that covers both the Arbitrum MCP Tools and Arbitrum Skills projects in a single place, making it easier for developers to discover and use both tools together.

Changes Made

1. Documentation Rebranded and Expanded

Previous State

  • GitBook documentation existed only for the Arbitrum MCP Tools project
  • Covered only MCP tool usage, configuration, and tool reference

New State

  • Documentation expanded and rebranded as Arbitrum AI Hub
  • Now serves as the central documentation hub for both projects:
    • Arbitrum MCP Tools — setup, platform configuration, full tool reference
    • Arbitrum Skills — skill generator usage, skill package installation, Claude Code integration
  • New name and URL: arbitrum-ai-hub.gitbook.io/docs

How Both Projects Work Together

┌─────────────────────────────┐
│  Arbitrum MCP Tools (npm)   │──── AI assistants can perform
│  31 tools, 8 platforms      │     blockchain operations
└──────────────┬──────────────┘
               │
               │ MCP tools docs are fed
               │ into the skill generator
               ▼
┌─────────────────────────────┐
│  Arbitrum Skill Generator   │──── Claude Code - LLMs becomes an
│  Docs + Contracts + MCP     │     Arbitrum expert
└──────────────┬──────────────┘
               │
               ▼
┌─────────────────────────────┐
│  Claude Code Skill Package  │──── SKILL.md + NAV files
│  output/arbitrum-skills/    │     + categorized docs
└─────────────────────────────┘