@calimero-network/agent-skills 0.3.0 → 0.4.0

package/skills/calimero-rust-sdk/rules/app-macro-placement.md

@@ -29,6 +29,9 @@ impl AppState {
 }
 ```
 
-**Why:** `#[app::state]` and `#[app::logic]` are proc macros that transform impl blocks to register the type with the SDK runtime. The struct itself only needs the derive macros (`Default`, `BorshDeserialize`, `BorshSerialize`).
+**Why:** `#[app::state]` and `#[app::logic]` are proc macros that transform impl blocks to register
+the type with the SDK runtime. The struct itself only needs the derive macros (`Default`,
+`BorshDeserialize`, `BorshSerialize`).
 
-**Also:** `#[app::init]` marks the constructor — called once when the context is created. It must return the state type, not `Self`.
+**Also:** `#[app::init]` marks the constructor — called once when the context is created. It must
+return the state type, not `Self`.

package/skills/calimero-rust-sdk/rules/no-std-collections.md

@@ -22,6 +22,9 @@ pub struct AppState {
 }
 ```
 
-**Why:** `std::collections` types do not participate in the CRDT merge process. Data written to them by one node will never reach other context members. The bug is silent — the app compiles and runs correctly on one node, but state diverges in multi-member contexts.
+**Why:** `std::collections` types do not participate in the CRDT merge process. Data written to them
+by one node will never reach other context members. The bug is silent — the app compiles and runs
+correctly on one node, but state diverges in multi-member contexts.
 
-**Applies to:** `HashMap`, `BTreeMap`, `HashSet`, `BTreeSet`, `Vec` (for shared state). `Vec` is fine for temporary local values inside a method, just not as a field in the state struct.
+**Applies to:** `HashMap`, `BTreeMap`, `HashSet`, `BTreeSet`, `Vec` (for shared state). `Vec` is
+fine for temporary local values inside a method, just not as a field in the state struct.

package/skills/calimero-rust-sdk/rules/state-derives.md

@@ -1,8 +1,7 @@
 # Rule: State struct must derive Default, BorshDeserialize, BorshSerialize
 
-The three derives are all required. Missing any one of them causes a **runtime panic**,
-not a compile error — the app will install and start, then crash when the context is
-first accessed.
+The three derives are all required. Missing any one of them causes a **runtime panic**, not a
+compile error — the app will install and start, then crash when the context is first accessed.
 
 ## WRONG — missing derives:
 
@@ -30,11 +29,11 @@ pub struct AppState {
 
 ## What each derive does
 
-| Derive | Required for |
-| --- | --- |
-| `Default` | `#[app::init]` calls `AppState::default()` as the baseline |
-| `BorshDeserialize` | Loading state from node storage on every method call |
-| `BorshSerialize` | Saving state to node storage after every mutation |
+| Derive             | Required for                                               |
+| ------------------ | ---------------------------------------------------------- |
+| `Default`          | `#[app::init]` calls `AppState::default()` as the baseline |
+| `BorshDeserialize` | Loading state from node storage on every method call       |
+| `BorshSerialize`   | Saving state to node storage after every mutation          |
 
 ## Import
 
@@ -42,5 +41,5 @@ pub struct AppState {
 use calimero_sdk::borsh::{BorshDeserialize, BorshSerialize};
 ```
 
-Do not use `borsh` crate directly — import from `calimero_sdk::borsh` to ensure
-version compatibility.
+Do not use `borsh` crate directly — import from `calimero_sdk::borsh` to ensure version
+compatibility.

package/skills/calimero-rust-sdk/rules/wasm-constraints.md

@@ -2,16 +2,16 @@
 
 Calimero apps run in a sandboxed WASM environment. The following are **not available**:
 
-| Forbidden | Use instead |
-| --- | --- |
-| `std::thread::spawn` | Not supported — WASM is single-threaded |
+| Forbidden                                     | Use instead                                     |
+| --------------------------------------------- | ----------------------------------------------- |
+| `std::thread::spawn`                          | Not supported — WASM is single-threaded         |
 | `tokio`, `async-std`, `async fn` in app logic | Not supported — all app methods are synchronous |
-| `std::fs`, file I/O | Use `env::private_storage_write/read` |
-| `std::net`, HTTP calls outbound | Not supported in WASM runtime |
-| `println!`, `eprintln!` | Use `calimero_sdk::env::log(&str)` |
-| System time (`std::time::SystemTime`) | Use `calimero_sdk::env::block_timestamp()` |
-| Environment variables | Not accessible from WASM |
-| Random number generation via `rand` | Use `calimero_sdk::env::random_seed()` |
+| `std::fs`, file I/O                           | Use `env::private_storage_write/read`           |
+| `std::net`, HTTP calls outbound               | Not supported in WASM runtime                   |
+| `println!`, `eprintln!`                       | Use `calimero_sdk::env::log(&str)`              |
+| System time (`std::time::SystemTime`)         | Use `calimero_sdk::env::block_timestamp()`      |
+| Environment variables                         | Not accessible from WASM                        |
+| Random number generation via `rand`           | Use `calimero_sdk::env::random_seed()`          |
 
 ## Logging
 
@@ -32,4 +32,6 @@ let ts = env::block_timestamp(); // u64 nanoseconds
 
 ## Why
 
-The `merod` WASM runtime is deterministic by design. Non-deterministic operations (threads, I/O, time, random) would break the CRDT synchronization guarantees — every node must reach the same state given the same sequence of operations.
+The `merod` WASM runtime is deterministic by design. Non-deterministic operations (threads, I/O,
+time, random) would break the CRDT synchronization guarantees — every node must reach the same state
+given the same sequence of operations.

package/skills/calimero-sdk-js/SKILL.md

@@ -1,12 +1,12 @@
 # calimero-sdk-js — Agent Instructions
 
 You are helping a developer **build a Calimero P2P application in TypeScript** using
-`@calimero-network/calimero-sdk-js`. The app compiles to WebAssembly and runs inside the
-`merod` node runtime.
+`@calimero-network/calimero-sdk-js`. The app compiles to WebAssembly and runs inside the `merod`
+node runtime.
 
-> **NOT this skill** if the developer is connecting a browser/Node.js *frontend* to a node
-> (that's `calimero-client-js` / `@calimero-network/calimero-client`). This skill is for
-> writing the application logic that *runs on the node*.
+> **NOT this skill** if the developer is connecting a browser/Node.js _frontend_ to a node (that's
+> `calimero-client-js` / `@calimero-network/calimero-client`). This skill is for writing the
+> application logic that _runs on the node_.
 
 ## Install
 
@@ -15,18 +15,18 @@ pnpm add @calimero-network/calimero-sdk-js
 pnpm add -D @calimero-network/calimero-cli-js typescript
 ```
 
-The CLI's `postinstall` hook downloads QuickJS, WASI-SDK, and Binaryen automatically.
-If you used `--ignore-scripts`, re-run with `pnpm install --ignore-scripts=false`.
+The CLI's `postinstall` hook downloads QuickJS, WASI-SDK, and Binaryen automatically. If you used
+`--ignore-scripts`, re-run with `pnpm install --ignore-scripts=false`.
 
 ## Core concepts
 
-| Concept | What it is |
-| --- | --- |
-| `@State` class | Persisted data — fields must be CRDT types |
-| `@Logic(StateClass)` class | Entry points callable via JSON-RPC; must extend the state class |
-| `@Init` static method | Seeds the initial state when context is first created |
-| `@View()` method | Read-only — skips persistence; required for query methods |
-| CRDT collection | Conflict-free type (`Counter`, `UnorderedMap`, etc.) — all state fields must use these |
+| Concept                    | What it is                                                                             |
+| -------------------------- | -------------------------------------------------------------------------------------- |
+| `@State` class             | Persisted data — fields must be CRDT types                                             |
+| `@Logic(StateClass)` class | Entry points callable via JSON-RPC; must extend the state class                        |
+| `@Init` static method      | Seeds the initial state when context is first created                                  |
+| `@View()` method           | Read-only — skips persistence; required for query methods                              |
+| CRDT collection            | Conflict-free type (`Counter`, `UnorderedMap`, etc.) — all state fields must use these |
 
 ## Minimal app
 
@@ -61,16 +61,15 @@ export class KvLogic extends KvState {
 
 ## CRDT collections quick reference
 
-| Type | Use case | Key ops |
-| --- | --- | --- |
-| `Counter` | Distributed counting (returns `bigint`) | `increment()`, `incrementBy(n)`, `value()` |
-| `UnorderedMap<K,V>` | Key-value store (LWW per key) | `set()`, `get()`, `has()`, `remove()`, `entries()` |
-| `UnorderedSet<T>` | Unique membership (LWW per element) | `add()`, `has()`, `delete()`, `toArray()` |
-| `Vector<T>` | Ordered list | `push()`, `get(i)`, `pop()`, `len()` |
-| `LwwRegister<T>` | Single value (timestamp LWW) | `set()`, `get()` |
+| Type                | Use case                                | Key ops                                            |
+| ------------------- | --------------------------------------- | -------------------------------------------------- |
+| `Counter`           | Distributed counting (returns `bigint`) | `increment()`, `incrementBy(n)`, `value()`         |
+| `UnorderedMap<K,V>` | Key-value store (LWW per key)           | `set()`, `get()`, `has()`, `remove()`, `entries()` |
+| `UnorderedSet<T>`   | Unique membership (LWW per element)     | `add()`, `has()`, `delete()`, `toArray()`          |
+| `Vector<T>`         | Ordered list                            | `push()`, `get(i)`, `pop()`, `len()`               |
+| `LwwRegister<T>`    | Single value (timestamp LWW)            | `set()`, `get()`                                   |
 
-Nested collections (`Map<K, Set<V>>`) propagate changes automatically — no manual
-re-serialization.
+Nested collections (`Map<K, Set<V>>`) propagate changes automatically — no manual re-serialization.
 
 ## Build & deploy
 
@@ -105,7 +104,8 @@ meroctl --node-name <NODE> call \
 - `@Init` must be a static method that returns the state class instance
 - `@Logic(StateClass)` must extend the state class
 - No async, no I/O, no threads in app logic — the WASM runtime is synchronous
-- **Windows: building is not supported natively — use WSL** (QuickJS/WASI-SDK toolchain requires Linux/macOS)
+- **Windows: building is not supported natively — use WSL** (QuickJS/WASI-SDK toolchain requires
+  Linux/macOS)
 
 ## Events
 
@@ -131,7 +131,15 @@ const val = secret.get();
 
 Private entries are never broadcast to other nodes.
 
+## Related skills
+
+- **`calimero-core`** — runtime concepts (context/app model, JSON-RPC protocol, WebSocket events,
+  CRDT type taxonomy)
+- **`calimero-meroctl`** — full `meroctl` CLI reference for deploying and testing the app
+- **`calimero-client-js`** — connecting a browser/React frontend to the node (not building app
+  logic)
+
 ## References
 
-See `references/` for CRDT collections, events, and build pipeline details.
-See `rules/` for hard constraints.
+See `references/` for CRDT collections, events, and build pipeline details. See `rules/` for hard
+constraints.

package/skills/calimero-sdk-js/references/build-pipeline.md

@@ -4,7 +4,7 @@
 
 ## Pipeline stages
 
-```
+```text
 TypeScript  →  Rollup  →  QuickJS  →  WASI-SDK  →  Binaryen  →  .wasm
   Source       Bundle    C bytecode     WASM        Optimized
 ```
@@ -84,11 +84,11 @@ merobox bootstrap run examples/counter/workflows/counter-js.yml --log-level=trac
 
 ## Platform support
 
-| Platform | Supported |
-| --- | --- |
-| macOS (x64, arm64) | Yes |
-| Linux (x64, arm64) | Yes |
-| Windows (native) | No — use WSL |
+| Platform           | Supported    |
+| ------------------ | ------------ |
+| macOS (x64, arm64) | Yes          |
+| Linux (x64, arm64) | Yes          |
+| Windows (native)   | No — use WSL |
 
 ## Definition of done (before PR)
 

package/skills/calimero-sdk-js/references/collections.md

@@ -11,9 +11,9 @@ Distributed counting. The value is the sum across all contributing nodes.
 import { Counter } from '@calimero-network/calimero-sdk-js/collections';
 
 const counter = new Counter();
-counter.increment();            // +1
-counter.incrementBy(5n);        // +5 (bigint)
-const total = counter.value();  // bigint
+counter.increment(); // +1
+counter.incrementBy(5n); // +5 (bigint)
+const total = counter.value(); // bigint
 ```
 
 > Counter values are always `bigint`. Do not compare with `=== 0` — use `=== 0n`.
@@ -27,10 +27,10 @@ import { UnorderedMap } from '@calimero-network/calimero-sdk-js/collections';
 
 const map = new UnorderedMap<string, string>();
 map.set('key', 'value');
-const val = map.get('key');       // 'value' | undefined
-const exists = map.has('key');    // boolean
+const val = map.get('key'); // 'value' | undefined
+const exists = map.has('key'); // boolean
 map.remove('key');
-const all = map.entries();        // [['key', 'value'], ...]
+const all = map.entries(); // [['key', 'value'], ...]
 ```
 
 ## UnorderedSet\<T\>
@@ -41,8 +41,8 @@ Set of unique values with Last-Write-Wins per element.
 import { UnorderedSet } from '@calimero-network/calimero-sdk-js/collections';
 
 const set = new UnorderedSet<string>();
-set.add('item');          // true on first insert, false if already present
-set.has('item');          // true
+set.add('item'); // true on first insert, false if already present
+set.has('item'); // true
 set.delete('item');
 const items = set.toArray();
 ```
@@ -57,9 +57,9 @@ import { Vector } from '@calimero-network/calimero-sdk-js/collections';
 const vec = new Vector<string>();
 vec.push('first');
 vec.push('second');
-const item = vec.get(0);   // 'first'
-const last = vec.pop();    // 'second'
-const len = vec.len();     // 1 (bigint)
+const item = vec.get(0); // 'first'
+const last = vec.pop(); // 'second'
+const len = vec.len(); // 1 (bigint)
 ```
 
 ## LwwRegister\<T\>

package/skills/calimero-sdk-js/references/events.md

@@ -1,7 +1,7 @@
 # Events
 
-Events let your app push real-time notifications to all context members.
-They are emitted during mutation methods and received by clients via WebSocket.
+Events let your app push real-time notifications to all context members. They are emitted during
+mutation methods and received by clients via WebSocket.
 
 ## Emitting events
 
@@ -22,7 +22,11 @@ Events can only be emitted inside mutation methods (not `@View()` methods).
 Clients use `WsSubscriptionsClient` from `@calimero-network/calimero-client`:
 
 ```typescript
-import { WsSubscriptionsClient, getAppEndpointKey, getContextId } from '@calimero-network/calimero-client';
+import {
+  WsSubscriptionsClient,
+  getAppEndpointKey,
+  getContextId,
+} from '@calimero-network/calimero-client';
 
 const ws = new WsSubscriptionsClient(getAppEndpointKey()!, '/ws');
 await ws.connect();

package/skills/calimero-sdk-js/rules/crdt-only-state.md

@@ -1,18 +1,18 @@
 # Rule: All @State fields must be CRDT types
 
 Every field on a `@State` class must be a CRDT collection from
-`@calimero-network/calimero-sdk-js/collections`. Plain JavaScript types are not
-persisted or synchronized.
+`@calimero-network/calimero-sdk-js/collections`. Plain JavaScript types are not persisted or
+synchronized.
 
 ## WRONG — plain JS types in state:
 
 ```typescript
 @State
 export class AppState {
-  items: Map<string, string> = new Map();   // ✗ — not a CRDT, not synced
-  tags: string[] = [];                       // ✗ — not a CRDT, not synced
-  name: string = '';                         // ✗ — use LwwRegister instead
-  count: number = 0;                         // ✗ — use Counter instead
+  items: Map<string, string> = new Map(); // ✗ — not a CRDT, not synced
+  tags: string[] = []; // ✗ — not a CRDT, not synced
+  name: string = ''; // ✗ — use LwwRegister instead
+  count: number = 0; // ✗ — use Counter instead
 }
 ```
 
@@ -30,18 +30,18 @@ export class AppState {
 
 ## Why this matters
 
-Plain JS types are not serialized to the node's CRDT storage. State that uses
-`Map`, `Set`, `Array`, or primitives directly will be lost on the next call and
-will never sync to other nodes in the context.
+Plain JS types are not serialized to the node's CRDT storage. State that uses `Map`, `Set`, `Array`,
+or primitives directly will be lost on the next call and will never sync to other nodes in the
+context.
 
 ## Choosing the right CRDT
 
-| Data shape | Use |
-| --- | --- |
-| Counting (monotonic) | `Counter` |
-| Key-value lookup | `UnorderedMap<K, V>` |
-| Unique membership | `UnorderedSet<T>` |
-| Ordered list | `Vector<T>` |
-| Single value (overwrites) | `LwwRegister<T>` |
-| User-owned signed data | `UserStorage<T>` |
-| Immutable content | `FrozenStorage<T>` |
+| Data shape                | Use                  |
+| ------------------------- | -------------------- |
+| Counting (monotonic)      | `Counter`            |
+| Key-value lookup          | `UnorderedMap<K, V>` |
+| Unique membership         | `UnorderedSet<T>`    |
+| Ordered list              | `Vector<T>`          |
+| Single value (overwrites) | `LwwRegister<T>`     |
+| User-owned signed data    | `UserStorage<T>`     |
+| Immutable content         | `FrozenStorage<T>`   |

package/skills/calimero-sdk-js/rules/no-console-log.md

@@ -1,13 +1,13 @@
 # Rule: Use env.log() — not console.log()
 
-`console` is not available in the QuickJS/WASM runtime. Calling `console.log()` will
-throw a runtime error. Use `env.log()` from the SDK's env module instead.
+`console` is not available in the QuickJS/WASM runtime. Calling `console.log()` will throw a runtime
+error. Use `env.log()` from the SDK's env module instead.
 
 ## WRONG:
 
 ```typescript
-console.log('Processing item:', key);        // ✗ — throws at runtime
-console.error('Something went wrong');       // ✗ — throws at runtime
+console.log('Processing item:', key); // ✗ — throws at runtime
+console.error('Something went wrong'); // ✗ — throws at runtime
 ```
 
 ## CORRECT:
@@ -15,8 +15,8 @@ console.error('Something went wrong');       // ✗ — throws at runtime
 ```typescript
 import * as env from '@calimero-network/calimero-sdk-js/env';
 
-env.log(`Processing item: ${key}`);          // ✓ — output appears in node logs
-env.log(`Error: ${error}`);                  // ✓
+env.log(`Processing item: ${key}`); // ✓ — output appears in node logs
+env.log(`Error: ${error}`); // ✓
 ```
 
 ## env.log() format

package/skills/calimero-sdk-js/rules/view-decorator.md

@@ -1,8 +1,8 @@
 # Rule: @View() is required on read-only methods
 
-Every method that does not modify state must be decorated with `@View()`. Without it,
-the runtime will persist state after every call — even when nothing changed — causing
-unnecessary storage writes and cross-node syncs.
+Every method that does not modify state must be decorated with `@View()`. Without it, the runtime
+will persist state after every call — even when nothing changed — causing unnecessary storage writes
+and cross-node syncs.
 
 ## WRONG — read-only method without @View():
 
@@ -41,6 +41,8 @@ export class AppLogic extends AppState {
 ## How to tell if a method needs @View()
 
 A method is read-only if it:
-- Does not call any mutation methods on CRDT fields (`set`, `insert`, `add`, `push`, `increment`, etc.)
+
+- Does not call any mutation methods on CRDT fields (`set`, `insert`, `add`, `push`, `increment`,
+  etc.)
 - Does not call `emit()` or `emitWithHandler()`
 - Only reads values and returns results