@calimero-network/agent-skills 0.1.0

package/README.md

@@ -0,0 +1,238 @@
+# @calimero-network/agent-skills
+
+AI agent skills for [Calimero Network](https://calimero.network) development.
+
+Install these skills into your project to give AI coding assistants (Claude, Cursor, Copilot)
+accurate knowledge of the Calimero SDK, client libraries, registry tooling, and more — without
+hallucinating APIs that don't exist.
+
+## Skills
+
+| Skill | When to use |
+| --- | --- |
+| [`calimero-rust-sdk`](#calimero-rust-sdk) | Building Rust WASM applications |
+| [`calimero-client-js`](#calimero-client-js) | Frontend / Node.js clients connecting to a node |
+| [`calimero-registry`](#calimero-registry) | Signing and publishing apps to the registry |
+| [`calimero-desktop`](#calimero-desktop) | Integrating apps with Calimero Desktop SSO |
+| [`calimero-node`](#calimero-node) | Node operators and meroctl scripting |
+| [`calimero-merobox`](#calimero-merobox) | Local multi-node dev environments and CI |
+| [`calimero-client-py`](#calimero-client-py) | Python client for node automation and backend services |
+| [`calimero-abi-codegen`](#calimero-abi-codegen) | Generate TypeScript clients from WASM ABI manifests |
+
+## Install
+
+```bash
+# Install a specific skill (writes to CLAUDE.md by default)
+npx @calimero-network/agent-skills calimero-rust-sdk
+
+# Target a specific editor
+npx @calimero-network/agent-skills calimero-rust-sdk --cursor
+npx @calimero-network/agent-skills calimero-rust-sdk --copilot
+
+# List available skills
+npx @calimero-network/agent-skills --list
+```
+
+### Where skill files are written
+
+| Flag | File |
+| --- | --- |
+| (default) | `CLAUDE.md` |
+| `--cursor` | `.cursorrules` |
+| `--copilot` | `.github/copilot-instructions.md` |
+
+Running the install again updates the existing block without duplicating it.
+
+---
+
+## Skill reference
+
+### calimero-rust-sdk
+
+For developers building **Calimero WASM applications** in Rust.
+
+Covers:
+- App skeleton with `#[app]` macros
+- CRDT state collections (`UnorderedMap`, `Vector`, `Set`)
+- Event emission with `app::emit!()`
+- Private vs shared storage
+- WASM runtime constraints (no threads, no `async`, no std I/O)
+- Reference examples (kv-store, collaborative-editor)
+
+Key rules included:
+- Never use `std::collections` for state — CRDT collections only
+- `#[app]` macro goes on the `impl` block, not the struct
+- No `println!` — use `env::log()`
+
+```bash
+npx @calimero-network/agent-skills calimero-rust-sdk
+```
+
+---
+
+### calimero-client-js
+
+For developers building **frontends or Node.js services** that connect to a Calimero node.
+
+Covers:
+- Authentication and token storage
+- JSON-RPC calls (mutations and views)
+- WebSocket event subscriptions
+- SSO token reading from URL hash
+
+Key rules included:
+- `mero-js` v2 uses camelCase (`contextId`, not `context_id`)
+- Always handle 401 with token refresh before surfacing errors
+
+```bash
+npx @calimero-network/agent-skills calimero-client-js
+```
+
+---
+
+### calimero-registry
+
+For developers **publishing apps** to the Calimero App Registry.
+
+Covers:
+- `mero-sign` installation (crates.io and from source)
+- Key generation and security
+- `manifest.json` format and required fields
+- Signing workflow (RFC 8785 canonicalization + Ed25519)
+- `calimero-registry bundle create` and `bundle push`
+- Team / org signing patterns
+
+Key rules included:
+- Sign the manifest **before** bundling — not after
+- Never commit `key.json` to version control
+
+```bash
+npx @calimero-network/agent-skills calimero-registry
+```
+
+---
+
+### calimero-desktop
+
+For developers **integrating their app frontend** with Calimero Desktop SSO.
+
+Covers:
+- Hash params passed by Desktop (`access_token`, `refresh_token`, `node_url`, `application_id`)
+- Full startup integration pattern (React and vanilla JS)
+- How Desktop discovers the app's frontend URL (`manifest.json` `links.frontend`)
+
+Key rules included:
+- Always fall back to manual login when hash params are absent
+
+```bash
+npx @calimero-network/agent-skills calimero-desktop
+```
+
+---
+
+### calimero-node
+
+For **node operators** and developers scripting against a live node.
+
+Covers:
+- `merod` startup and configuration
+- Full `meroctl` command reference (app, context, identity, call)
+- Context lifecycle (app install → context create → invite → join → sync)
+
+Key rules included:
+- Application and context are different — installing an app does not create a context
+
+```bash
+npx @calimero-network/agent-skills calimero-node
+```
+
+---
+
+### calimero-merobox
+
+For developers setting up **local multi-node environments** or CI pipelines.
+
+Covers:
+- Merobox installation
+- Workflow YAML format
+- Multi-node setup with app deployment and context creation
+- GitHub Actions integration template
+
+Key rules included:
+- Docker must be running before any merobox command
+
+```bash
+npx @calimero-network/agent-skills calimero-merobox
+```
+
+---
+
+### calimero-client-py
+
+For developers using the **Python client** to automate or script against a Calimero node.
+
+Covers:
+- Full async API (contexts, apps, identities, blobs, aliases, proposals)
+- Authentication and token caching (`~/.merobox/auth_cache/`)
+- First-time token seeding and CI/CD patterns
+
+Key rules included:
+- `node_name` must be stable and unique per node — changing it loses cached tokens
+- All client methods are async and must be awaited
+
+```bash
+npx @calimero-network/agent-skills calimero-client-py
+```
+
+---
+
+### calimero-abi-codegen
+
+For developers **generating typed TypeScript clients** from a Calimero app's ABI manifest.
+
+Covers:
+- CLI usage (`npx calimero-abi-codegen -i abi.json -o src/generated`)
+- ABI manifest format (`wasm-abi/1` schema, types, methods, events)
+- Generated output shape (`types.ts` + `{ClientName}.ts`)
+- Programmatic API for custom codegen pipelines
+- Integrating codegen into your build script
+
+Key rules included:
+- ABI must have `"schema_version": "wasm-abi/1"` — other values are rejected
+- Method, event, and type names must all be unique; map keys must be string
+
+```bash
+npx @calimero-network/agent-skills calimero-abi-codegen
+```
+
+---
+
+## Structure
+
+Each skill follows this layout:
+
+```
+skills/<skill-name>/
+├── SKILL.md          # Agent instructions: what to know, what to avoid
+├── references/       # Detailed API guides with real code examples
+└── rules/            # Hard rules: one file per rule, named after the rule
+```
+
+The install script appends skill content to your editor's context file, wrapped in
+markers so re-running updates the block cleanly.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for how to add or update a skill.
+
+Skills should be:
+- Based on real API surfaces, not pseudocode
+- Focused on code examples over prose
+- Kept up to date with library releases
+
+## Links
+
+- [Calimero Network](https://calimero.network)
+- [Documentation](https://docs.calimero.network)
+- [GitHub org](https://github.com/calimero-network)
+- [Discord](https://discord.gg/urJeMtRRMu)

package/SKILL.md

@@ -0,0 +1,43 @@
+# Calimero Network — Agent Skills
+
+This package provides AI agent skills for building on the Calimero Network stack.
+
+## Available Skills
+
+| Skill | Install command | When to use |
+| --- | --- | --- |
+| `calimero-rust-sdk` | `npx @calimero-network/agent-skills calimero-rust-sdk` | Building Rust WASM applications |
+| `calimero-client-js` | `npx @calimero-network/agent-skills calimero-client-js` | Frontend / Node.js clients connecting to a node |
+| `calimero-registry` | `npx @calimero-network/agent-skills calimero-registry` | Signing and publishing apps to the registry |
+| `calimero-desktop` | `npx @calimero-network/agent-skills calimero-desktop` | Integrating apps with Calimero Desktop SSO |
+| `calimero-node` | `npx @calimero-network/agent-skills calimero-node` | Node operators and meroctl scripting |
+| `calimero-merobox` | `npx @calimero-network/agent-skills calimero-merobox` | Local multi-node dev environments and CI |
+| `calimero-client-py` | `npx @calimero-network/agent-skills calimero-client-py` | Python client for node automation and backend services |
+| `calimero-abi-codegen` | `npx @calimero-network/agent-skills calimero-abi-codegen` | Generate TypeScript clients from WASM ABI manifests |
+
+## Auto-Detection
+
+Skills should be loaded when the following are detected in the project:
+
+| Signal | Load skill |
+| --- | --- |
+| `calimero-sdk` in `Cargo.toml` | `calimero-rust-sdk` |
+| `@calimero-network/calimero-client` in `package.json` | `calimero-client-js` |
+| `@calimero-network/mero-js` in `package.json` | `calimero-client-js` |
+| `mero-sign` in any script or Makefile | `calimero-registry` |
+| `calimero-registry` CLI usage | `calimero-registry` |
+| `access_token` read from `window.location.hash` | `calimero-desktop` |
+| `merobox` in `package.json` or `requirements.txt` | `calimero-merobox` |
+| `calimero-client-py` in `requirements.txt` or `pyproject.toml` | `calimero-client-py` |
+| `calimero-abi-codegen` or `abi.json` in project | `calimero-abi-codegen` |
+
+## About Calimero
+
+Calimero is a framework for distributed, peer-to-peer applications with automatic CRDT-based data synchronization, user-owned data, and verifiable off-chain computing.
+
+Core concepts:
+- **Context** — an isolated application instance with its own state, members, and storage
+- **Application** — WASM code deployed to a node; each context runs one application
+- **Node** (`merod`) — the runtime that hosts apps, syncs state, and exposes JSON-RPC/WebSocket
+- **Identity** — root key → client keys per device; JWT tokens for API auth
+- **CRDT state** — conflict-free replicated data; state lives on node storage, synced across context members

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@calimero-network/agent-skills",
+  "version": "0.1.0",
+  "description": "AI agent skills for Calimero Network development — Rust SDK, JS client, registry publishing, desktop SSO, and more.",
+  "keywords": [
+    "calimero",
+    "agent-skills",
+    "ai",
+    "p2p",
+    "crdt",
+    "wasm",
+    "mero-sign",
+    "calimero-sdk"
+  ],
+  "homepage": "https://github.com/calimero-network/agent-skills",
+  "bugs": {
+    "url": "https://github.com/calimero-network/agent-skills/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/calimero-network/agent-skills.git"
+  },
+  "license": "MIT",
+  "bin": {
+    "calimero-skills": "./scripts/install.js"
+  },
+  "files": [
+    "skills/",
+    "SKILL.md",
+    "scripts/",
+    "README.md"
+  ],
+  "scripts": {
+    "format": "prettier --write \"**/*.{md,json,js,ts}\"",
+    "format:check": "prettier --check \"**/*.{md,json,js,ts}\"",
+    "lint:md": "markdownlint-cli2 \"**/*.md\" \"!node_modules/**\"",
+    "test": "node scripts/test.js"
+  },
+  "devDependencies": {
+    "markdownlint-cli2": "^0.13.0",
+    "prettier": "^3.3.3"
+  }
+}

package/scripts/install.js

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const SKILLS_DIR = path.join(__dirname, '..', 'skills');
+const VALID_SKILLS = fs.readdirSync(SKILLS_DIR).filter((f) =>
+  fs.statSync(path.join(SKILLS_DIR, f)).isDirectory()
+);
+
+const TARGETS = {
+  claude: 'CLAUDE.md',
+  cursor: '.cursorrules',
+  copilot: '.github/copilot-instructions.md',
+};
+
+function parseArgs() {
+  const args = process.argv.slice(2);
+  const skill = args.find((a) => !a.startsWith('--'));
+  const target = args.includes('--cursor')
+    ? 'cursor'
+    : args.includes('--copilot')
+      ? 'copilot'
+      : 'claude';
+  const listOnly = args.includes('--list');
+  return { skill, target, listOnly };
+}
+
+function readSkillContent(skillName) {
+  const skillDir = path.join(SKILLS_DIR, skillName);
+  const parts = [];
+
+  // SKILL.md first
+  const skillMd = path.join(skillDir, 'SKILL.md');
+  if (fs.existsSync(skillMd)) {
+    parts.push(fs.readFileSync(skillMd, 'utf8').trim());
+  }
+
+  // references/
+  const refsDir = path.join(skillDir, 'references');
+  if (fs.existsSync(refsDir)) {
+    const refs = fs.readdirSync(refsDir).filter((f) => f.endsWith('.md'));
+    for (const ref of refs.sort()) {
+      parts.push(fs.readFileSync(path.join(refsDir, ref), 'utf8').trim());
+    }
+  }
+
+  // rules/
+  const rulesDir = path.join(skillDir, 'rules');
+  if (fs.existsSync(rulesDir)) {
+    const rules = fs.readdirSync(rulesDir).filter((f) => f.endsWith('.md'));
+    for (const rule of rules.sort()) {
+      parts.push(fs.readFileSync(path.join(rulesDir, rule), 'utf8').trim());
+    }
+  }
+
+  return parts.join('\n\n---\n\n');
+}
+
+function appendToFile(filePath, header, content) {
+  const marker = `<!-- calimero-skills:${header} -->`;
+  const block = `\n\n${marker}\n\n${content}\n\n${marker}:end`;
+
+  if (fs.existsSync(filePath)) {
+    const existing = fs.readFileSync(filePath, 'utf8');
+    // Replace existing block if present
+    const re = new RegExp(`${marker}[\\s\\S]*?${marker}:end`, 'g');
+    if (re.test(existing)) {
+      fs.writeFileSync(filePath, existing.replace(re, block.trim()));
+      return 'updated';
+    }
+    fs.appendFileSync(filePath, block);
+    return 'appended';
+  } else {
+    fs.writeFileSync(filePath, block.trim());
+    return 'created';
+  }
+}
+
+function main() {
+  const { skill, target, listOnly } = parseArgs();
+
+  if (listOnly || !skill) {
+    console.log('\nAvailable Calimero agent skills:\n');
+    for (const s of VALID_SKILLS) {
+      console.log(`  ${s}`);
+    }
+    console.log('\nUsage:');
+    console.log('  npx @calimero-network/agent-skills <skill-name>');
+    console.log('  npx @calimero-network/agent-skills <skill-name> --cursor');
+    console.log('  npx @calimero-network/agent-skills <skill-name> --copilot');
+    console.log('  npx @calimero-network/agent-skills --list\n');
+    if (!listOnly) process.exit(1);
+    return;
+  }
+
+  if (!VALID_SKILLS.includes(skill)) {
+    console.error(`\nUnknown skill: "${skill}"`);
+    console.error(`Valid skills: ${VALID_SKILLS.join(', ')}\n`);
+    process.exit(1);
+  }
+
+  const content = readSkillContent(skill);
+  const targetFile = TARGETS[target];
+
+  // Ensure parent dir exists (e.g. .github/ for copilot)
+  const dir = path.dirname(path.resolve(targetFile));
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+
+  const result = appendToFile(targetFile, skill, content);
+  console.log(`\n✓ Skill "${skill}" ${result} in ${targetFile}`);
+  console.log(`  Target: ${target}\n`);
+}
+
+main();

package/scripts/test.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const SKILLS_DIR = path.join(__dirname, '..', 'skills');
+let passed = 0;
+let failed = 0;
+
+function assert(condition, message) {
+  if (condition) {
+    console.log(`  ✓ ${message}`);
+    passed++;
+  } else {
+    console.error(`  ✗ ${message}`);
+    failed++;
+  }
+}
+
+const skills = fs.readdirSync(SKILLS_DIR).filter((f) =>
+  fs.statSync(path.join(SKILLS_DIR, f)).isDirectory()
+);
+
+console.log(`\nChecking ${skills.length} skills...\n`);
+
+for (const skill of skills) {
+  console.log(`[${skill}]`);
+  const skillDir = path.join(SKILLS_DIR, skill);
+
+  assert(
+    fs.existsSync(path.join(skillDir, 'SKILL.md')),
+    'SKILL.md exists'
+  );
+  assert(
+    fs.existsSync(path.join(skillDir, 'references')),
+    'references/ directory exists'
+  );
+  assert(
+    fs.existsSync(path.join(skillDir, 'rules')),
+    'rules/ directory exists'
+  );
+
+  const skillMd = path.join(skillDir, 'SKILL.md');
+  if (fs.existsSync(skillMd)) {
+    const content = fs.readFileSync(skillMd, 'utf8');
+    assert(content.length > 100, 'SKILL.md has meaningful content');
+    assert(content.includes('##'), 'SKILL.md has sections');
+  }
+
+  const refsDir = path.join(skillDir, 'references');
+  if (fs.existsSync(refsDir)) {
+    const refs = fs.readdirSync(refsDir).filter((f) => f.endsWith('.md'));
+    assert(refs.length > 0, `references/ has at least one file (found ${refs.length})`);
+  }
+
+  const rulesDir = path.join(skillDir, 'rules');
+  if (fs.existsSync(rulesDir)) {
+    const rules = fs.readdirSync(rulesDir).filter((f) => f.endsWith('.md'));
+    assert(rules.length > 0, `rules/ has at least one file (found ${rules.length})`);
+  }
+
+  console.log('');
+}
+
+console.log(`Results: ${passed} passed, ${failed} failed\n`);
+if (failed > 0) process.exit(1);

package/skills/calimero-abi-codegen/SKILL.md

@@ -0,0 +1,61 @@
+# calimero-abi-codegen — Agent Instructions
+
+You are helping a developer use **`calimero-abi-codegen`** to generate typed TypeScript
+clients from a Calimero WASM application's ABI manifest.
+
+## What it does
+
+Takes an `abi.json` file (exported by the Calimero Rust SDK) and generates two files:
+- `types.ts` — all TypeScript type definitions matching the app's Rust types
+- `{ClientName}.ts` — a typed client class with methods for every app function
+
+After codegen, frontend developers call app methods with full TypeScript type safety
+instead of constructing raw JSON-RPC calls by hand.
+
+## Install & run
+
+```bash
+# One-off (no install)
+npx calimero-abi-codegen -i abi.json -o src/generated
+
+# Or install globally
+npm install -g @calimero-network/abi-codegen
+calimero-abi-codegen -i abi.json -o src/generated
+```
+
+## CLI flags
+
+| Flag | Default | Description |
+| --- | --- | --- |
+| `-i, --input <file>` | `abi.json` | Input ABI JSON file |
+| `-o, --outDir <dir>` | `src` | Output directory |
+| `--client-name <Name>` | `Client` | Class name for generated client |
+| `--name-from <path>` | — | Derive class name from a file path (e.g. WASM file) |
+| `--import-path <path>` | `@calimero-network/calimero-client` | Import path for base types |
+| `--validate` | — | Validate ABI only, no code generation |
+
+## Quick examples
+
+```bash
+# Basic
+npx calimero-abi-codegen -i abi.json -o src/generated
+
+# Custom class name
+npx calimero-abi-codegen -i abi.json -o src/generated --client-name KvStoreClient
+
+# Derive class name from WASM filename
+npx calimero-abi-codegen -i abi.json -o src/generated --name-from kv_store.wasm
+# → generates class KvStore
+
+# Just validate the ABI (CI check)
+npx calimero-abi-codegen --validate -i abi.json
+```
+
+## Critical: ABI schema version must be `wasm-abi/1`
+
+The input JSON must have `"schema_version": "wasm-abi/1"`. Other versions are rejected.
+
+## References
+
+See `references/` for ABI format, generated output shape, and programmatic API.
+See `rules/` for schema version and unique name requirements.

package/skills/calimero-abi-codegen/references/abi-format.md

@@ -0,0 +1,105 @@
+# ABI Manifest Format
+
+The input `abi.json` follows the `wasm-abi/1` schema.
+
+## Minimal valid ABI
+
+```json
+{
+  "schema_version": "wasm-abi/1",
+  "types": {},
+  "methods": [],
+  "events": []
+}
+```
+
+## Full example — KV Store ABI
+
+```json
+{
+  "schema_version": "wasm-abi/1",
+  "types": {
+    "Entry": {
+      "kind": "record",
+      "fields": [
+        { "name": "key",   "type": { "kind": "string" } },
+        { "name": "value", "type": { "kind": "string" } }
+      ]
+    }
+  },
+  "methods": [
+    {
+      "name": "set",
+      "params": [
+        { "name": "key",   "type": { "kind": "string" } },
+        { "name": "value", "type": { "kind": "string" } }
+      ]
+    },
+    {
+      "name": "get",
+      "params": [
+        { "name": "key", "type": { "kind": "string" } }
+      ],
+      "returns": { "kind": "string" },
+      "returns_nullable": true
+    },
+    {
+      "name": "entries",
+      "params": [],
+      "returns": { "kind": "list", "items": { "$ref": "Entry" } }
+    }
+  ],
+  "events": [
+    {
+      "name": "ItemSet",
+      "payload": { "$ref": "Entry" }
+    }
+  ]
+}
+```
+
+## Type reference forms
+
+```json
+{ "kind": "string" }                      // scalar
+{ "kind": "bool" }
+{ "kind": "u32" }
+{ "kind": "u64" }
+{ "kind": "bytes", "encoding": "hex" }    // variable bytes
+{ "$ref": "TypeName" }                    // reference to named type in types{}
+{ "kind": "list", "items": { ... } }      // array
+{ "kind": "map", "key": { ... }, "value": { ... } }  // map (key must be string)
+{ "kind": "record", "fields": [...] }     // inline struct
+```
+
+## Type definitions (`types` object)
+
+```json
+"types": {
+  "MyStruct": {
+    "kind": "record",
+    "fields": [
+      { "name": "id",    "type": { "kind": "u64" } },
+      { "name": "name",  "type": { "kind": "string" } },
+      { "name": "tags",  "type": { "kind": "list", "items": { "kind": "string" } } }
+    ]
+  },
+  "Status": {
+    "kind": "variant",
+    "variants": [
+      { "name": "Active" },
+      { "name": "Inactive" },
+      { "name": "Pending", "payload": { "kind": "string" } }
+    ]
+  }
+}
+```
+
+## Validation rules
+
+- `schema_version` must be exactly `"wasm-abi/1"`
+- No `$ref` pointing to a type not in `types{}`
+- Map keys must be string type
+- All method names must be unique
+- All event names must be unique
+- All type names must be unique