zama-skills

Zama Protocol skill pack for AI coding agents (Claude Code, Cursor, Windsurf, OpenCode, Codex, Aider, Continue) — from an empty directory to a working confidential dApp in 30 minutes.

Built for: Zama Developer Program — Mainnet Season 2 / Bounty Track.

Differentiator: Every code-generating skill (/zama-contract, /zama-test, /zama-frontend, /zama-audit, /zama-debug) queries context7 MCP for live Zama documentation before emitting code — /zama-ai/fhevm (1,772 snippets), /zama-ai/fhevm-hardhat-template, /websites/openzeppelin_confidential-contracts. APIs are checked against current docs, not the model’s training cut-off, so deprecated packages and renamed symbols don’t slip through.

On top of that, /zama-contract refuses 12 forbidden cleartext-leak patterns at generation time — require(FHE.decrypt(x)), if (FHE.decrypt(x)), comparing euint handles with ==/</>, branching on cleartext ebool, decrypting storage slots, and others. The static guard fires even when the user explicitly asks for the pattern, and /zama-audit re-runs the same checks plus ACL-grant verification across the whole repo.

Polished UI out of the box. /zama-frontend reads your contract source, detects the variant (token / voting / wrapper / auction), and materializes a complete Tailwind-styled dApp — connect wallet, network indicator, encrypted-input + reveal panels, transaction status with Etherscan links, dark-mode-ready theme. No more bare <button> placeholders: the panels you ship are the panels the skill writes.

Watch the full video walkthrough (unlisted)   ·   Live dApp on Vercel   ·   Verified contract on Sepolia

Prerequisites

After install, verify with /zama-doctor — it checks every requirement and prints fix commands for whatever is missing.

Install — pick your AI tool

Best experience: Claude Code. This pack was designed around Claude Code’s slash commands, skill auto-routing, and inter-skill chaining (/zama-design → /zama-init → /zama-contract → /zama-test → /zama-audit → /zama-deploy). The other tools get the same underlying skill content as portable markdown rules — useful, but you orchestrate the chain yourself instead of one slash command kicking off the next.

Click the section that matches your editor / agent.

Don’t see your tool? Pick Generic at the bottom — it drops a self-contained zama-skills-knowledge/ folder you can hand-point any AI agent at.

/plugin marketplace add github.com/kocaemre/zama-skills
/plugin install zama-skills@zama-skills
/zama-doctor                # verifies Node ≥ 20, pnpm, context7 + magic MCP

npx zama-skills@latest install --tool claude-code             # writes to ./.claude/skills (this project only)
npx zama-skills@latest install --tool claude-code --scope personal   # writes to ~/.claude/skills (every project)

/zama-autonomous            # one command, full pipeline (design → … → frontend)
/zama-design                # or run skills individually:
/zama-init                  # scaffold pnpm monorepo
/zama-contract              # author confidential .sol with verified ACL
/zama-test                  # mock + Sepolia tests
/zama-audit                 # FHE-aware review (must pass before deploy)
/zama-deploy                # Sepolia + Etherscan verify (manual confirm)
/zama-frontend              # wire @zama-fhe/relayer-sdk
/zama-debug                 # match an FHE error to a fix command
/zama-doctor                # diagnose env at any time

/plugin update zama-skills                                    # marketplace install
npx zama-skills@latest uninstall --tool claude-code --force   # npx install

cd <your-project>
npx zama-skills@latest install --tool cursor --force

npx zama-skills@latest uninstall --tool cursor --force

cd <your-project>
npx zama-skills@latest install --tool windsurf --force

npx zama-skills@latest uninstall --tool windsurf --force

cd <your-project>
npx zama-skills@latest install --tool opencode --force

npx zama-skills@latest uninstall --tool opencode --force

cd <your-project>
npx zama-skills@latest install --tool codex --force

npx zama-skills@latest uninstall --tool codex --force

cd <your-project>
npx zama-skills@latest install --tool aider --force

aider --read CONVENTIONS.md

npx zama-skills@latest uninstall --tool aider --force

cd <your-project>
npx zama-skills@latest install --tool continue --force

npx zama-skills@latest uninstall --tool continue --force

cd <your-project>
npx zama-skills@latest install --tool generic --force

npx zama-skills@latest uninstall --tool generic --force

# Interactive multi-select picker (Claude Code is auto-pre-selected)
npx zama-skills@latest install

# Specific tools
npx zama-skills@latest install --tool claude-code,cursor,opencode --force

# Every supported tool (CI-friendly)
npx zama-skills@latest install --all --force

Re-running install is idempotent — it’s safe to run any time you want to refresh your local copy after a zama-skills release.

Where do the rules go? (project vs global scope)

--scope project (default) writes under cwd — the rules ship with your repo, your team gets them on git pull. This is the right choice for almost every tool.

--scope personal writes under $HOME — only Claude Code actually reads global rules from ~/.claude/skills/. The other tools key off the current working directory.

The CLI prints a warning if you pick --scope personal for a tool that won’t honor it. Recommended: keep the default --scope project, commit the rule files to your repo, and let your team’s AI agents pick them up automatically.

Demo

The full walkthrough lives at the top of this README — GIF + video + live dApp + verified contract.

Pipeline shown: /plugin marketplace add → /zama-design → /zama-init → /zama-contract → /zama-deploy (live Sepolia) → MetaMask decrypt on the live dApp.

Quick Start — pick your path

After installing the plugin, jump straight to the path that matches your goal. Each path is a chain of skills; Claude Code picks the next one automatically from the closing summary, but you can also type the slash commands yourself.

Path 0 — One command, the whole thing (~30 min, recommended for first-timers)

/zama-autonomous

Runs the full pipeline (design → init → contract → test → audit → deploy → frontend) in sequence. Pauses only at safety gates: design review, audit findings, the manual deploy confirmation, and final smoke. Resumable — if you stop or hit an error, re-run /zama-autonomous and it asks whether to resume from the saved step or start fresh.

State lives at .planning/v1-autonomous/state.json (no secrets, just step progress). Run /zama-doctor first if you’re not sure your environment is ready.

Path 1 — Manual chain (full pipeline, ~30 min)

Same outcome as Path 0, but you trigger each skill yourself:

/zama-design   →   "describe your idea"
/zama-init     →   scaffold the monorepo
/zama-contract →   write the confidential contract
/zama-test     →   mock + Sepolia tests
/zama-audit    →   FHE-aware code review (must pass)
/zama-deploy   →   Sepolia deploy + Etherscan verify
/zama-frontend →   wire the UI

Best for: hackathon submissions, MVPs, learning the stack end-to-end. Each skill’s closing summary tells you the next one — Claude Code auto-suggests it.

Path 2 — Just the contract (~5 min)

You already have a project; you only need a confidential ERC-7984 / Votes / custom contract.

/zama-contract
# pick: name, base (erc7984 / votes / custom), state schema, decryption path

Output drops at packages/contracts/contracts/<Name>.sol with auto-injected ACL grants and a refusal to emit any cleartext-leak pattern. Recommended follow-up: /zama-test for the test scaffolding, /zama-audit to confirm the diff is clean.

Path 3 — Audit / harden an existing contract (~2 min)

You inherited a confidential contract or wrote one by hand. Run the FHE-aware review:

/zama-audit              # scans current directory
/zama-audit ./contracts  # scoped to a path

Reports ACL gaps, cleartext leaks, HCU explosions (>12 FHE ops/fn), deprecated imports. Exits 0 (clean), 1 (warnings), 2 (critical) so you can wire it into CI.

Path 4 — Debug a runtime error (~1 min)

You got an error from hardhat, vitest, the relayer, or the live dApp. Paste it:

/zama-debug
# paste the stack trace / revert message when prompted

Matches against a 10+ pattern catalog (ACL revert, initSDK undefined, deprecated imports, HCU exceeded, SSR indexedDB, etherscan v1, relayer timeout, etc.) and prints the root cause + the exact fix command.

Path 5 — Design only (no code), then hand off

You want a planning artifact you can share with collaborators or feed into the chain later.

/zama-design

Produces DESIGN.md (contract architecture + ACL strategy per actor + decryption path per data type) and UI-WIREFRAME.md (component tree + 4-state UX flows). Both files reference live Zama docs via context7 — no hallucinated APIs. Pick this path if you want to validate the architecture before committing to scaffolding.

What you get — 10 skills

/zama-deploy has disable-model-invocation: true — Claude will not auto-deploy on its own. You must invoke it explicitly.

Try it live

See examples/confidential-token/ — a confidential ERC-7984 token (cDEMO) deployed to Sepolia at 0x04Bd105DE7a5D3297c3747cef90ac8b760136896 and live on Vercel. Built end-to-end by running this plugin’s skills against an empty directory — every contract, test, deploy script, and React component is reproducible from the recorded skill commit SHAs in .gsd-snapshot.json.

Why this exists

Building a confidential dApp on Zama Protocol requires juggling: pinned @fhevm/solidity + @openzeppelin/confidential-contracts versions, ACL discipline (FHE.allowThis after every state write), HCU budget awareness (20M/tx, 5M depth), three different decryption paths (public / user / oracle), the Confidential Token Registry, and the relayer SDK on the frontend. Get any of it wrong — say, ship code that imports the deprecated fhevmjs package or forgets a single FHE.allow call — and your dApp silently fails on Sepolia.

zama-skills codifies the official patterns. Every skill, before generating code, queries context7 for the canonical Zama doc snippet that covers the user’s request. No “vibes-based FHE.”

Compatibility

• Network: Sepolia testnet only (mainnet support deferred to v2 — needs auditing rigor).
• Node.js: >=20.
• Solidity: ^0.8.24+ (template default 0.8.27).
• Hardhat: ^2.x (Hardhat 3 is not supported by @fhevm/hardhat-plugin yet).
• Ethers: v6 only (v5 will mismatch typechain output).
• Refuses to emit: fhevmjs (deprecated 2025-07-10 → use @zama-fhe/relayer-sdk), root fhevm package (deprecated → use @fhevm/solidity), ethers@5, Hardhat 3.

How it works

.claude-plugin/marketplace.json      ← catalog
plugins/zama-skills/
├── .claude-plugin/plugin.json        ← manifest
└── skills/
    ├── init/SKILL.md                 ← /zama-init   (auto-invoke, context: fork)
    ├── contract/SKILL.md             ← /zama-contract
    ├── test/SKILL.md                 ← /zama-test
    ├── deploy/SKILL.md               ← /zama-deploy (manual only)
    ├── frontend/SKILL.md             ← /zama-frontend
    ├── design/SKILL.md               ← /zama-design  (plan/blueprint, v1.1)
    ├── audit/SKILL.md                ← /zama-audit   (FHE-aware code review, v1.1)
    └── debug/SKILL.md                ← /zama-debug   (error → fix matcher, v1.1)

The plugin is a single Claude Code marketplace at the repo root. Skill folder names drop the zama- prefix (the plugin namespace already supplies it) so commands read /zama-init not /zama-zama-init.

CI / quality gates

• npm run validate — zod schema check for marketplace.json + plugin.json + all 5 SKILL.md frontmatters (rejects: bad kebab-case, reserved marketplace names, .. in source paths, missing disable-model-invocation on deploy, missing context: fork on init, missing allowed-tools on any skill, combined description+when_to_use over 1,536 chars).
• npx tsc --noEmit — strict TypeScript on the CLI.
• npm test — vitest.
• GitHub Actions runs all of the above on push and every PR.

Roadmap

Links

• Repository: github.com/kocaemre/zama-skills
• npm package: npmjs.com/package/zama-skills
• Example dApp: examples/confidential-token/
• Live demo: zama-skills.vercel.app
• Roadmap: .planning/ROADMAP.md (visible on the GitHub repo, not shipped in the npm tarball)
• Issues / contributions: open an issue or PR on github.com/kocaemre/zama-skills — bug reports, missing patterns, and pinned-version refresh PRs all welcome.
• License: LICENSE
• Third-party licenses: THIRD_PARTY_LICENSES.md

License

MIT © 2026 Emre Koca

Acknowledgements

• Zama — fhEVM, FHE Solidity library, hardhat plugin, relayer SDK
• OpenZeppelin — Confidential Contracts (ERC-7984)
• Anthropic — Claude Code skills + plugins format
• context7 — live docs MCP that powers anti-hallucination