Package the skills as a Claude Code and Codex plugin

.agents/plugins/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "name": "etherscan",
+  "interface": {
+    "displayName": "Etherscan"
+  },
+  "plugins": [
+    {
+      "name": "etherscan",
+      "source": {
+        "source": "local",
+        "path": "./"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_USE"
+      },
+      "category": "Developer Tools"
+    }
+  ]
+}

.claude-plugin/marketplace.json

@@ -0,0 +1,14 @@
+{
+  "name": "etherscan",
+  "description": "Official Etherscan plugins",
+  "owner": {
+    "name": "Etherscan"
+  },
+  "plugins": [
+    {
+      "name": "etherscan",
+      "source": "./",
+      "description": "Debug EVM transactions, review verified contracts, and trace on-chain money flow with Etherscan."
+    }
+  ]
+}

.claude-plugin/plugin.json

@@ -0,0 +1,18 @@
+{
+  "name": "etherscan",
+  "displayName": "Etherscan",
+  "description": "Debug EVM transactions, review verified contracts, trace on-chain money flow, and pick the right Etherscan page, API endpoint, CLI command, or MCP tool. Uses the Etherscan CLI first.",
+  "author": {
+    "name": "Etherscan",
+    "url": "https://etherscan.io"
+  },
+  "homepage": "https://github.com/etherscan/skills",
+  "repository": "https://github.com/etherscan/skills",
+  "license": "MIT",
+  "keywords": ["etherscan", "ethereum", "evm", "blockchain", "transactions", "smart-contracts"],
+  "icon": "./assets/icon.png",
+  "documentationUrl": "https://docs.etherscan.io",
+  "supportUrl": "https://etherscan.io/contactus",
+  "privacyPolicyUrl": "https://etherscan.io/privacypolicy",
+  "termsOfServiceUrl": "https://etherscan.io/terms"
+}

.codex-plugin/plugin.json

@@ -0,0 +1,42 @@
+{
+  "name": "etherscan",
+  "version": "0.1.0",
+  "description": "Debug EVM transactions, review verified contracts, trace on-chain money flow, and pick the right Etherscan page, API endpoint, CLI command, or MCP tool.",
+  "author": {
+    "name": "Etherscan",
+    "url": "https://etherscan.io"
+  },
+  "homepage": "https://github.com/etherscan/skills",
+  "repository": "https://github.com/etherscan/skills",
+  "license": "MIT",
+  "keywords": [
+    "etherscan",
+    "ethereum",
+    "evm",
+    "blockchain",
+    "transactions",
+    "smart-contracts"
+  ],
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "Etherscan",
+    "shortDescription": "Debug transactions and review contracts with Etherscan.",
+    "longDescription": "Etherscan skills that explain EVM transactions, review verified contracts, trace on-chain money flow, and route a task to the right Etherscan website page, API endpoint, CLI command, or MCP tool. They use the Etherscan CLI first.",
+    "developerName": "Etherscan",
+    "category": "Developer Tools",
+    "capabilities": [
+      "Read"
+    ],
+    "websiteURL": "https://etherscan.io",
+    "privacyPolicyURL": "https://etherscan.io/privacypolicy",
+    "termsOfServiceURL": "https://etherscan.io/terms",
+    "defaultPrompt": [
+      "Explain what happened in this transaction with Etherscan.",
+      "Review this verified contract on Etherscan.",
+      "Trace where the funds from this address went."
+    ],
+    "brandColor": "#0784C3",
+    "composerIcon": "./assets/icon.png",
+    "logo": "./assets/icon.png"
+  }
+}

CONTRIBUTING.md

@@ -17,6 +17,16 @@ skills/
     examples/       # optional — example outputs
 ```
 
+## Plugin packaging
+
+The repo root is also a Claude Code and Codex plugin that installs every skill under `skills/`, so a new skill ships in the plugin with no extra step. The plugin files are:
+
+- `.claude-plugin/plugin.json` and `.claude-plugin/marketplace.json` (Claude Code)
+- `.codex-plugin/plugin.json` and `.agents/plugins/marketplace.json` (Codex)
+- `assets/icon.png`
+
+The Claude manifest has no `version`, so every merge to `main` becomes the new plugin version for Claude Code users the next time their marketplace updates. The Codex manifest has one; bump it to release a change to Codex users. Check the plugin with `claude plugin validate .`.
+
 ## Adding a skill
 
 1. Create `skills/<skill-name>/SKILL.md`.

README.md

@@ -30,6 +30,24 @@
 
 ## Installation
 
+### As a Claude Code or Codex plugin
+
+The plugin installs all four skills and updates them with this repo. It contains no MCP server: the skills use the [Etherscan CLI](https://docs.etherscan.io/ai/cli.md) first, and use an Etherscan MCP connection only if you have already added one.
+
+In Claude Code:
+
+```text
+/plugin marketplace add etherscan/skills
+/plugin install etherscan@etherscan
+```
+
+In Codex:
+
+```bash
+codex plugin marketplace add etherscan/skills
+codex plugin add etherscan@etherscan
+```
+
 ### With the Skills CLI
 
 Install every skill in this repo:

skills/etherscan/SKILL.md

@@ -63,8 +63,9 @@ When the user does not specify an interface, apply these defaults.
 
 - Prefer the website for an interactive human workflow.
 - Prefer the API for an application integration or when the broadest endpoint coverage is required.
-- Prefer the CLI for terminal automation, pipelines, or exports.
-- Prefer MCP for agent-driven, read-only tool calls when an authenticated MCP connection is available.
+- Prefer the CLI for terminal automation, pipelines, exports, and agent-driven read-only lookups when the agent can run shell commands and the CLI is installed, has a resolved API key, and supports the requested chain, even when an MCP connection is also available.
+- Otherwise, prefer MCP when an MCP connection is available.
+- Otherwise, use the API (or the website for an interactive human workflow) and tell the user that the CLI or MCP would need setup.
 
 ## Respect capability boundaries
 
@@ -91,7 +92,10 @@ Use these representative cases to verify routing and guardrail behavior after ch
 | --- | --- |
 | Show an address in the block explorer. | Use the website reference and an interactive address page. |
 | Export a wallet's ERC-20 transfers to CSV from a terminal. | Use the CLI reference and its pagination and CSV support. |
-| Call an agent tool to retrieve a balance. | Use MCP when live discovery advertises a matching tool; inspect its current schema before calling it. |
+| An agent with shell access retrieves a balance, and both the CLI and an MCP connection are available. | Use the CLI; inspect its live help before running the command. |
+| An agent with shell access retrieves a balance; the CLI is installed but has no resolved API key or does not support the chain, and an MCP connection is available. | Use MCP; tell the user the CLI needs an API key or chain support to be preferred. |
+| An agent without shell access retrieves a balance. | Use MCP when live discovery advertises a matching tool; inspect its current schema before calling it. |
+| An agent retrieves a balance, and neither a usable CLI nor an MCP connection is available. | Use the API reference and tell the user that the CLI or MCP would need setup; do not claim an unavailable interface. |
 | Integrate token-holder counts into a backend. | Use the API and discover the current endpoint from official documentation; do not invent an MCP tool. |
 | The Etherscan CLI is installed locally. | Mention the installed version, inspect its live help, and use it when it matches the requested environment and output. |
 | An MCP server is documented but live discovery is unavailable. | Report its availability as unknown; do not describe it as connected or infer its tool inventory. |

skills/etherscan/references/mcp.md

@@ -32,13 +32,14 @@ Live discovery overrides remembered or bundled tool names and schemas.
 
 ## Durable constraints
 
-The official guide currently identifies the production endpoint as:
+The official guide currently identifies two production endpoints:
 
 ```text
-https://mcp.etherscan.io/mcp
+https://mcp.etherscan.io/mcp           # authenticated, full tool set, counts toward the key's API plan
+https://mcp-keyless.etherscan.io/mcp   # no key, no PRO tools, rate limited separately
 ```
 
-Use this bearer-header shape only when the client asks for the raw authentication form:
+Use this bearer-header shape for the authenticated endpoint, and only when the client asks for the raw authentication form:
 
 ```text
 Authorization: Bearer YourApiKeyToken
@@ -52,6 +53,18 @@ Authorization: Bearer YourApiKeyToken
 - Treat the MCP surface as read-only unless current tool discovery and official documentation explicitly establish a state-changing capability.
 - Require explicit authorization for the exact payload and chain before any state-changing tool call. Do not infer write support from another Etherscan interface.
 
+## Keep calls minimal
+
+- Call the narrowest tool that answers the question. Do not fetch holdings, history, labels, or funding sources only to decorate an answer.
+- Query one resolved chain. Do not probe or scan other chains unless the user asks for multichain results.
+- Use conservative pagination for activity lists, and say when a result is truncated or paginated.
+- Treat an empty result as "no records returned for this query," not as proof that no activity exists.
+- If a throttling error includes `retryAfter` or other reset details, report that timing instead of guessing one, and do not retry in a loop.
+
+## Render widgets only where they display
+
+Call a visual tool such as `render_etherscan_widget` only when current discovery advertises it, the user wants a visual result, and the host renders MCP app UI, as chat clients such as claude.ai and ChatGPT do. In a terminal or coding agent, or when unsure, answer in text instead. Copy only facts present in tool results into the widget, and never synthesize chart points from a single current value or a start and end value.
+
 ## If verification fails
 
 - Do not invent a tool, argument, schema, limit, or capability when live discovery is unavailable.