calendar (v4)

CRITICAL — MUST use the Read tool to read
../lark-shared/SKILL.md
before starting, which contains authentication and permission handling CRITICAL — Before executing any Shortcuts, be sure to use the Read tool to read their corresponding documentation. Do not call commands blindly directly.

Core Scenarios

The calendar skill includes the following core scenarios:

1. Schedule Booking

This is the most core scenario of the calendar skill, focusing on enabling users to book schedules at low cost.

💡 Core Principle: Act as an intelligent assistant, provide decision support, not a form filler or make decisions on behalf of users.

Time and Date Inference Specifications: To ensure accuracy, strictly follow the following rules when inferring time:

Definition of the week: Monday is the first day of the week, Sunday is the last day of the week. When calculating relative dates like "next Monday", be sure to base it on the current actual date and week benchmark to avoid miscalculations.
Range of a day: When the user refers to a general day such as "tomorrow" or "today", the time range should default to cover the entire day. Do not reduce the query scope on your own, as this may miss evening arrangements.
Historical Time Constraint: Cannot book time that has completely passed. The only exception is a schedule that "crosses the current time", i.e., the start time of the schedule is in the past but the end time is in the future.

Workflow for Schedule Booking:

Intelligent Inference of Default Values
- Default values exist for title, attendees, and duration, so there is no need to frequently confirm with the user.
- Attendees: If no other people are clearly specified, the default attendees are only the user themselves. When searching for specific attendees (people, groups, meeting rooms) yields multiple results that cannot be uniquely determined, you must ask the user to select and confirm, and record this preference as long-term memory for automatic recognition in subsequent interactions.
- Meeting Rooms: Currently, active booking of meeting rooms is not supported unless the corresponding meeting room ID (with omm_ prefix) already exists in the current context and needs to be added to the schedule.
- Title: Automatically generated based on the conversation context (e.g., "Communication Alignment" or "Requirement Discussion"), defaults to "Meeting" if inference is not possible.
- Duration: Dynamically inferred based on meeting type and context (e.g., "Review/Report" is inferred as 60 minutes, etc.), defaults to 30 minutes if inference is not possible.
Time Suggestions and Decision Support (Core Experience)
- With a specific time point (e.g., "10 AM tomorrow"): Call the relevant tool (such as
```
lark-cli calendar +freebusy
```
  lark-calendar-freebusy) to first check the free/busy status of attendees during that period (Note: If an attendee's RSVP status for an existing schedule is "declined", that time period is considered free). If there are no conflicts, proceed to the next step of confirmation and creation; if there are conflicts, inform the user of the conflict and ask whether to continue creating or reselect a time.
- With a time interval (e.g., "tomorrow", "afternoon", "this week"): Call the relevant tool (such as
```
lark-cli calendar +suggestion
```
  lark-calendar-suggestion) to obtain multiple time recommendation options for all attendees within the interval for the user to choose from. Only after the user confirms the option can you execute the schedule creation operation; once the user selects a recommended option, there is no need to check free/busy information again.
- No time information provided: Default to inferring a reasonable interval (e.g., "today" or "the next two days") and also obtain multiple time recommendation options for the user to quickly select from.
- Life-related needs (e.g., fitness, swimming, walking, meal appointments, milk tea, etc. Note: "coffee appointment" is considered a work scenario): Do not call the
```
suggestion
```
  tool. You should infer appropriate non-working hours on your own for the user to confirm. If inference is not possible, try to actively ask the user, and form a memory after receiving feedback for direct application in subsequent interactions.
- Ambiguity Resolution and Long-Term Memory Construction (Aha Moment): For the user's exclusive time expression habits (e.g., "after work starts", "before work ends") or ambiguous time scenarios (e.g., 12-hour format without specifying AM/PM), do not make subjective assumptions. You should clarify the true intention through active confirmation, and record such personalized definitions as long-term preferences to promote the continuous evolution of the system's cognitive ability, ultimately achieving an intelligent experience of "understanding next time".

Non-Blocking Execution

After the user confirms the specific time option, execute

lark-cli calendar +create --summary "..." --start "..." --end "..." --attendee-ids ...

Friendly Feedback
- Report results: Return the summary information of the successfully created schedule

Core Concepts

Calendar: The container for schedules. Each user has a primary calendar, and can also create or subscribe to shared calendars.
Event: A single event entry in the calendar, containing attributes such as start/end time, location, title, attendees, etc. Supports one-time and recurring schedules, following the RFC5545 iCalendar international standard.
All-day Event: A schedule that only occupies a date without specific start/end times, and the end date is included in the schedule time.
Instance: A specific time instance of a schedule, essentially an expansion of the schedule. Regular events and exception events correspond to 1 Instance, while recurring events correspond to N Instances. When querying by time period, recurring schedules can be expanded into independent instances through the instance view for accurate display and management on the timeline.
Recurrence Rule (Rrule): Defines the recurrence rule for recurring schedules, such as
```
FREQ=DAILY;UNTIL=20230307T155959Z;INTERVAL=14
```
which means repeating every 14 days.
Exception: A schedule in a recurring series that is inconsistent with the original recurring schedule.
Attendee: A participant in the schedule, which can be a user, group, meeting room resource, external email address, etc. Each attendee has an independent RSVP status.
RSVP Status: The response status of an attendee to a schedule invitation (Accept/Decline/Tentative).
FreeBusy: Query the user's free/busy status during a specified time period, used for meeting time coordination.

Resource Relationships

Calendar (日历)
└── Event (日程)
    ├── Attendee (参会人)
    └── Reminder (提醒)

Shortcuts (Recommended for Priority Use)

Shortcuts are advanced encapsulations of common operations (

lark-cli calendar +<verb> [flags]

). Operations with Shortcuts should be used first.

Shortcut	Description
`+agenda`	View schedule arrangements (default to today)
`+create`	Create a schedule and invite attendees (ISO 8601 time)
`+freebusy`	Check the free/busy status of the user's primary calendar and RSVP status
`+suggestion`	Provide multiple time recommendation solutions for appointment schedule requests with undetermined times

+suggestion Usage

Before calling

+suggestion

, be sure to read the usage instructions in lark-calendar-suggestion. Do not call the command directly.

bash

lark-cli calendar +suggestion --start "2026-03-10T00:00:00+08:00" --end "2026-03-10T11:00:00+08:00" --attendee-ids "ou_xxx,oc_yyy" --duration-minutes 30 # 为用户ou_xxx和群组oc_yyy里的成员推荐空闲时段

API Resources

bash

lark-cli schema calendar.<resource>.<method>   # Must check the parameter structure before calling the API
lark-cli calendar <resource> <method> [flags] # Call the API

Important: When using the native API, must first run
schema
to check the
--data
/
--params
parameter structure. Do not guess the field format.

calendars

```
create
```
— Create a shared calendar
```
delete
```
— Delete a shared calendar
```
get
```
— Query calendar information
```
list
```
— Query calendar list
```
patch
```
— Update calendar information
```
primary
```
— Query the user's primary calendar
```
search
```
— Search calendars

event.attendees

```
batch_delete
```
— Delete event attendees
```
create
```
— Add event attendees
```
list
```
— Get event attendee list

events

```
create
```
— Create an event
```
delete
```
— Delete an event
```
get
```
— Get an event
```
instance_view
```
— Query event view
```
patch
```
— Update an event
```
search
```
— Search events

freebusys

```
list
```
— Query free/busy information of primary calendar events

Permission Table

Method	Required scope
`calendars.create`	`calendar:calendar:create`
`calendars.delete`	`calendar:calendar:delete`
`calendars.get`	`calendar:calendar:read`
`calendars.list`	`calendar:calendar:read`
`calendars.patch`	`calendar:calendar:update`
`calendars.primary`	`calendar:calendar:read`
`calendars.search`	`calendar:calendar:read`
`event.attendees.batch_delete`	`calendar:calendar.event:update`
`event.attendees.create`	`calendar:calendar.event:update`
`event.attendees.list`	`calendar:calendar.event:read`
`events.create`	`calendar:calendar.event:create`
`events.delete`	`calendar:calendar.event:delete`
`events.get`	`calendar:calendar.event:read`
`events.instance_view`	`calendar:calendar.event:read`
`events.patch`	`calendar:calendar.event:update`
`events.search`	`calendar:calendar.event:read`
`freebusys.list`	`calendar:calendar.free_busy:read`

Note (Mandatory):

When converting between date (time) strings and timestamps, be sure to use external tools such as system commands or script code for processing to ensure absolute accuracy. Violations will lead to serious logical errors!

lark-calendar

NPX Install

Tags

SKILL.md Content (Chinese)