DEV Community

UtkarshVarma
UtkarshVarma

Posted on

Building midnight-agent-skills: AI-Powered Development for Privacy-First Blockchain Made Easy

#agents #ai #blockchain #privacy

By Utkarsh Varma, Webisoft Development Labs

The Problem: Privacy Blockchain Development is Hard

Building on Midnight Network isn't like building on Ethereum or Solana. It's a completely different paradigm:

  • New Language: Compact, a domain-specific language for zero-knowledge circuits
  • Privacy Primitives: Shielded/unshielded states, selective disclosure, witnesses
  • Complex Tooling: Proof servers, indexers, specialized nodes
  • Limited Resources: Fewer tutorials, examples, and Stack Overflow answers

When I started building on Midnight, I spent hours:

  • Debugging pragma syntax errors (is it >= 0.16 && <= 0.18 or >= 0.19?)
  • Figuring out why circuit fn(): Void doesn't work (it's [], not Void)
  • Understanding the difference between ledger {} block syntax (deprecated) vs export ledger (correct)
  • Setting up local infrastructure with the right version combinations

Every AI coding assistant I used—Claude, Cursor, Copilot—would generate wrong Compact code because they were trained on outdated or incorrect syntax.

The Insight: AI Agents Need Midnight-Specific Knowledge

AI coding assistants are incredibly powerful, but they have a knowledge cutoff. They don't know:

  • The latest Compact syntax (v0.19+ as of December 2025)
  • Midnight-specific patterns (commit-reveal, selective disclosure)
  • Infrastructure setup quirks (version synchronization between node/indexer/proof-server)
  • Common mistakes and their fixes

What if we could give AI agents the knowledge they need to build on Midnight correctly?

That's when I discovered the Agent Skills format from Vercel. They created a way to package domain-specific knowledge that AI agents can consume and use.

The Solution: midnight-agent-skills

I built midnight-agent-skills—a collection of curated, verified knowledge that extends AI coding assistants for Midnight development.

How It Works 

┌─────────────────────────────────────────────────────────────┐
│                     Your AI Agent                           │
│               (Claude, Cursor, Copilot)                     │
└─────────────────────┬───────────────────────────────────────┘
                      │
                      │ reads
                      ▼
┌─────────────────────────────────────────────────────────────┐
│                 midnight-agent-skills                        │
│                                                             │
│  ┌─────────────────┐  ┌─────────────────┐                  │
│  │ CLAUDE.md       │  │ AGENTS.md       │                  │
│  │ Agent guidance  │  │ Agent guidance  │                  │
│  └─────────────────┘  └─────────────────┘                  │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │                    skills/                           │   │
│  │                                                      │   │
│  │  midnight-compact-guide/    Compact v0.19+ syntax   │   │
│  │  midnight-sdk-guide/        TypeScript SDK          │   │
│  │  midnight-infra-setup/      Infrastructure          │   │
│  │  midnight-deploy/           Deployment              │   │
│  │  midnight-test-runner/      Testing                 │   │
│  │                                                      │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
└─────────────────────────────────────────────────────────────┘
                      │
                      │ generates
                      ▼
┌─────────────────────────────────────────────────────────────┐
│              Correct Midnight Code                          │
│                                                             │
│  pragma language_version >= 0.19;                          │
│  import CompactStandardLibrary;                            │
│  export ledger counter: Counter;                           │
│  export circuit increment(): [] { ... }                    │
│                                                             │
└─────────────────────────────────────────────────────────────┘
Enter fullscreen mode Exit fullscreen mode

When you clone the repo into your project, your AI agent automatically reads the CLAUDE.md and AGENTS.md files. These files:

  1. Describe available skills and when to use them
  2. Provide critical syntax notes so the agent doesn't make common mistakes
  3. Reference detailed rules in the skills/ directory

The Skills

1. midnight-compact-guide

The core skill. Contains everything about Compact language syntax (v0.19+):

Correct patterns:

pragma language_version >= 0.19;

import CompactStandardLibrary;

// Ledger - individual declarations (NOT block syntax)
export ledger counter: Counter;
export ledger owner: Bytes<32>;

// Witness - declaration only, NO body
witness local_secret_key(): Bytes<32>;

// Circuit - returns [] (NOT Void)
export circuit increment(): [] {
  counter.increment(1);
}

// Pure circuit (NOT pure function)
pure circuit helper(x: Field): Field {
  return x + 1;
}
Enter fullscreen mode Exit fullscreen mode

Common mistakes it prevents:

AI Would Generate Skill Teaches Correct
ledger { counter: Counter; } export ledger counter: Counter;
circuit fn(): Void circuit fn(): []
pure function helper() pure circuit helper()
Choice::rock Choice.rock
counter.value() counter.read()

2. midnight-sdk-guide

TypeScript SDK integration:

  • Wallet connection (Lace)
  • Contract deployment
  • State management
  • Error handling
  • React hooks

3. midnight-infra-setup

Local infrastructure setup:

4. midnight-deploy

Deployment workflow:

  • Compile contracts
  • Deploy to local
  • Deploy to preview testnet
  • Environment configuration

5. midnight-test-runner

Testing with Vitest:

  • Contract simulators
  • Private state testing
  • Selective disclosure verification

How I Built It

Step 1: Study Existing Formats

I cloned vercel-labs/agent-skills to understand the format:

skill/
├── SKILL.md           # Main skill definition (YAML frontmatter + content)
├── rules/             # Detailed rules
│   └── rule-name.md
└── scripts/           # Executable scripts
    └── script.sh
Enter fullscreen mode Exit fullscreen mode

Step 2: Gather Authoritative Sources

I studied multiple sources for correct Compact syntax:

  1. MeshJS Starter Template - Most up-to-date (pragma >= 0.19, updated Dec 2025)
  2. midnight-mcp - Comprehensive syntax reference
  3. OpenZeppelin Compact Contracts - Older but battle-tested patterns
  4. Official Midnight Docs - Language reference

The MeshJS template was the most current, so I based the syntax on that.

Step 3: Create Skills with Verified Patterns

Every code example in the skills was verified against actual compiling contracts. I didn't just copy from docs—I checked:

  • Does this pragma format work?
  • Is ledger {} block syntax still supported? (No, deprecated)
  • What's the return type for circuits? ([], not Void)
  • Do witnesses have bodies in Compact? (No, declaration only)

Step 4: Build the CLI

I created an npx-installable CLI:

// bin/cli.js
#!/usr/bin/env node
import { run } from '../src/index.js';
run(process.argv.slice(2));

// Usage
npx midnight-agent-skills init        // Add all skills
npx midnight-agent-skills add <skill> // Add specific skill
npx midnight-agent-skills list        // List skills
Enter fullscreen mode Exit fullscreen mode

Problems It Solves

1. Wrong Syntax Generation

Before: AI generates circuit fn(): Void { }
After: AI generates circuit fn(): [] { }

2. Outdated Patterns

Before: AI uses deprecated ledger {} block syntax
After: AI uses correct export ledger field: Type;

3. Infrastructure Confusion

Before: Spend hours figuring out version compatibility
After: Skill provides exact versions and synchronization requirements

4. Missing Patterns

Before: Reinvent commit-reveal pattern from scratch
After: Copy verified, working pattern from skill

5. Testing Struggles

Before: Figure out how to test private state
After: Use provided simulator patterns

Building with midnight-agent-skills

Quick Start 

# Create a new Midnight project
mkdir my-midnight-dapp
cd my-midnight-dapp

# Add the skills
npx midnight-agent-skills init

# Now your AI agent knows Midnight!
Enter fullscreen mode Exit fullscreen mode

Example Workflow

1. Ask your AI to write a contract:

Write a Midnight contract for a simple voting system where:
- Users can vote once
- Votes are private (shielded)
- Final tally is public
Enter fullscreen mode Exit fullscreen mode

2. The AI reads the skills and generates correct code:

pragma language_version >= 0.19;

import CompactStandardLibrary;

export ledger totalVotes: Counter;
export ledger hasVoted: Map<Bytes<32>, Boolean>;

witness local_secret_key(): Bytes<32>;

circuit get_voter_id(): Bytes<32> {
  const sk = local_secret_key();
  return persistentHash<Vector<2, Bytes<32>>>([pad(32, "vote:id:"), sk]);
}

export circuit vote(choice: Uint<8>): [] {
  const voter = get_voter_id();
  assert(disclose(!hasVoted.member(voter)), "Already voted");

  hasVoted.insert(disclose(voter), true);
  totalVotes.increment(1);
}
Enter fullscreen mode Exit fullscreen mode

3. Ask for infrastructure setup:

Set up local Midnight infrastructure for testing
Enter fullscreen mode Exit fullscreen mode

4. The AI provides correct commands:

# Start node
docker run -p 9944:9944 midnightntwrk/midnight-node

# Start indexer (must match node version)
docker run -p 8088:8088 midnightntwrk/midnight-indexer

# Start proof server
docker run -p 6300:6300 midnightntwrk/midnight-proof-server
Enter fullscreen mode Exit fullscreen mode

Technical Architecture

File Structure 

midnight-agent-skills/
├── package.json              # npm package config
├── bin/
│   └── cli.js               # npx entry point
├── src/
│   └── index.js             # CLI logic
├── skills/
│   ├── midnight-compact-guide/
│   │   ├── SKILL.md         # Main skill (Compact v0.19+)
│   │   └── rules/
│   │       ├── privacy-selective-disclosure.md
│   │       ├── tokens-shielded-unshielded.md
│   │       ├── common-errors.md
│   │       └── openzeppelin-patterns.md
│   ├── midnight-sdk-guide/
│   │   ├── SKILL.md
│   │   └── rules/
│   │       └── wallet-integration.md
│   ├── midnight-infra-setup/
│   │   ├── SKILL.md
│   │   └── scripts/
│   │       └── setup.sh
│   ├── midnight-deploy/
│   │   ├── SKILL.md
│   │   └── scripts/
│   │       └── deploy.sh
│   └── midnight-test-runner/
│       ├── SKILL.md
│       └── scripts/
│           └── test.sh
├── AGENTS.md                 # Agent guidance
├── CLAUDE.md                 # Claude-specific guidance
├── README.md
├── CONTRIBUTING.md
└── LICENSE
Enter fullscreen mode Exit fullscreen mode

SKILL.md Format 

---
name: midnight-compact-guide
description: Triggers on "write contract", "Compact syntax"...
license: MIT
metadata:
  author: webisoft
  version: "2.1.0"
  compact-version: "0.19+"
---

# Skill Title

Content with verified code examples...
Enter fullscreen mode Exit fullscreen mode

How AI Agents Discover Skills

  1. Claude Code: Reads CLAUDE.md automatically
  2. Cursor: Reads .cursorrules or AGENTS.md
  3. Other agents: Read AGENTS.md or skill files directly

The CLAUDE.md and AGENTS.md files contain:

  • Overview of available skills
  • Trigger phrases
  • Critical syntax notes (prevents common mistakes)
  • Quick reference code

Verification Process

Every code pattern in the skills was verified:

Source Priority

  1. MeshJS Starter Template (Dec 2025) - Most current
  2. Midnight Official Docs - Language reference
  3. midnight-mcp - Curated syntax guide
  4. OpenZeppelin Compact - Audited patterns (older version)

Verification Steps 

# 1. Check MeshJS template
grep "pragma language_version" counter-contract/src/counter.compact
# Result: pragma language_version >= 0.19;

# 2. Check OpenZeppelin
grep "pragma language_version" compact-contracts/contracts/**/*.compact
# Result: pragma language_version >= 0.15.0;  (older)

# 3. Check git history
git log --format="%ad %s" --date=short counter-contract/src/counter.compact
# Result: 2025-12-17 bump: preview yaml and tooling & compiler

# Conclusion: Use >= 0.19 from MeshJS (most recent)
Enter fullscreen mode Exit fullscreen mode

Future Plans

More Skills

  • midnight-audit - Security audit patterns
  • midnight-upgrade - Contract upgrade patterns
  • midnight-bridge - Cross-chain integration
  • midnight-identity - DID and credential patterns

Better Tooling

  • VS Code extension for skill browsing
  • Web interface for skill search
  • Auto-update mechanism for syntax changes

Community Contributions

  • Contribution guide available
  • Open for PRs with new patterns
  • Verification process for community skills

Conclusion

Building on Midnight doesn't have to be painful. With midnight-agent-skills, your AI coding assistant becomes a Midnight expert:

  • Knows the correct Compact syntax (v0.19+)
  • Understands privacy patterns
  • Can set up infrastructure
  • Helps with testing and deployment

Get started:

npx midnight-agent-skills init
Enter fullscreen mode Exit fullscreen mode

Then just ask your AI to help you build on Midnight. It will know what to do.

Resources

Built with care by Webisoft Development Labs

Maintained by Utkarsh Varma (@UvRoxx)

Top comments (0)