# iii-observe

A skill for Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and OpenCode that teaches the agent how to wire iii functions together with iii.observe.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 1100 installs · ★ 18938 repo stars
- Author: iii-hq
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/iii-hq/iii/tree/HEAD/skills/iii-observe/SKILL.md
- Updated: 2026-11-09
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/iii-observe

## What it does

The skill covers the full observer API in the `iii` framework: basic two-argument `iii.observe(a, b)` calls, filter expressions, `capture` configuration, and options like `max_in_flight` and `expires_in_ms`. All examples span TypeScript, Python, Rust, Go, and the browser SDK.

In `iii`, every event is a function call: an HTTP request is a call of `http::on-request`, a cron tick of `cron::on-tick`, a row change of `database::on-row-changed`. Observing one of these source functions — with the right `args` — is how a handler binds to that event. The `capture` field controls which parts of the observed call (input, output, error, caller) the target receives. A `capture` list that omits all of `input`, `output`, and `error` causes the engine to return `INVALID_ARGS`.

For custom event sources, the skill covers four lifecycle hooks: `onObserverAdded`, `onObserverRemoved`, `onObservationMatch`, and `onObservationDeliver`. The observer stays in `pending` state until the target function is registered, so registration order matters.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add iii-hq/iii --skill iii-observe -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/iii-observe/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/iii-observe/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add iii-hq/iii --skill iii-observe -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/iii-observe/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add iii-hq/iii --skill iii-observe -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/iii-observe/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install iii-hq/iii skills/iii-observe
```

2. **Manually: put the files in place**
- File: `.github/skills/iii-observe/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add iii-hq/iii --skill iii-observe -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/iii-hq/iii --path skills/iii-observe
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/iii-observe/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add iii-hq/iii --skill iii-observe -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/iii-hq/iii/tree/HEAD/skills/iii-observe/SKILL.md

## When to use it
- chain an alert function to every successful call of another function
- bind a request handler to an HTTP route via `http::on-request`
- set up a cron job by observing `cron::on-tick` with a schedule expression
- catch only failed calls using `capture: ["error"]` with an input field filter
- build a custom event source using `onObserverAdded` and `onObservationDeliver` hooks

## Example prompts
- Subscribe `alerts::big-order` to every successful `orders::create` call using `iii.observe`
- Set up an observer on `payments::charge` with filter `input.amount >= 500` and `capture: ["error", "caller"]`
- Bind `orders::create` to POST `/orders` by observing `http::on-request` with the appropriate args

## Similar
- [code-craft](https://affpapa.org/en/nevibecode/skills/code-craft.md) — skill · 1700 installs
- [webhook-development](https://affpapa.org/en/nevibecode/skills/webhook-development.md) — skill · 510 installs
- [test-specialist](https://affpapa.org/en/nevibecode/skills/travisjneuman-test-specialist.md) — skill · 138 installs
- [cli-anything-firefly-iii](https://affpapa.org/en/nevibecode/skills/cli-anything-firefly-iii.md) — skill · 410 installs
- [event-driven-architect](https://affpapa.org/en/nevibecode/skills/event-driven-architect.md) — skill · 292 installs
- [rust-anything](https://affpapa.org/en/nevibecode/skills/rust-anything.md) — skill · ★ 7482 repo stars

From the same set: [iii-hq/iii](https://affpapa.org/en/nevibecode/by/iii-hq/iii.md) — 8 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
