home / skills / openclaw / skills / lark-calendar

lark-calendar skill

unsafe

This skill helps you manage Lark calendar events and tasks end-to-end, resolving attendee names automatically and syncing with your timezone.

npx playbooks add skill openclaw/skills --skill lark-calendar

Review the files below or copy the command above to add this skill to your agents.

Files (17)

SKILL.md

6.8 KB

---
name: lark-calendar
description: Create, update, and delete calendar events and tasks in Lark (Feishu). Includes employee directory for automatic name-to-user_id resolution.
version: 1.0.0
author: Claw AI
---

# Lark Calendar & Task Skill

Create, update, and delete calendar events and tasks in Lark (Feishu).

## Overview

This skill provides full CRUD operations for:
- **Calendar Events** — meetings, appointments, schedules
- **Tasks (Todo)** — action items with deadlines

## Configuration

**Required Environment Variables** (in `.secrets.env`):
```bash
FEISHU_APP_ID=cli_a9f52a4ed7b8ded4
FEISHU_APP_SECRET=<your-app-secret>
```

**Default Calendar:** `[email protected]` (Claw calendar)

**Default Timezone:** `Asia/Singapore`

## Quick Reference

### Create Calendar Event

```bash
node skills/lark-calendar/scripts/create-event.mjs \
  --title "Meeting with Team" \
  --description "Discuss Q2 roadmap" \
  --start "2026-02-03 14:00:00" \
  --end "2026-02-03 15:00:00" \
  --attendees "Boyang,RK" \
  --location "Meeting Room A"
```

**Parameters:**
| Param | Required | Description |
|-------|----------|-------------|
| `--title` | ✅ | Event title |
| `--description` | ❌ | Event description |
| `--start` | ✅ | Start time (YYYY-MM-DD HH:MM:SS) |
| `--end` | ✅ | End time (YYYY-MM-DD HH:MM:SS) |
| `--attendees` | ❌ | Comma-separated names (auto-resolved to user_ids) |
| `--attendee-ids` | ❌ | Comma-separated user_ids directly |
| `--location` | ❌ | Event location |
| `--timezone` | ❌ | Timezone (default: Asia/Singapore) |
| `--calendar` | ❌ | Calendar ID (uses default if omitted) |

### Update Calendar Event

```bash
node skills/lark-calendar/scripts/update-event.mjs \
  --event-id "f9900f6b-b472-4b17-a818-7b5584abdc37_0" \
  --title "Updated Title" \
  --start "2026-02-03 15:00:00" \
  --end "2026-02-03 16:00:00"
```

### Delete Calendar Event

```bash
node skills/lark-calendar/scripts/delete-event.mjs \
  --event-id "f9900f6b-b472-4b17-a818-7b5584abdc37_0"
```

### List Calendar Events

```bash
# List events for next 7 days
node skills/lark-calendar/scripts/list-events.mjs

# List events in date range
node skills/lark-calendar/scripts/list-events.mjs \
  --start "2026-02-01" \
  --end "2026-02-28"
```

### Create Task

```bash
node skills/lark-calendar/scripts/create-task.mjs \
  --title "Review PR #123" \
  --description "Code review for authentication module" \
  --due "2026-02-05 18:00:00" \
  --assignees "Boyang,jc"
```

**Parameters:**
| Param | Required | Description |
|-------|----------|-------------|
| `--title` | ✅ | Task title |
| `--description` | ❌ | Task description |
| `--due` | ✅ | Due date (YYYY-MM-DD HH:MM:SS) |
| `--assignees` | ❌ | Comma-separated names (auto-resolved) |
| `--assignee-ids` | ❌ | Comma-separated user_ids directly |
| `--timezone` | ❌ | Timezone (default: Asia/Singapore) |

### Update Task

```bash
node skills/lark-calendar/scripts/update-task.mjs \
  --task-id "35fc5310-a1b1-49c7-be75-be631d3079ee" \
  --title "Updated Task" \
  --due "2026-02-06 18:00:00"
```

### Delete Task

```bash
node skills/lark-calendar/scripts/delete-task.mjs \
  --task-id "35fc5310-a1b1-49c7-be75-be631d3079ee"
```

### Manage Event Attendees

```bash
# Add attendees
node skills/lark-calendar/scripts/manage-attendees.mjs \
  --event-id "xxx" --add "RK,jc"

# Remove attendees  
node skills/lark-calendar/scripts/manage-attendees.mjs \
  --event-id "xxx" --remove "jc"
```

### Manage Task Members

```bash
# Add members
node skills/lark-calendar/scripts/manage-task-members.mjs \
  --task-id "xxx" --add "RK,jc"

# Remove members
node skills/lark-calendar/scripts/manage-task-members.mjs \
  --task-id "xxx" --remove "jc"
```

## Employee Directory

Names are auto-resolved to Lark user_ids. Supported names:

| user_id | Names | Role |
|---------|-------|------|
| `dgg163e1` | Boyang, by, 博洋 | Boss |
| `gb71g28b` | RK | Leadership, R&D |
| `53gc5724` | Ding | Leadership, Operations |
| `217ec2c2` | Charline | HR |
| `f2bfd283` | 曾晓玲, xiaoling | HR |
| `f26fe45d` | HH | Research |
| `45858f91` | zan, Eva | - |
| `7f79b6de` | Issac | Operations |
| `1fb2547g` | 王铁柱 | Operations |
| `e5997acd` | 尼克, Nico | Operations |
| `438c3c1f` | Ivan | Operations |
| `17g8bab2` | Dodo | R&D, Product |
| `73b45ec5` | 启超, QiChaoShi | R&D, Design |
| `d1978a39` | chenglin | R&D, Frontend |
| `ef6fc4a7` | 冠林, Green | R&D, Frontend |
| `b47fa8f2` | sixian, sx, Sixian-Yu | R&D, Frontend |
| `934fbf15` | jc, sagiri, 俊晨 | R&D, Backend |
| `8c4aad87` | 大明, daming | R&D, Backend |
| `ab87g5e1` | Emily Yobal | Intern |
| `55fa337f` | jingda, 景达 | Intern |
| `333c7cf1` | 刘纪源, 纪源, Aiden | Intern |

## Business Rules

1. **Boyang is always added** as attendee to every calendar event (automatic)
2. **Timezone handling:** Uses IANA identifiers (e.g., `Asia/Singapore`, `Asia/Shanghai`)
3. **Time format:** Always `YYYY-MM-DD HH:MM:SS`
4. **user_id vs open_id:** This skill uses `user_id` format (e.g., `dgg163e1`), NOT `open_id` (e.g., `ou_xxx`)

## Programmatic Usage

```javascript
import { createEvent, updateEvent, deleteEvent } from './skills/lark-calendar/lib/calendar.mjs';
import { createTask, updateTask, deleteTask } from './skills/lark-calendar/lib/task.mjs';
import { resolveNames } from './skills/lark-calendar/lib/employees.mjs';

// Create event
const result = await createEvent({
  title: 'Team Sync',
  description: 'Weekly standup',
  startTime: '2026-02-03 10:00:00',
  endTime: '2026-02-03 10:30:00',
  attendeeIds: ['dgg163e1', 'gb71g28b'],
  location: 'Zoom',
  timezone: 'Asia/Singapore'
});

// Create task
const task = await createTask({
  title: 'Review document',
  description: 'Q2 planning doc',
  dueTime: '2026-02-05 18:00:00',
  assigneeIds: ['dgg163e1'],
  timezone: 'Asia/Singapore'
});
```

## Lark API Reference

- [Calendar Events API](https://open.larksuite.com/document/server-docs/calendar-v4/calendar-event/create)
- [Calendar Attendees API](https://open.larksuite.com/document/server-docs/calendar-v4/calendar-event-attendee/create)
- [Tasks API](https://open.larksuite.com/document/server-docs/task-v2/task/create)

## Permissions Required

Ensure your Lark app has these scopes:
- `calendar:calendar` — Read/write calendar ✅ (already enabled)
- `calendar:calendar:readonly` — Read calendar ✅ (already enabled)
- `task:task:write` — Write tasks ⚠️ (needs to be added for task creation)
- `task:task:read` — Read tasks
- `contact:user.employee_id:readonly` — Read user info ✅ (already enabled)

**To add permissions:**
1. Go to [Lark Open Platform](https://open.larksuite.com/app/cli_a9f52a4ed7b8ded4/auth)
2. Add scopes: `task:task:write`, `contact:contact:readonly` (for dynamic employee lookup)
3. Re-publish the app version

**Note:** Without `contact:contact:readonly`, the skill uses a static fallback employee list. Update `lib/employees.mjs` when team changes.

Overview

This skill lets you create, update, list, and delete calendar events and tasks in Lark (Feishu). It supports attendee and assignee management and includes an employee directory for automatic name-to-user_id resolution. Default timezone and calendar are preconfigured to simplify common workflows.

How this skill works

The skill calls Lark Calendar and Tasks APIs to perform CRUD operations. Names passed as attendees or assignees are resolved to Lark user_id values via a built-in directory; if API permission for contacts is available it will perform live resolution. Events use IANA timezones and a strict YYYY-MM-DD HH:MM:SS time format.

When to use it

Schedule meetings and automatically include core stakeholders
Create and assign tasks with due dates tied to team members
Update or cancel events and tasks programmatically
List events for a date range to build reports or reminders
Manage event attendees or task members in bulk

Best practices

Provide times in YYYY-MM-DD HH:MM:SS and specify timezone when different from the default
Prefer user_id values if you already have them to avoid name ambiguity
Ensure the Lark app has task and contact scopes for full functionality
Rely on the default calendar for team-wide scheduling or pass a calendar ID for personal calendars
Keep the local employee directory updated if contact scope is not granted

Example use cases

Create a team sync meeting with attendees resolved by name; Boss is auto-added
Schedule a client demo and include location, description, and timezone
Create a code-review task and assign multiple assignees with a deadline
List next 7 days of events to generate a daily agenda
Update an event time or remove a canceled attendee programmatically

FAQ

How are names mapped to Lark accounts?

The skill includes a static employee directory to resolve common names to user_id. If contact permissions are granted the skill will query Lark for live resolution.

What timezone and time format does the skill use?

Times use the format YYYY-MM-DD HH:MM:SS and IANA timezone identifiers (e.g., Asia/Singapore). A default timezone is applied if none is provided.