fhevm-skill — Portable FHEVM Skill for AI Coding Agents
Submission for: Zama Developer Program Mainnet Season 2 — Bounty Track
Author: @Makabeez
GitHub: GitHub - Makabeez/fhevm-skill: Production-ready AI agent skill (SKILL.md) for building confidential smart contracts on Zama Protocol. · GitHub
Demo video (2:23): https://youtu.be/S2rgXkSU0IE
What it is
A portable, agent-agnostic skill that teaches any AI coding agent — Claude Code, Cursor, Windsurf, Aider — how to write correct FHEVM smart contracts from a plain-English prompt. Zero FHE background required from the developer using the agent.
Why it matters
AI coding agents are how a growing share of developers write Solidity in 2026. But they have no built-in knowledge of FHE: encrypted types, ACL rules, async decryption flow, anti-patterns. The result is broken contracts that look plausible but fail silently or leak data.
fhevm-skill closes that gap with one drop-in instruction file plus a runnable validator.
What’s inside
| Component | What it does |
|---|---|
| SKILL.md | 14 sections — every encrypted type, every FHE operation, ACL rules, async decryption, 13 anti-patterns. Sourced from official Zama docs and the OpenZeppelin FHEVM security guide. |
| scripts/fhevm-lint.js | Static linter, zero dependencies. Catches 12 FHEVM anti-patterns (AP-001 → AP-013) before deployment with rule ID, line number, and exact fix. |
| templates/ | Three production-ready contracts: ConfidentialERC20, SealedBidAuction, ConfidentialVote. |
| references/cheatsheet.md | One-page quick reference for the most-used FHE patterns. |
| my-app/ | Hardhat project with 3 passing tests proving the templates work in mock FHE mode. |
The unique edge — runnable validation
Most documentation submissions are read-only. This one ships a linter you can execute against any FHEVM codebase in one command:
node scripts/fhevm-lint.js path/to/contracts/
Example output on a deliberately broken contract:
error line 17 [AP-001] if/else branching on encrypted value error line 18 [AP-003] Storing encrypted result without FHE.allowThis error line 24 [AP-005] Deprecated TFHE.decrypt() synchronous decryption 
warn line 10 [AP-008] euint256 used for token balance (prefer euint64) warn line 5 [AP-013] Legacy TFHE import (deprecated)
Found 4 error(s) 2 warning(s)
Each issue includes the rule ID, severity, line number, the offending code, and the exact fix. This turns the skill from “instructions an agent reads” into “instructions plus a tool that audits the agent’s output.”
How to use it
git clone https://github.com/Makabeez/fhevm-skill cd fhevm-skill/my-app npm install npx hardhat test # 3 passing tests in mock FHE mode
cd .. node scripts/fhevm-lint.js path/to/your/contracts/
For AI agent integration: load SKILL.md as a system prompt or add it to your agent’s context. The agent will have full FHEVM proficiency for the rest of the session.
Built and tested on
- Ubuntu 24.04 LTS (DigitalOcean droplet, Frankfurt)
- Node.js v22.22.2 (LTS)
- Hardhat v2 with
@fhevm/hardhat-pluginmock mode - Solidity 0.8.24
Repo & demo
- GitHub: GitHub - Makabeez/fhevm-skill: Production-ready AI agent skill (SKILL.md) for building confidential smart contracts on Zama Protocol. · GitHub
- Video: https://youtu.be/S2rgXkSU0IE
Feedback and PRs welcome — happy to extend the linter rule set or add more templates if the community has specific patterns they’d like covered.
Thanks to the Zama team for an excellent protocol and docs ecosystem.