movie-night-calendar
Skill1 starsChanged 4 months agoMITView on GitHub
Use when a media catalogue app needs shared scheduling — a movie-night calendar, watch-party planner, a month grid of events with a host and a title attached, an upcoming-event badge, or a "who's picking this Friday" feature. Also use when calendar dates render one day off, when past events need distinguishing from upcoming, or when deciding who may delete an event.
In this repository58 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- api-test-suiteSkill
- ascii-artSkill
- caddy-reverse-proxySkill
- changelog-generatorSkill
- color-palette-generatorSkill
- cron-taskSkill
- csv-toolkitSkill
- discord-bot-buildSkill
- docker-umbrellaSkill
- dotfiles-manageSkill
- email-sendSkill
- env-config-managerSkill
- excalidraw-diagramSkill
- file-organizerSkill
- forgejo-self-hostSkill
- frontend-design-toolkitSkill
- generate-dockerfileSkill
- gif-searchSkill
- git-backupSkill
- github-actions-ciSkill
- hallmark-readmeSkill
- http-api-testerSkill
- invoice-generatorSkill
- json-formatterSkill
- log-analyzerSkill
- markdown-linterSkill
- markdown-to-pdfSkill
- markdown-to-slidesSkill
- mcp-server-buildSkill
- media-id-mappingSkill
- movie-catalogue-siteSkill
- ntfy-notifierSkill
- ocr-documentsSkill
- ollama-localSkill
- openapi-generatorSkill
- password-generatorSkill
- pdf-extractSkill
- portfolio-upkeepSkill
- qr-code-generatorSkill
- regex-testerSkill
- resume-builderSkill
- rss-monitorSkill
- searxng-self-hostSkill
- skill-publishSkill
- skill-registry-catalogSkill
- skills-portfolio-scaffoldSkill
- snippet-managerSkill
- sqlite-dashboardSkill
- streaming-provider-embedsSkill
- tailscale-deploySkill
- telegram-bot-buildSkill
- tmdb-metadataSkill
- uptime-kuma-self-hostSkill
- watchlist-syncSkill
- webhook-receiverSkill
- youtube-transcriptSkill
The file
We split this skill into the rules it gives an agent
4 rules. About 0 are common, 2 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 28
Do not use it for personal reminders with no shared audience (a notes field on the watchlist row is enough), or for release-date calendars …
- Very specific: line 148
Keep external_id nullable.
- Distinctive: line 194
A stale badge: after create/delete.
- Distinctive: line 203
Do recurrence (every Friday), RSVPs, attendance tracking, or voting on what to watch.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
movie-night-calendar
Overview
A shared calendar bolted onto a catalogue app: a month grid, one row per scheduled screening, each carrying a host profile, a real title picked from the metadata API, a date and optional time, a description, and an optional chat/voice link. Plus the small things that make it feel finished — a day panel, a past/upcoming distinction, and an "there's something coming up" badge in the nav.
It is a small feature with two disproportionate traps: JavaScript date parsing that silently shifts the day, and permissions on a table anyone can reach.
When to Use
- A catalogue app needs "movie night on Friday" scheduling shared between profiles.
- A watch-party planner, screening schedule, or club calendar over an existing title catalogue.
- Debugging a calendar that renders events one day early or late.
- Deciding who may create, edit, or delete an event.
Do not use it for personal reminders with no shared audience (a notes field on the watchlist row is enough), or for release-date calendars sourced from the metadata API — those are a /discover query with date filters, not stored events.
Workflow
- Add the table and its grants (see Schema). One migration, following the same exposed-view discipline as
watchlist-sync. - Load the month's events once, ordered by date, and render the grid from that array — not one request per cell.
- Build the month grid with the leading blanks maths (see Rendering the Month).
- Parse every date string with an explicit local-midnight suffix (see The Off-By-One-Day Trap). Do this before anything else, or you will chase a rendering bug that is a parsing bug.
- Add the day panel: click a cell, see that day's events, create from there with the date pre-filled.
- Attach a real title by searching the metadata API in the create form and storing the id and poster alongside the free-text title (see Attaching a Title).
- Decide and enforce who can delete (see Permissions), and say the rule in the UI.
- Add the upcoming badge as a bounded range query (see Upcoming Badge).
Schema
CREATE TABLE movie_nights (
id SERIAL PRIMARY KEY,
host_profile_id INTEGER NOT NULL REFERENCES profiles(id) ON DELETE CASCADE,
title TEXT NOT NULL, -- denormalised on purpose, see below
external_id INTEGER, -- TMDB id, nullable: not every night is a catalogued title
media_type TEXT CHECK (media_type IN ('movie','tv')),
poster_url TEXT DEFAULT '',
event_date DATE NOT NULL,
event_time TEXT DEFAULT '', -- free text; see the timezone note
description TEXT DEFAULT '',
chat_url TEXT DEFAULT '', -- Discord/Matrix/Jitsi invite
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);
CREATE INDEX movie_nights_date_idx ON movie_nights (event_date);
ALTER TABLE movie_nights ENABLE ROW LEVEL SECURITY;
NOTIFY pgrst, 'reload schema';Three deliberate choices:
titleandposter_urlare denormalised. An event must still read correctly when the catalogue row is gone, and a scheduled night is a historical record — it should not silently retitle itself if the metadata changes.event_dateis aDATE, not aTIMESTAMPTZ. A movie night is a calendar day, not an instant. Storing an instant forces a timezone decision on a value that doesn't have one and reintroduces the off-by-one below at the database layer.event_timeis free text. Storing"8pm-ish"honestly beats storing20:00:00+00and then rendering it in a timezone nobody agreed on. If you need a real instant, add a separate nullablestarts_at TIMESTAMPTZand say in the UI which timezone it is displayed in.
The Off-By-One-Day Trap
This is the bug this skill exists for.
new Date('2026-08-02') // parsed as UTC midnight → renders as Aug 1 west of UTC
new Date('2026-08-02T00:00:00') // parsed as LOCAL midnight → correctA bare YYYY-MM-DD string is parsed by the ECMAScript spec as UTC, while a date-time string without an offset is parsed as local. So every event silently shifts a day for anyone in a negative-offset timezone — and looks perfect on the developer's machine if they happen to be east of UTC.
Two rules, applied everywhere:
// Read: always append the time component.
const dateObj = new Date(dateStr + 'T00:00:00');
// Write: never use toISOString().slice(0,10) — that converts to UTC first
// and shifts the day back for anyone in a negative offset.
function fmtDate(d) {
const y = d.getFullYear();
const m = String(d.getMonth() + 1).padStart(2, '0');
const day = String(d.getDate()).padStart(2, '0');
return `${y}-${m}-${day}`;
}Compare against a normalised today, or every event dated today counts as past from 00:00:01 onward:
const today = new Date();
today.setHours(0, 0, 0, 0);
const isPast = new Date(dateStr + 'T00:00:00') < today;Rendering the Month
Fetch once, filter in memory:
const events = await api('/movie_nights?order=event_date.asc');Then the grid maths, which is three lines and easy to get subtly wrong:
const firstDay = new Date(year, month, 1).getDay(); // 0=Sun leading blanks
const daysInMonth = new Date(year, month + 1, 0).getDate(); // day 0 of next month = last of thisnew Date(y, m + 1, 0) is the idiomatic "days in month" and handles leap years for free. Emit firstDay empty cells before day 1, then one cell per day carrying:
- the day number,
- up to ~3 event rows (title plus a dot in the host's avatar colour), then a
+N moreline, todayandpastclasses,- a
data-dateattribute and a click handler opening the day panel.
Cap the events shown per cell. A day with nine events must not stretch the row and break the grid.
Escape every interpolated string. These are user-authored titles and descriptions going into innerHTML. The one-liner that actually works:
function escapeHtml(str) {
const div = document.createElement('div');
div.textContent = str;
return div.innerHTML;
}And render chat_url links with target="_blank" rel="noopener" — a user-supplied URL opened without noopener hands the opened page a reference to your window.
Attaching a Title
The create form searches the metadata API (see tmdb-metadata) and stores the chosen result's id, display title, and poster path together. Store all three:
- the id so the event can deep-link into your own title page,
- the title so the event reads correctly without a lookup,
- the poster so the grid and day panel render without a metadata request per event.
Keep external_id nullable. Not every movie night is a catalogued title — "board games" or "whatever we feel like" is a legitimate entry, and a NOT NULL id turns that into a lie or a blocked flow.
Pre-fill the date from whichever day cell was clicked, and default it to today when the panel was opened without one.
Permissions
A generated REST layer over Postgres gives anon whatever you grant, so decide this explicitly rather than inheriting it:
- Host may delete their own event. Compare
event.host_profile_idagainst the active profile. - An admin/editor may delete any. Whatever your app's edit gate is.
- Nobody else sees a delete button.
Be honest that this is a UI-level gate if anon holds a broad DELETE grant — anyone reaching the API directly can delete anything. That's a legitimate design for a self-hosted site behind a single shared front door (see watchlist-sync), but the README has to say so. If you want it enforced, the delete has to move behind a SECURITY DEFINER function that checks the caller, or behind real RLS with a JWT.
Past events are worth treating differently: hide "create" and edit affordances on a past date, but keep delete available for tidy-up. A calendar you cannot clean up fills with dead weeks.
Upcoming Badge
A bounded range query, not a full table scan on every page load:
const today = new Date(); today.setHours(0, 0, 0, 0);
const week = new Date(today.getTime() + 7 * 24 * 60 * 60 * 1000);
const rows = await api(`/movie_nights?event_date=gte.${fmtDate(today)}&event_date=lte.${fmtDate(week)}`);
badge.hidden = !(rows && rows.length);Refresh it after any create or delete, or the badge disagrees with the calendar until the next reload.
Failure must hide the badge, not break the nav — wrap it and swallow.
Empty States
- A month with no events says so in words ("No movie nights this month" — plus "create one from any day" only when the viewer can actually create). Never a blank grid area.
- A day panel with no events says "No movie nights planned", not an empty list.
- A failed load is distinct from an empty month. Same three-state rule as everywhere else: haven't asked, asked and empty, asked and failed.
Common Pitfalls
new Date('2026-08-02'). UTC-parsed; shifts a day west of UTC. The single most likely bug in this feature.toISOString().slice(0,10)to write a date. Same bug, other direction.- Comparing against an unnormalised
new Date(). Today's events read as past all afternoon. getMonth()off-by-one. It is 0-indexed;getDate()is not.- Unbounded events per cell. One busy day breaks the grid.
- Unescaped titles/descriptions in
innerHTML. User-authored strings. target="_blank"withoutrel="noopener"on a user-supplied chat URL.- A stale badge after create/delete.
NOT NULLon the title id. Blocks legitimate non-catalogue nights.- Storing a time as a UTC timestamp and rendering it without saying which timezone.
Limitations
This skill does not:
- Send invitations, reminders, emails, or push notifications. It stores a link; delivery is a separate system.
- Do recurrence (every Friday), RSVPs, attendance tracking, or voting on what to watch. Each is a real feature with its own schema; this is a single-row event.
- Export to iCal/Google Calendar.
event_date+event_timeas stored is not a precise enough instant for an.icswithout thestarts_ataddition it names. - Sync playback between viewers. A watch-party with synchronised players is a different problem entirely, and the embed hosts in
streaming-provider-embedspublish no seek command you can rely on. - Enforce permissions server-side by itself. It describes the UI gate honestly and names the two ways to make it real.
- Handle timezones for a distributed group. It deliberately stores a calendar day and free-text time rather than pretending to.
Verification Checklist
- An event created for today renders on today's cell with the machine's timezone set to something west of UTC (this is the test that catches the parsing bug)
- Month navigation across a year boundary and into February of a leap year both render the right number of days
- A day with more than three events shows
+N moreand does not stretch the row - A title containing
<script>renders as text - The delete button appears only for the host and the editor, and the rule is stated in the UI
- Creating and deleting an event both update the upcoming badge without a reload
- An empty month and a failed load render differently
- A past date offers delete but not create
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

