shared-skills

Access macOS Messages and Contacts programmatically without Full Disk Access. Use when: (1) "Operation not permitted" error accessing ~/Library/Messages/chat.db or ~/Library/Application Support/AddressBook/, (2) Need to read iMessage history, contacts, or chat data from terminal/scripts, (3) Need to SAVE or update a contact (name, phone, email, Instagram/social handle, note), (4) CNContactStore/CNSaveRequest write fails with a CoreData 4097 XPC error, (5) Full Disk Access isn't granted or isn't desirable. Covers AppleScript automation permissions workaround, the read-vs-write permission split, and Beeper Desktop CLI as alternatives to direct database access.

Use compiled Swift binaries instead of AppleScript for macOS system integrations. Use when: (1) an AppleScript is slow (>2s) for Contacts, Calendar, Reminders, or other system data, (2) need to read/write macOS Contacts, Calendar, Reminders, Focus status, or Notifications programmatically, (3) osascript is timing out or iterating slowly, (4) building a new macOS system integration for an AI agent or CLI tool. Swift + native frameworks (CNContactStore, EventKit, UNUserNotificationCenter) are ~100x faster than AppleScript equivalents. Compile once with swiftc, call from Python/Node/Bash.

Use when asked to explain, describe, or write up a topic for a technically competent audience that lacks project-specific or insider context — onboarding a new teammate, an outside reviewer, external docs, or when the user says "explain to someone unfamiliar", "don't assume inside knowledge", or "assume no context".

Git commit best practices for Claude Code. Use when: (1) about to create a git commit, (2) user asks to commit changes, (3) bundling multiple changes together. Covers atomic commits, meaningful messages, what not to commit, and ensuring commit messages reflect all changes in the diff.

Stack Overflow terminal interface with Startpage, StackExchange API, Google, and DuckDuckGo backends. Use when: (1) need to look up a programming question on Stack Overflow, (2) searching StackExchange sites (unix, superuser, serverfault), (3) fetching SO answers programmatically from a script or agent context. Default engine: Startpage. Use --print for non-TTY/pipeable output.

X/Twitter CLI for reading timelines, searching tweets, checking engagement, streaming, and managing lists. Use when: (1) user asks about tweets, Twitter, or X, (2) checking mentions or engagement, (3) searching Twitter discussions, (4) streaming tweets by keyword, (5) looking up users or followers.

Update README and documentation files to match the current state of the codebase. Use when: (1) user asks to "update the readme", "sync docs", or "docs are stale", (2) after significant refactors or feature additions, (3) user asks "is the README accurate?", (4) CLAUDE.md instructions say to check docs after changes. Finds what changed since docs were last touched, then makes targeted correctness and completeness fixes. Does NOT rewrite for style — preserves the author's voice and structure.

Create agent-optimized CLI skill documentation. Use when: (1) "create a skill for <CLI>", (2) "document <CLI> for agents", (3) adopting a new CLI tool that needs an agent-friendly reference, (4) rewriting an existing CLI skill with better agent optimization. Runs a discover-analyze-generate-verify pipeline. Output: SKILL.md in ~/projects/shared-skills/skills/.

Svelte 5 best practices including runes ($state, $derived, $effect), dependency tracking patterns, ESLint configuration, and component patterns

TypeScript development best practices including type system, generics, utility types, configuration, and patterns for React, Node.js, and full-stack applications

Remove signs of AI-generated writing from text. Use when editing or reviewing text to make it sound more natural and human-written. Based on Wikipedia's comprehensive "Signs of AI writing" guide. Detects and fixes patterns including: inflated symbolism, promotional language, superficial -ing analyses, vague attributions, em dash overuse, rule of three, AI vocabulary words, negative parallelisms, and excessive conjunctive phrases.

Cross-platform messaging CLI for Beeper Desktop. Access iMessage, WhatsApp, Instagram, LinkedIn, Telegram, Signal, Discord, Slack, and more from the terminal. Use when the user asks about messages, wants to search conversations, check unread, or send messages.

Find real, user-impacting bugs across an entire codebase using a swarm of specialized agents. Use when: (1) user invokes /bug-basher or /bug-basher-5000, (2) user asks to "find bugs", "hunt for bugs", or "what's broken", (3) user wants a bug audit focused on UX impact. NOT for code reviews or style nits. Focuses exclusively on: crashes, data corruption, confusing UX, broken features, bad error messages, logical inconsistencies. Uses parallel agents that scale with codebase size (3-25 agents). Outputs BUGS_FOUND.md organized by severity with quick wins surfaced first. Agents perform root cause analysis for each bug.

Calculate project-specific token usage and costs from Claude Code session data. Use when: (1) user asks "how many tokens have I used?", (2) user wants to see project costs, (3) analyzing Claude Code usage patterns, (4) comparing usage across projects. Covers parsing ~/.claude session files, extracting token counts, and calculating estimated costs with prompt caching.

Perform a thorough, critical code review of an entire codebase. Use when: (1) user asks for a "code review", (2) user wants to find bugs or issues, (3) user asks "what's wrong with this code", (4) user wants security audit, (5) user asks about edge cases or best practices violations, (6) user asks to "find missed tasks" or "what slipped through the cracks". Covers security, bugs, edge cases, code quality, deprecated code, readability, best practices, and missed task detection. Outputs findings to a markdown file organized by severity.

Set up multi-agent parallel implementation for a project phase. Use when: (1) user has a PHASEx_TASKS.md with multiple epics and dependencies, (2) user wants to parallelize work across multiple Claude agents, (3) user asks to "set up orchestration" or "coordinate agents" for a phase. Analyzes dependencies, determines agent count, generates prompts and coordination docs.

Set up and run a Ralph Wiggum autonomous loop for Claude Code when the official plugin isn't available. Use when: (1) user asks about "Ralph Wiggum loop" or "Ralph loop", (2) need to apply many well-specified code changes autonomously, (3) want to run Claude Code in a bash loop with progress tracking and oscillation detection, (4) official ralph-wiggum plugin is not in the marketplace. Covers: manual bash loop setup, PROMPT.md design, PROGRESS.md tracker, completion signal gotchas, oscillation detection, permission configuration, and when NOT to use Ralph loops.

Two-phase research pattern: (1) quiz user to build structured selection criteria, (2) dispatch parallel agents across multiple models with intentionally varied context levels, then compile/rank/filter into a single report. Use when: (1) user asks to "find me a..." or "help me choose..." with multiple viable options, (2) group decisions with multiple constraints, (3) any scenario where breadth of search + structured evaluation both matter — travel planning, restaurant selection, apartment hunting, tech stack decisions, gear purchasing, event venue selection. Key insight: some agents get full criteria (targeted search) while others get minimal context (wider net, avoids confirmation bias). Different models surface different results.

Patterns and anti-patterns for orchestrating multi-agent teams on complex research and planning tasks. Use when: (1) dispatching 3+ agents for a complex task like calendar restructuring, trip planning, or multi-source research, (2) user explicitly asks for agent teams, (3) task requires gathering data from multiple sources and synthesizing into a plan. Covers: agent role design, iteration loops, scratchpad usage, re-dispatching idle agents, critique pass structure, cross-referencing between agents, and handling user corrections mid-task.

Comprehensive debugging guide for AI agents tackling confusing issues. Use when: (1) code hangs/freezes with no error, (2) behavior differs from expectations with no clear cause, (3) errors are misleading or don't point to root cause, (4) you've tried obvious fixes and they didn't work, (5) the issue only reproduces in certain conditions. Contains strategies for: silent hangs, misleading errors, data-dependent bugs, race conditions, and integration issues. Core principle: CREATE OBSERVABILITY before attempting fixes.

Review session transcripts to ensure ARCHITECTURE.md stays in sync with implementation decisions. Use when: (1) after completing a major feature/epic, (2) periodic architecture audits, (3) onboarding new contributors who need accurate docs, (4) before releases to ensure docs reflect reality. Spawns parallel agents that cross-reference transcript decisions against docs/ARCHITECTURE.md. Project-specific to Flow budget tracking app.

Fix invisible/broken rendering when streaming deduplicated results through SSE or WebSocket pipelines with async enrichment. Use when: (1) a counter/count shows items exist but UI renders nothing or fewer items than expected, (2) Svelte keyed {#each} or React key-based lists show blank despite array having items, (3) streaming pipeline uses async processing per item with a dedup Map/Set check before the await, (4) fire-and-forget async calls with Promise.then() lose results when parent stream closes. Root cause: dedup check happens before async gap, allowing concurrent calls for the same key to all pass, producing duplicate emissions. Secondary cause: onDone/stream-close fires before all async promises resolve, silently dropping late results.

Programmatically identify and manage resource-heavy browser tabs on macOS using ps, AppleScript, and forensic techniques. Use when user says: (1) "my browser is using a lot of CPU/memory", (2) "which tab is causing my Mac to run slow/hot", (3) "Edge/Chrome/Safari is hogging resources", (4) "find the runaway tab", (5) "there's a tab making my computer slow", (6) "close duplicate tabs", (7) "clean up my browser tabs". Covers process investigation, AppleScript tab enumeration, forensic identification (kill → observe → identify), and bulk tab operations.

Analyze Claude Code session transcripts to extract decisions, learnings, and state. Use when: (1) recovering interrupted sessions, (2) extracting what an agent did, (3) auditing decisions made during long-running tasks, (4) reconstructing agent state after context limit. Covers JSONL format, parsing commands, and parallel analysis patterns.

Claudeception is a continuous learning system that extracts reusable knowledge from work sessions. Triggers: (1) /claudeception command to review session learnings, (2) "save this as a skill" or "extract a skill from this", (3) "what did we learn?", (4) After any task involving non-obvious debugging, workarounds, or trial-and-error discovery. Creates new Claude Code skills when valuable, reusable knowledge is identified.

Manage Femi's Google Calendar schedule. Use when: (1) adjusting today's schedule (running late, skipping something, pushing blocks), (2) modifying recurring events (move climbing, change gym day), (3) adding one-off events, (4) checking what's on the calendar. Contains all verified addresses, color codes, commute data, and constraints.

Avoid fixing display/presentation problems by modifying stored data. Use when: (1) considering normalizing dates/timestamps to fix timezone display issues, (2) tempted to transform data at ingestion to solve UI formatting problems, (3) debugging where data "looks wrong" in the UI but the underlying data is correct, (4) fixing localization/formatting issues by changing what gets stored. Core principle: Display issues belong in the display layer, not the data layer.

Set up git worktrees correctly for Next.js projects with Prisma. Use when: (1) "Cannot find module '.prisma/client/default'" error in new worktree, (2) API routes return 500 errors in worktree but work in main repo, (3) Setting up parallel development branches for UI comparison. Covers npm install, prisma generate, and .env file copying.

Handle timezone issues with imported/subscribed Google Calendar ICS feeds when using the `gog` CLI tool. Use when: (1) work calendar events show meetings at absurd times like 11 PM or 4 AM, (2) calendar has an `@import.calendar.google.com` ID suffix, (3) work meeting times don't make sense as local times but make perfect sense as UTC, (4) using `gog calendar events` on any non-primary calendar. Root cause: imported ICS feeds (from Microsoft Outlook, Exchange, etc.) store times in UTC. The `gog` tool returns these raw UTC times without converting to the user's local timezone. Primary/native Google Calendar events DO include timezone offsets (e.g., `-08:00` for PST).

Scan messages for action items, unanswered questions, and unfulfilled plans. Use when: (1) user asks to check messages, review inbox, or find things they forgot to respond to, (2) morning briefing or daily check-in, (3) user says "what am I forgetting?" or "who do I need to get back to?", (4) user wants to find promises they made but didn't fulfill. Scans Beeper messages across all platforms, resolves contacts, prioritizes by recency/frequency, outputs to both Notion and Markdown.

Fix "Module not found: Can't resolve 'dns'" (or 'fs', 'net', 'tls') errors in Next.js with Prisma. Use when: (1) Build fails with "Can't resolve 'dns'" from pg/connection-parameters.js, (2) Error trace shows "[Client Component Browser]" importing server modules, (3) Using Prisma with @prisma/adapter-pg and getting Node.js module errors, (4) Barrel exports cause unexpected server code in client bundles. Covers: barrel export patterns, Prisma enum imports, direct component imports, serverExternalPackages.

Fix "the chunking context does not support external modules (request: node:module)" error in Next.js with Prisma. Use when: (1) Next.js build fails with node:module error, (2) Turbopack shows "chunking context does not support external modules", (3) Client component imports types from @/generated/prisma/client or @prisma/client/runtime/client, (4) Error trace shows "Client Component Browser" importing Prisma types. Root cause: Prisma client includes Node.js-specific code that can't be bundled for the browser.

Prevent accidental deletion of Notion child pages when updating parent page content. Use when: (1) using replace_content command on a Notion page that has subpages, (2) updating page content where child pages exist as blocks, (3) seeing "deleted" status on pages after parent content update. In Notion, child pages exist as blocks within parent content - replacing all content removes the child page blocks and orphans or deletes the child pages.

Fix Notion MCP URL validation errors when updating page content with links. Use when: (1) "Invalid agent URL - Failed to parse as URL" error with {{URL}} syntax, (2) need to link to existing page without moving it, (3) replacing plain text with page references. Covers difference between <page> vs <mention-page> tags and read vs write URL formats.

Match David's specific Notion formatting preferences when creating content. Use when: (1) creating new pages in David's Notion workspace, (2) user says content is "over-formatted" or doesn't match their style, (3) starting any Notion content creation task. This skill contains David's actual preferences learned from 30+ pages across his workspace - tables, checkboxes, toggles, bold headers, casual tone, databases for tracking.

Organize Notion todo list database with categories and deadlines based on bandwidth constraints. Use when: (1) user asks to organize/categorize/schedule their todo list, plan their week, reschedule tasks, or says 'I missed some deadlines' or 'what should I work on', (2) multiple tasks need deadline assignment with load balancing, (3) tasks need category assignment based on content analysis, (4) tasks are past due and need rescheduling. Covers strategy selection (MCP vs API vs parallel subagents), deadline cascading when priorities change, past-due task triage, and bandwidth-aware scheduling.

Fix Prisma 7 "engine type client requires adapter" error after upgrading from Prisma 6. Use when: (1) Error "Using engine type 'client' requires either 'adapter' or 'accelerateUrl' to be provided to PrismaClient constructor", (2) PrismaClientConstructorValidationError after Prisma 7 upgrade, (3) Setting engineType = "library" doesn't fix the error, (4) Next.js build fails after upgrading Prisma to v7.x.

Safely handle Prisma migration drift on existing databases without data loss. Use when: (1) "prisma migrate dev" shows "Drift detected: Your database schema is not in sync", (2) Prisma asks "We need to reset the schema. All data will be lost. Do you want to continue?", (3) Database was created via Supabase, direct SQL, or another ORM before adopting Prisma, (4) Adding schema changes to a production database that wasn't initialized with Prisma migrations. Covers baselining existing databases and applying incremental changes safely.

REQUIRED before ANY Notion operation. Determines whether to use MCP tools or direct API. Use when: (1) about to use ANY Notion MCP tool (notion-search, notion-fetch, notion-update-page, notion-create-pages), (2) user asks to query, update, create, or organize Notion content, (3) need to list all items in a database (MCP CANNOT do this - only API can), (4) bulk updating 5+ pages (API is faster), (5) updating page icons/covers (only API supports this), (6) MCP search returns incomplete results, (7) user mentions "Notion" in any capacity. Covers: MCP vs API decision matrix, when MCP fails, property update formats, content editing approaches, hybrid workflow pattern, bulk operation scripts, API setup. CRITICAL: MCP cannot list database items - this is a common failure mode. Always check this skill first.

Transcribe audio files (OGG, MP3, WAV, M4A, FLAC, etc.) using whisper-cpp locally with Metal GPU. Use when: (1) user provides an audio file to transcribe, (2) user asks "what does this audio say?", (3) user drops a voice memo or recording.