How to use the Lark Event Listener agent skill

What is an agent skill and what does lark-event make the agent do?

An agent skill is a folder of instructions and reference files that an AI agent loads when a task matches it. The lark-event skill is one such folder. Its SKILL.md and reference files cover the lark-cli command-line tool and its event commands.

With this skill, the agent can list the event types it can subscribe to, read the fields of an event, and stream live events from Lark/Feishu as one line of JSON per event. The agent can then read those lines, filter them with jq expressions, and act on them.

• Stream events such as im.message.receive_v1 (new IM messages) and im.message.reaction.created_v1 (reactions added)
• Consume approval, task, VC meeting, minutes and whiteboard events
• Run listeners as background subprocesses with readiness signals, exit codes and shutdown rules

Install the lark-event skill

Download the ZIP of the skill from this page. Then choose one of two ways to install it.

Option A: unzip into your personal skills folder ~/.claude/skills/, or into a project's .claude/skills/ folder for use in one project only.

Option B: in the Claude apps, open Settings, go to Capabilities, then Skills, and upload the ZIP.

• Personal: unzip into ~/.claude/skills/
• Single project: unzip into the project's .claude/skills/ folder
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP

Set up lark-cli and authentication first

The skill does nothing without the lark-cli command-line tool installed and authenticated, and a Lark/Feishu tenant. The skill's metadata lists lark-cli as a required binary. Authentication, the --as user or --as bot switch, and Permission denied handling are described in the lark-shared skill, which the lark-event skill tells the agent to read first.

Your Lark app or bot also needs permissions for the event types you subscribe to. Some event types only work with a specific identity: the approval keys require --as user.

• lark-cli installed and on the PATH
• Authenticated Lark/Feishu account with the scopes the event needs
• lark-shared skill available for authentication details
• Bot or app permissions for each subscribed event type

Trigger the skill with natural requests

You do not need to type commands yourself. Describe the event and what you want done with it, and mention Lark or Feishu. The skill is written to handle requests such as listening for new messages, streaming reactions, or reacting to meeting end events.

The agent will look up the correct event key, check its fields, and then start the consumer. Be specific about how long the listener should run and what should happen to each event.

• "Listen for new messages sent to my Lark bot and reply to any that mention deployment."
• "Watch approval status changes for the next 30 minutes and tell me when one is approved."
• "Stream task updates from Lark for 10 minutes and summarise them."
• "Show me one sample event for VC meeting ended so I can see the fields."

Commands the agent runs

The core commands are lark-cli event list to see subscribable keys, lark-cli event schema to see one key's fields, and lark-cli event consume to stream events. Each event is written to stdout as NDJSON. Useful flags include --param (or -p) for business parameters, --jq to filter or reshape each event, --max-events to exit after N events, and --timeout to exit after a duration such as 30s or 2m.

• lark-cli event list --json
• lark-cli event schema <EventKey> --json
• lark-cli event consume <EventKey> [flags]
• Flags: --param, --jq, --max-events, --timeout, --output-dir, --as user|bot|auto

Run listeners safely as subprocesses

When an agent runs a listener in the background, the parent process should wait for the ready line on stderr, which looks like [event] ready event_key=<key>, before reading stdout. Do not use sleep as a substitute. Bounded runs with --max-events or --timeout exit on their own. For unbounded runs, stdin must stay open, because stdin closing causes a graceful exit.

Shut down with SIGTERM or by closing stdin. Avoid kill -9 on consume processes for minutes, vc and board keys, because it skips the server-side unsubscribe and can leave a subscription behind. To listen to several event types, start one consume process per key.

• Exit 0 with reason limit, timeout or signal means the run completed; non-zero means failure
• Exit 1 covers Lark API failures, 2 validation errors, 3 auth failures, 4 and 5 network or internal failures
• Do not use --quiet for AI runs, because it hides readiness and drop warnings
• Under nohup or systemd defaults, stdin is closed and an unbounded run exits at once; keep stdin open with < <(tail -f /dev/null) or use a bound

Filter events with jq

Use lark-cli event schema <key> --json to find where the fields start. A value of "." means fields sit at the top level, so you write .chat_id. A value of ".event" means fields are inside a V2 envelope, so you write .event.chat_id. Check each field's type and description before writing a filter.

For IM messages, the content field is already rendered to readable text for text, post, image, file and audio messages. Only interactive cards keep the raw JSON string, so do not run fromjson on every message.

• Filter a menu event: --jq 'select(.event_key == "start_eval")' on application.bot.menu_v6
• An empty jq output skips the event