Crab fit

Crab Fit

Create and analyze public Crab Fit scheduling polls with the bundled CLI. Require Python 3.11 or later. Do not require API credentials.

Protect people and their data

• Treat every poll link as public to anyone who possesses it.
• Keep titles neutral. Do not put confidential project names, health details, customer data, or other sensitive information in a title.
• Tell the user that the link can be shared with participants and is not access-controlled.
• Note when relevant that Crab Fit deletes events after three months of inactivity.
• Do not submit or change a participant's availability. Do not impersonate a participant or handle participant passwords.
• Do not send invitations or book calendars. Draft short invitation copy when useful, then let the user or a separate authorized tool send or schedule it.

Create a poll

1. Resolve the event title, candidate dates or exact start times, and IANA timezone.
2. Treat a fully specified request to create a poll as authorization to create it. Do not ask for a second confirmation.
3. Ask one targeted question only when dates, times, or timezone remain materially ambiguous. Infer an unambiguous IANA timezone such as Asia/Singapore from clear user context. Resolve relative dates to absolute dates and state them in the result.
4. Derive a short, neutral title from context when the user did not provide one.
5. Run from this skill directory:

python3 scripts/crab_fit.py create \
  --name "Project sync" \
  --timezone Asia/Singapore \
  --window 2026-07-30T09:00/2026-07-30T11:00 \
  --window 2026-07-31T14:00/2026-07-31T16:00 \
  --interval-minutes 30

Use repeated --slot values instead of --window for exact candidate start times:

python3 scripts/crab_fit.py create \
  --name "Planning call" \
  --timezone Europe/London \
  --slot 2026-08-04T10:00 \
  --slot 2026-08-04T15:30

Do not mix --window and --slot. Treat window ends as exclusive. Use --dry-run when the user asks to preview the interpretation without creating a poll. Use --json when another program or agent needs structured output.

Never automatically retry creation. A timed-out or disconnected POST may have succeeded, and the API has no idempotency key. If the CLI reports an uncertain creation result, explain that retrying could create a duplicate and ask the user before trying again.

After success, return:

• The poll title and absolute candidate dates and times in the requested timezone.
• The shareable https://crab.fit/<event-id> link.
• A brief reminder that anyone with the link can access the poll.
• Optional invitation copy, clearly presented as a draft rather than sent.

Summarize results

Accept either an event ID or a Crab Fit event URL:

python3 scripts/crab_fit.py results "https://crab.fit/project-sync-123456" --top 5

Rank contiguous windows when the user specifies a meeting duration:

python3 scripts/crab_fit.py results project-sync-123456 \
  --duration-minutes 60 \
  --top 5

Use --interval-minutes only to override the event grid when required for contiguous analysis. The CLI otherwise infers the smallest positive gap between candidate times. A one-slot poll requires an explicit interval for duration analysis. Require the duration to be an exact multiple of the interval. Use --json for structured output.

Summarize the response count, highest-coverage candidate times, ties, and the names of unavailable participants when the CLI provides them. Keep all displayed times in the event timezone and include the timezone label. For a requested duration, describe only windows in which each counted participant selected every required grid cell. Do not claim consensus when one or more participants are unavailable.

Handle failures

• Correct invalid input locally. Require intervals to be positive multiples of 15 minutes.
• Supply local datetimes without a UTC offset. Use --timezone as the single timezone source.
• Reject nonexistent or ambiguous daylight-saving local times instead of guessing. Ask the user to choose an explicit valid local time.
• Explain 404 as an unknown or expired poll, 422 as rejected input, and 429 as rate limiting.
• Allow the CLI's bounded retry behavior for read-only result requests. Do not add retries around creation.
• Use CRAB_FIT_API_BASE_URL and CRAB_FIT_WEB_BASE_URL only for a user-requested self-hosted instance or controlled testing.

Read references/api.md when debugging HTTP behavior, integrating the JSON output, or changing the client. Do not call participant mutation endpoints even though the upstream API exposes them.