From zama-skills
Diagnose fhEVM / Zama Protocol errors from a pasted revert message, vitest failure, hardhat trace, or runtime exception. Matches the input against a curated catalog of 10 known patterns (ACL grants, deprecated fhevmjs/fhevm imports, HCU exhaustion, relayer SSR/indexedDB, Etherscan v1, relayer 502, wagmi ABI drift, ZamaConfig path, /bundle vs /web entry) and returns a likely root cause, concrete fix command(s), and an authoritative reference link.
How this skill is triggered — by the user, by Claude, or both
Slash command
/zama-skills:debugThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
<!-- @sync:prompt:mcp-prerequisite -->
This skill talks to two MCP servers. The first is required; the second is recommended for higher-quality UI output.
| MCP | Status | Why | Install |
|---|---|---|---|
context7 | REQUIRED | Live Zama / OpenZeppelin Confidential / fhEVM docs (anti-hallucination guarantee) | claude mcp add context7 -- npx -y @upstash/context7-mcp |
magic (21st.dev) | RECOMMENDED for /zama-frontend and /zama-design | Production-grade UI component scaffolding (shadcn-flavored, design-system-aware) | claude mcp add magic -- npx -y @21st-dev/magic (sign-in required) |
Before invoking any mcp__context7__* or mcp__magic__* tool, verify the tool is available. If a context7 call would fail (tool not found / not in the available tool list):
STOP. Do NOT generate any code or write any file.
Tell the user (verbatim, do not paraphrase):
This skill requires the context7 MCP server to fetch live Zama documentation.
It does not appear to be installed.
Install it (one-time setup):
claude mcp add context7 -- npx -y @upstash/context7-mcp
After install, restart Claude Code (or run /mcp to verify) and re-run this skill.
Wait for the user to confirm install. Re-attempt the call. If it still fails, tell the user to run /zama-doctor for a full diagnostic.
If a magic call would fail (only relevant for /zama-frontend and /zama-design UI generation):
Do NOT stop — magic is optional. Continue with hand-authored shadcn components.
Tell the user (once, near the start of UI generation):
Magic MCP (21st.dev) is not installed. UI components will be hand-authored
using shadcn primitives. For higher-quality, design-system-aware components,
install Magic:
claude mcp add magic -- npx -y @21st-dev/magic
Then restart Claude Code and re-run this skill.
Continue without magic.
context7 is hard-required. Every Zama / OpenZeppelin / fhEVM API the skill emits is verified against /zama-ai/fhevm (1772 HIGH-reputation snippets) and /websites/openzeppelin_confidential-contracts (354 snippets). A WebFetch fallback would weaken the anti-hallucination guarantee — if context7 is unavailable, the right answer is to fix the setup, not to silently degrade.
Run /zama-doctor — it lists every required and recommended MCP/tool with install commands and a status check.
Single source of truth. Every SKILL.md in this plugin transcludes this block via a
@sync:shared:context7-querymarker pair. Edit here, runpnpm sync, and all skills update.
Zama Protocol package surfaces (@fhevm/solidity, @zama-fhe/relayer-sdk, @fhevm/hardhat-plugin, @openzeppelin/confidential-contracts) evolve faster than any LLM training cut-off. To avoid hallucinated APIs, always query context7 for live documentation before emitting Zama-related code.
When this skill activates, BEFORE generating any Solidity, TypeScript, or config file that touches fhEVM, perform the following calls in order:
Resolve the primary fhEVM library
mcp__context7__resolve-library-idlibraryName: "fhevm" → expect /zama-ai/fhevm (HIGH reputation, ~1772 snippets).Fetch topic-scoped fhEVM docs for the operation in progress
mcp__context7__get-library-docscontext7CompatibleLibraryId: "/zama-ai/fhevm"topic: narrowed to the user's question (e.g., "acl", "decryption", "euint", "relayer", "auction").Fetch hardhat-template scaffolding docs when generating build/test infra
context7CompatibleLibraryId: "/zama-ai/fhevm-hardhat-template"topic: such as "deploy", "test", "mock".Fetch OpenZeppelin Confidential Contracts when generating tokens, governance, or vesting
context7CompatibleLibraryId: "/websites/openzeppelin_confidential-contracts"topic: such as "ERC7984", "VotesConfidential", "FHESafeMath".Fallback narrowing — if returned docs are too broad, re-call get-library-docs with a tighter topic: parameter focused on the user's exact question.
fhevmjs or fhevm (root package). Both were officially deprecated 2025-07-10. Replacements are @zama-fhe/relayer-sdk and @fhevm/solidity respectively.pinned-versions.json, the JSON wins. That file was npm-registry-verified on 2026-05-03 and reflects peer-dep alignment across the Zama stack. Treat docs as API guidance; treat the JSON as version truth.https://docs.zama.org/protocol/protocol-apps/addresses/testnet/sepolia at skill runtime.| Library ID | Snippets | Use For |
|---|---|---|
/zama-ai/fhevm | 1772 | Solidity FHE primitives, ACL, decryption, encrypted types |
/zama-ai/fhevm-hardhat-template | 43 | Hardhat config, deploy scripts, mock testing |
/websites/openzeppelin_confidential-contracts | 354 | ERC-7984, governance, FHESafeMath |
You are operating inside a Zama Protocol skill. Before emitting any package import, dependency declaration, or install command, you MUST consult the deprecation/incompatibility ban list.
Before emitting ANY import statement, package.json dependency entry, or npm install / pnpm add command:
plugins/zama-skills/shared/deprecated-imports.json.deprecated key:
replaces instead.// fhevmjs deprecated 2025-07-10; using @zama-fhe/relayer-sdk).incompatible key:
useInstead instead.// hardhat v3 incompatible with @fhevm/hardhat-plugin peer range).plugins/zama-skills/shared/pinned-versions.jsonplugins/zama-skills/shared/snippets/deprecation-guard.mdThis skill turns a pasted error message / stack trace into an actionable
diagnosis. The pattern catalog lives at assets/PATTERNS.md (mirror of
scripts/lib/patterns.ts) — 10 high-frequency fhEVM failure modes.
Use AskUserQuestion with a single free-text prompt:
Paste the full error message — including the stack trace if you have it. The more lines, the better the match. Truncated one-liners often miss because the unique signal lives a few frames down.
If the user has a log file on disk, accept a path instead and read it
with Read. Either way, hold the raw text in memory for Step 2.
Invoke the matcher CLI:
node ${CLAUDE_SKILL_DIR}/scripts/diagnose.ts --error "$(printf '%s' "$ERROR_TEXT")"
Or, if the text is in a file:
node ${CLAUDE_SKILL_DIR}/scripts/diagnose.ts --file path/to/error.log
The script:
0 on a match and prints a markdown block with
Likely cause, Fix (numbered steps; commands prefixed with $),
and a Reference link.1 on no match and prints next-step guidance
(re-paste full trace, search docs, query context7).2 on usage error.Surface the printed markdown verbatim to the user.
Do not fabricate a fix. Instead:
mcp__context7__get-library-docs query against
/zama-ai/fhevm with a tight topic (e.g., topic: "decryption",
topic: "acl", topic: "sepolia").The catalog already contains deprecated-fhevmjs and
deprecated-fhevm-root. If a diagnosis lands on either:
@zama-fhe/relayer-sdk@^0.4.2 and @fhevm/solidity@^0.11.1
respectively).// fhevmjs deprecated 2025-07-10; using @zama-fhe/relayer-sdk).After printing the diagnosis, append:
---
Pattern matched: <pattern-name>
Catalog: assets/PATTERNS.md (10 entries)
If this didn't fix it, re-paste the full stack — truncation is the #1 cause of misses.
Add new patterns by:
DebugPattern entry to scripts/lib/patterns.ts.### <name> section to assets/PATTERNS.md
with the same heading id (the test suite asserts both files match).SAMPLES map in
scripts/diagnose.test.ts so the per-pattern regression test passes.vitest run skills/debug and confirming all tests pass.{{patternName}}{{fixCommands}}
/zama-debug again — patterns evolve as the SDK updates.Pattern catalog:
plugins/zama-skills/skills/debug/assets/PATTERNS.md(10+ entries, contributions welcome).
Provides UI/UX resources: 50+ styles, color palettes, font pairings, guidelines, charts for web/mobile across React, Next.js, Vue, Svelte, Tailwind, React Native, Flutter. Aids planning, building, reviewing interfaces.
Fetches up-to-date documentation from Context7 for libraries and frameworks like React, Next.js, Prisma. Use for setup questions, API references, and code examples.
npx claudepluginhub kocaemre/zama-skills --plugin zama-skills