Algorithmic philosophies are computational aesthetic movements that are then expressed through code. Output .md files (philosophy), .html files (interactive viewer), and .js files (generative algorithms).

This happens in two steps:

1. Algorithmic Philosophy Creation (.md file)
2. Express by creating p5.js generative art (.html + .js files)

First, undertake this task:

ALGORITHMIC PHILOSOPHY CREATION

To begin, create an ALGORITHMIC PHILOSOPHY (not static images or templates) that will be interpreted through:

• Computational processes, emergent behavior, mathematical beauty
• Seeded randomness, noise fields, organic systems
• Particles, flows, fields, forces
• Parametric variation and controlled chaos

THE CRITICAL UNDERSTANDING

• What is received: Some subtle input or instructions by the user to take into account, but use as a foundation; it should not constrain creative freedom.
• What is created: An algorithmic philosophy/generative aesthetic movement.
• What happens next: The same version receives the philosophy and EXPRESSES IT IN CODE - creating p5.js sketches that are 90% algorithmic generation, 10% essential parameters.

Consider this approach:

• Write a manifesto for a generative art movement
• The next phase involves writing the algorithm that brings it to life

The philosophy must emphasize: Algorithmic expression. Emergent behavior. Computational beauty. Seeded variation.

HOW TO GENERATE AN ALGORITHMIC PHILOSOPHY

Name the movement (1-2 words): "Organic Turbulence" / "Quantum Harmonics" / "Emergent Stillness"

Articulate the philosophy (4-6 paragraphs - concise but complete):

To capture the ALGORITHMIC essence, express how this philosophy manifests through:

• Computational processes and mathematical relationships?
• Noise functions and randomness patterns?
• Particle behaviors and field dynamics?
• Temporal evolution and system states?
• Parametric variation and emergent complexity?

CRITICAL GUIDELINES:

• Avoid redundancy: Each algorithmic aspect should be mentioned once. Avoid repeating concepts about noise theory, particle dynamics, or mathematical principles unless adding new depth.
• Emphasize craftsmanship REPEATEDLY: The philosophy MUST stress multiple times that the final algorithm should appear as though it took countless hours to develop, was refined with care, and comes from someone at the absolute top of their field. This framing is essential - repeat phrases like "meticulously crafted algorithm," "the product of deep computational expertise," "painstaking optimization," "master-level implementation."
• Leave creative space: Be specific about the algorithmic direction, but concise enough that the next Claude has room to make interpretive implementation choices at an extremely high level of craftsmanship.

The philosophy must guide the next version to express ideas ALGORITHMICALLY, not through static images. Beauty lives in the process, not the final frame.

PHILOSOPHY EXAMPLES

"Organic Turbulence" Philosophy: Chaos constrained by natural law, order emerging from disorder. Algorithmic expression: Flow fields driven by layered Perlin noise. Thousands of particles following vector forces, their trails accumulating into organic density maps. Multiple noise octaves create turbulent regions and calm zones. Color emerges from velocity and density - fast particles burn bright, slow ones fade to shadow. The algorithm runs until equilibrium - a meticulously tuned balance where every parameter was refined through countless iterations by a master of computational aesthetics.

"Quantum Harmonics" Philosophy: Discrete entities exhibiting wave-like interference patterns. Algorithmic expression: Particles initialized on a grid, each carrying a phase value that evolves through sine waves. When particles are near, their phases interfere - constructive interference creates bright nodes, destructive creates voids. Simple harmonic motion generates complex emergent mandalas. The result of painstaking frequency calibration where every ratio was carefully chosen to produce resonant beauty.

"Recursive Whispers" Philosophy: Self-similarity across scales, infinite depth in finite space. Algorithmic expression: Branching structures that subdivide recursively. Each branch slightly randomized but constrained by golden ratios. L-systems or recursive subdivision generate tree-like forms that feel both mathematical and organic. Subtle noise perturbations break perfect symmetry. Line weights diminish with each recursion level. Every branching angle the product of deep mathematical exploration.

"Field Dynamics" Philosophy: Invisible forces made visible through their effects on matter. Algorithmic expression: Vector fields constructed from mathematical functions or noise. Particles born at edges, flowing along field lines, dying when they reach equilibrium or boundaries. Multiple fields can attract, repel, or rotate particles. The visualization shows only the traces - ghost-like evidence of invisible forces. A computational dance meticulously choreographed through force balance.

"Stochastic Crystallization" Philosophy: Random processes crystallizing into ordered structures. Algorithmic expression: Randomized circle packing or Voronoi tessellation. Start with random points, let them evolve through relaxation algorithms. Cells push apart until equilibrium. Color based on cell size, neighbor count, or distance from center. The organic tiling that emerges feels both random and inevitable. Every seed produces unique crystalline beauty - the mark of a master-level generative algorithm.

These are condensed examples. The actual algorithmic philosophy should be 4-6 substantial paragraphs.

ESSENTIAL PRINCIPLES

• ALGORITHMIC PHILOSOPHY: Creating a computational worldview to be expressed through code
• PROCESS OVER PRODUCT: Always emphasize that beauty emerges from the algorithm's execution - each run is unique
• PARAMETRIC EXPRESSION: Ideas communicate through mathematical relationships, forces, behaviors - not static composition
• ARTISTIC FREEDOM: The next Claude interprets the philosophy algorithmically - provide creative implementation room
• PURE GENERATIVE ART: This is about making LIVING ALGORITHMS, not static images with randomness
• EXPERT CRAFTSMANSHIP: Repeatedly emphasize the final algorithm must feel meticulously crafted, refined through countless iterations, the product of deep expertise by someone at the absolute top of their field in computational aesthetics

The algorithmic philosophy should be 4-6 paragraphs long. Fill it with poetic computational philosophy that brings together the intended vision. Avoid repeating the same points. Output this algorithmic philosophy as a .md file.

DEDUCING THE CONCEPTUAL SEED

CRITICAL STEP: Before implementing the algorithm, identify the subtle conceptual thread from the original request.

THE ESSENTIAL PRINCIPLE: The concept is a subtle, niche reference embedded within the algorithm itself - not always literal, always sophisticated. Someone familiar with the subject should feel it intuitively, while others simply experience a masterful generative composition. The algorithmic philosophy provides the computational language. The deduced concept provides the soul - the quiet conceptual DNA woven invisibly into parameters, behaviors, and emergence patterns.

This is VERY IMPORTANT: The reference must be so refined that it enhances the work's depth without announcing itself. Think like a jazz musician quoting another song through algorithmic harmony - only those who know will catch it, but everyone appreciates the generative beauty.

P5.JS IMPLEMENTATION

With the philosophy AND conceptual framework established, express it through code. Pause to gather thoughts before proceeding. Use only the algorithmic philosophy created and the instructions below.

⚠️ STEP 0: READ THE TEMPLATE FIRST ⚠️

CRITICAL: BEFORE writing any HTML:

1. Read templates/viewer.html using the Read tool
2. Study the exact structure, styling, and Anthropic branding
3. Use that file as the LITERAL STARTING POINT - not just inspiration
4. Keep all FIXED sections exactly as shown (header, sidebar structure, Anthropic colors/fonts, seed controls, action buttons)
5. Replace only the VARIABLE sections marked in the file's comments (algorithm, parameters, UI controls for parameters)

Avoid:

• ❌ Creating HTML from scratch
• ❌ Inventing custom styling or color schemes
• ❌ Using system fonts or dark themes
• ❌ Changing the sidebar structure

Follow these practices:

• ✅ Copy the template's exact HTML structure
• ✅ Keep Anthropic branding (Poppins/Lora fonts, light colors, gradient backdrop)
• ✅ Maintain the sidebar layout (Seed → Parameters → Colors? → Actions)
• ✅ Replace only the p5.js algorithm and parameter controls

The template is the foundation. Build on it, don't rebuild it.

To create gallery-quality computational art that lives and breathes, use the algorithmic philosophy as the foundation.

TECHNICAL REQUIREMENTS

Seeded Randomness (Art Blocks Pattern):

// ALWAYS use a seed for reproducibility
let seed = 12345; // or hash from user input
randomSeed(seed);
noiseSeed(seed);

Parameter Structure - FOLLOW THE PHILOSOPHY:

To establish parameters that emerge naturally from the algorithmic philosophy, consider: "What qualities of this system can be adjusted?"

let params = {
  seed: 12345,  // Always include seed for reproducibility
  // colors
  // Add parameters that control YOUR algorithm:
  // - Quantities (how many?)
  // - Scales (how big? how fast?)
  // - Probabilities (how likely?)
  // - Ratios (what proportions?)
  // - Angles (what direction?)
  // - Thresholds (when does behavior change?)
};

To design effective parameters, focus on the properties the system needs to be tunable rather than thinking in terms of "pattern types".

Core Algorithm - EXPRESS THE PHILOSOPHY:

CRITICAL: The algorithmic philosophy should dictate what to build.

To express the philosophy through code, avoid thinking "which pattern should I use?" and instead think "how to express this philosophy through code?"

If the philosophy is about organic emergence, consider using:

• Elements that accumulate or grow over time
• Random processes constrained by natural rules
• Feedback loops and interactions

If the philosophy is about mathematical beauty, consider using:

• Geometric relationships and ratios
• Trigonometric functions and harmonics
• Precise calculations creating unexpected patterns

If the philosophy is about controlled chaos, consider using:

• Random variation within strict boundaries
• Bifurcation and phase transitions
• Order emerging from disorder

The algorithm flows from the philosophy, not from a menu of options.

To guide the implementation, let the conceptual essence inform creative and original choices. Build something that expresses the vision for this particular request.

Canvas Setup: Standard p5.js structure:

function setup() {
  createCanvas(1200, 1200);
  // Initialize your system
}

function draw() {
  // Your generative algorithm
  // Can be static (noLoop) or animated
}

CRAFTSMANSHIP REQUIREMENTS

CRITICAL: To achieve mastery, create algorithms that feel like they emerged through countless iterations by a master generative artist. Tune every parameter carefully. Ensure every pattern emerges with purpose. This is NOT random noise - this is CONTROLLED CHAOS refined through deep expertise.

• Balance: Complexity without visual noise, order without rigidity
• Color Harmony: Thoughtful palettes, not random RGB values
• Composition: Even in randomness, maintain visual hierarchy and flow
• Performance: Smooth execution, optimized for real-time if animated
• Reproducibility: Same seed ALWAYS produces identical output

OUTPUT FORMAT

Output:

1. Algorithmic Philosophy - As markdown or text explaining the generative aesthetic
2. Single HTML Artifact - Self-contained interactive generative art built from templates/viewer.html (see STEP 0 and next section)

The HTML artifact contains everything: p5.js (from CDN), the algorithm, parameter controls, and UI - all in one file that works immediately in claude.ai artifacts or any browser. Start from the template file, not from scratch.

INTERACTIVE ARTIFACT CREATION

REMINDER: templates/viewer.html should have already been read (see STEP 0). Use that file as the starting point.

To allow exploration of the generative art, create a single, self-contained HTML artifact. Ensure this artifact works immediately in claude.ai or any browser - no setup required. Embed everything inline.

CRITICAL: WHAT'S FIXED VS VARIABLE

The templates/viewer.html file is the foundation. It contains the exact structure and styling needed.

FIXED (always include exactly as shown):

• Layout structure (header, sidebar, main canvas area)
• Anthropic branding (UI colors, fonts, gradients)
• Seed section in sidebar:
  • Seed display
  • Previous/Next buttons
  • Random button
  • Jump to seed input + Go button
• Actions section in sidebar:
  • Regenerate button
  • Reset button

VARIABLE (customize for each artwork):

• The entire p5.js algorithm (setup/draw/classes)
• The parameters object (define what the art needs)
• The Parameters section in sidebar:
  • Number of parameter controls
  • Parameter names
  • Min/max/step values for sliders
  • Control types (sliders, inputs, etc.)
• Colors section (optional):
  • Some art needs color pickers
  • Some art might use fixed colors
  • Some art might be monochrome (no color controls needed)
  • Decide based on the art's needs

Every artwork should have unique parameters and algorithm! The fixed parts provide consistent UX - everything else expresses the unique vision.

REQUIRED FEATURES

1. Parameter Controls

• Sliders for numeric parameters (particle count, noise scale, speed, etc.)
• Color pickers for palette colors
• Real-time updates when parameters change
• Reset button to restore defaults

2. Seed Navigation

• Display current seed number
• "Previous" and "Next" buttons to cycle through seeds
• "Random" button for random seed
• Input field to jump to specific seed
• Generate 100 variations when requested (seeds 1-100)

3. Single Artifact Structure

<!DOCTYPE html>
<html>
<head>
  <!-- p5.js from CDN - always available -->
  <script src="https://cdnjs.cloudflare.com/ajax/libs/p5.js/1.7.0/p5.min.js"></script>
  <style>
    /* All styling inline - clean, minimal */
    /* Canvas on top, controls below */
  </style>
</head>
<body>
  <div id="canvas-container"></div>
  <div id="controls">
    <!-- All parameter controls -->
  </div>
  <script>
    // ALL p5.js code inline here
    // Parameter objects, classes, functions
    // setup() and draw()
    // UI handlers
    // Everything self-contained
  </script>
</body>
</html>

CRITICAL: This is a single artifact. No external files, no imports (except p5.js CDN). Everything inline.

4. Implementation Details - BUILD THE SIDEBAR

The sidebar structure:

1. Seed (FIXED) - Always include exactly as shown:

• Seed display
• Prev/Next/Random/Jump buttons

2. Parameters (VARIABLE) - Create controls for the art:

<div class="control-group">
    <label>Parameter Name</label>
    <input type="range" id="param" min="..." max="..." step="..." value="..." oninput="updateParam('param', this.value)">
    <span class="value-display" id="param-value">...</span>
</div>

Add as many control-group divs as there are parameters.

3. Colors (OPTIONAL/VARIABLE) - Include if the art needs adjustable colors:

• Add color pickers if users should control palette
• Skip this section if the art uses fixed colors
• Skip if the art is monochrome

4. Actions (FIXED) - Always include exactly as shown:

• Regenerate button
• Reset button
• Download PNG button

Requirements:

• Seed controls must work (prev/next/random/jump/display)
• All parameters must have UI controls
• Regenerate, Reset, Download buttons must work
• Keep Anthropic branding (UI styling, not art colors)

USING THE ARTIFACT

The HTML artifact works immediately:

1. In claude.ai: Displayed as an interactive artifact - runs instantly
2. As a file: Save and open in any browser - no server needed
3. Sharing: Send the HTML file - it's completely self-contained

VARIATIONS & EXPLORATION

The artifact includes seed navigation by default (prev/next/random buttons), allowing users to explore variations without creating multiple files. If the user wants specific variations highlighted:

• Include seed presets (buttons for "Variation 1: Seed 42", "Variation 2: Seed 127", etc.)
• Add a "Gallery Mode" that shows thumbnails of multiple seeds side-by-side
• All within the same single artifact

This is like creating a series of prints from the same plate - the algorithm is consistent, but each seed reveals different facets of its potential. The interactive nature means users discover their own favorites by exploring the seed space.

THE CREATIVE PROCESS

User request → Algorithmic philosophy → Implementation

Each request is unique. The process involves:

1. Interpret the user's intent - What aesthetic is being sought?
2. Create an algorithmic philosophy (4-6 paragraphs) describing the computational approach
3. Implement it in code - Build the algorithm that expresses this philosophy
4. Design appropriate parameters - What should be tunable?
5. Build matching UI controls - Sliders/inputs for those parameters

The constants:

• Anthropic branding (colors, fonts, layout)
• Seed navigation (always present)
• Self-contained HTML artifact

Everything else is variable:

• The algorithm itself
• The parameters
• The UI controls
• The visual outcome

To achieve the best results, trust creativity and let the philosophy guide the implementation.

RESOURCES

This skill includes helpful templates and documentation:

• templates/viewer.html: REQUIRED STARTING POINT for all HTML artifacts.

  • This is the foundation - contains the exact structure and Anthropic branding
  • Keep unchanged: Layout structure, sidebar organization, Anthropic colors/fonts, seed controls, action buttons
  • Replace: The p5.js algorithm, parameter definitions, and UI controls in Parameters section
  • The extensive comments in the file mark exactly what to keep vs replace

• templates/generator_template.js: Reference for p5.js best practices and code structure principles.

  • Shows how to organize parameters, use seeded randomness, structure classes
  • NOT a pattern menu - use these principles to build unique algorithms
  • Embed algorithms inline in the HTML artifact (don't create separate .js files)

Critical reminder:

• The template is the STARTING POINT, not inspiration
• The algorithm is where to create something unique
• Don't copy the flow field example - build what the philosophy demands
• But DO keep the exact UI structure and Anthropic branding from the template

Artifacts Builder

To build powerful frontend claude.ai artifacts, follow these steps:

1. Initialize the frontend repo using scripts/init-artifact.sh
2. Develop your artifact by editing the generated code
3. Bundle all code into a single HTML file using scripts/bundle-artifact.sh
4. Display artifact to user
5. (Optional) Test the artifact

Stack: React 18 + TypeScript + Vite + Parcel (bundling) + Tailwind CSS + shadcn/ui

Design & Style Guidelines

VERY IMPORTANT: To avoid what is often referred to as "AI slop", avoid using excessive centered layouts, purple gradients, uniform rounded corners, and Inter font.

Quick Start

Step 1: Initialize Project

Run the initialization script to create a new React project:

bash scripts/init-artifact.sh <project-name>
cd <project-name>

This creates a fully configured project with:

• ✅ React + TypeScript (via Vite)
• ✅ Tailwind CSS 3.4.1 with shadcn/ui theming system
• ✅ Path aliases (@/) configured
• ✅ 40+ shadcn/ui components pre-installed
• ✅ All Radix UI dependencies included
• ✅ Parcel configured for bundling (via .parcelrc)
• ✅ Node 18+ compatibility (auto-detects and pins Vite version)

Step 2: Develop Your Artifact

To build the artifact, edit the generated files. See Common Development Tasks below for guidance.

Step 3: Bundle to Single HTML File

To bundle the React app into a single HTML artifact:

bash scripts/bundle-artifact.sh

This creates bundle.html - a self-contained artifact with all JavaScript, CSS, and dependencies inlined. This file can be directly shared in Claude conversations as an artifact.

Requirements: Your project must have an index.html in the root directory.

What the script does:

• Installs bundling dependencies (parcel, @parcel/config-default, parcel-resolver-tspaths, html-inline)
• Creates .parcelrc config with path alias support
• Builds with Parcel (no source maps)
• Inlines all assets into single HTML using html-inline

Step 4: Share Artifact with User

Finally, share the bundled HTML file in conversation with the user so they can view it as an artifact.

Step 5: Testing/Visualizing the Artifact (Optional)

Note: This is a completely optional step. Only perform if necessary or requested.

To test/visualize the artifact, use available tools (including other Skills or built-in tools like Playwright or Puppeteer). In general, avoid testing the artifact upfront as it adds latency between the request and when the finished artifact can be seen. Test later, after presenting the artifact, if requested or if issues arise.

Reference

• shadcn/ui components: https://ui.shadcn.com/docs/components

Anthropic Brand Styling

Overview

To access Anthropic's official brand identity and style resources, use this skill.

Keywords: branding, corporate identity, visual identity, post-processing, styling, brand colors, typography, Anthropic brand, visual formatting, visual design

Brand Guidelines

Colors

Main Colors:

• Dark: #141413 - Primary text and dark backgrounds
• Light: #faf9f5 - Light backgrounds and text on dark
• Mid Gray: #b0aea5 - Secondary elements
• Light Gray: #e8e6dc - Subtle backgrounds

Accent Colors:

• Orange: #d97757 - Primary accent
• Blue: #6a9bcc - Secondary accent
• Green: #788c5d - Tertiary accent

Typography

• Headings: Poppins (with Arial fallback)
• Body Text: Lora (with Georgia fallback)
• Note: Fonts should be pre-installed in your environment for best results

Features

Smart Font Application

• Applies Poppins font to headings (24pt and larger)
• Applies Lora font to body text
• Automatically falls back to Arial/Georgia if custom fonts unavailable
• Preserves readability across all systems

Text Styling

• Headings (24pt+): Poppins font
• Body text: Lora font
• Smart color selection based on background
• Preserves text hierarchy and formatting

Shape and Accent Colors

• Non-text shapes use accent colors
• Cycles through orange, blue, and green accents
• Maintains visual interest while staying on-brand

Technical Details

Font Management

• Uses system-installed Poppins and Lora fonts when available
• Provides automatic fallback to Arial (headings) and Georgia (body)
• No font installation required - works with existing system fonts
• For best results, pre-install Poppins and Lora fonts in your environment

Color Application

• Uses RGB color values for precise brand matching
• Applied via python-pptx's RGBColor class
• Maintains color fidelity across different systems

These are instructions for creating design philosophies - aesthetic movements that are then EXPRESSED VISUALLY. Output only .md files, .pdf files, and .png files.

Complete this in two steps:

1. Design Philosophy Creation (.md file)
2. Express by creating it on a canvas (.pdf file or .png file)

First, undertake this task:

DESIGN PHILOSOPHY CREATION

To begin, create a VISUAL PHILOSOPHY (not layouts or templates) that will be interpreted through:

• Form, space, color, composition
• Images, graphics, shapes, patterns
• Minimal text as visual accent

THE CRITICAL UNDERSTANDING

• What is received: Some subtle input or instructions by the user that should be taken into account, but used as a foundation; it should not constrain creative freedom.
• What is created: A design philosophy/aesthetic movement.
• What happens next: Then, the same version receives the philosophy and EXPRESSES IT VISUALLY - creating artifacts that are 90% visual design, 10% essential text.

Consider this approach:

• Write a manifesto for an art movement
• The next phase involves making the artwork

The philosophy must emphasize: Visual expression. Spatial communication. Artistic interpretation. Minimal words.

HOW TO GENERATE A VISUAL PHILOSOPHY

Name the movement (1-2 words): "Brutalist Joy" / "Chromatic Silence" / "Metabolist Dreams"

Articulate the philosophy (4-6 paragraphs - concise but complete):

To capture the VISUAL essence, express how the philosophy manifests through:

• Space and form
• Color and material
• Scale and rhythm
• Composition and balance
• Visual hierarchy

CRITICAL GUIDELINES:

• Avoid redundancy: Each design aspect should be mentioned once. Avoid repeating points about color theory, spatial relationships, or typographic principles unless adding new depth.
• Emphasize craftsmanship REPEATEDLY: The philosophy MUST stress multiple times that the final work should appear as though it took countless hours to create, was labored over with care, and comes from someone at the absolute top of their field. This framing is essential - repeat phrases like "meticulously crafted," "the product of deep expertise," "painstaking attention," "master-level execution."
• Leave creative space: Remain specific about the aesthetic direction, but concise enough that the next Claude has room to make interpretive choices also at a extremely high level of craftmanship.

The philosophy must guide the next version to express ideas VISUALLY, not through text. Information lives in design, not paragraphs.

PHILOSOPHY EXAMPLES

"Concrete Poetry" Philosophy: Communication through monumental form and bold geometry. Visual expression: Massive color blocks, sculptural typography (huge single words, tiny labels), Brutalist spatial divisions, Polish poster energy meets Le Corbusier. Ideas expressed through visual weight and spatial tension, not explanation. Text as rare, powerful gesture - never paragraphs, only essential words integrated into the visual architecture. Every element placed with the precision of a master craftsman.

"Chromatic Language" Philosophy: Color as the primary information system. Visual expression: Geometric precision where color zones create meaning. Typography minimal - small sans-serif labels letting chromatic fields communicate. Think Josef Albers' interaction meets data visualization. Information encoded spatially and chromatically. Words only to anchor what color already shows. The result of painstaking chromatic calibration.

"Analog Meditation" Philosophy: Quiet visual contemplation through texture and breathing room. Visual expression: Paper grain, ink bleeds, vast negative space. Photography and illustration dominate. Typography whispered (small, restrained, serving the visual). Japanese photobook aesthetic. Images breathe across pages. Text appears sparingly - short phrases, never explanatory blocks. Each composition balanced with the care of a meditation practice.

"Organic Systems" Philosophy: Natural clustering and modular growth patterns. Visual expression: Rounded forms, organic arrangements, color from nature through architecture. Information shown through visual diagrams, spatial relationships, iconography. Text only for key labels floating in space. The composition tells the story through expert spatial orchestration.

"Geometric Silence" Philosophy: Pure order and restraint. Visual expression: Grid-based precision, bold photography or stark graphics, dramatic negative space. Typography precise but minimal - small essential text, large quiet zones. Swiss formalism meets Brutalist material honesty. Structure communicates, not words. Every alignment the work of countless refinements.

These are condensed examples. The actual design philosophy should be 4-6 substantial paragraphs.

ESSENTIAL PRINCIPLES

• VISUAL PHILOSOPHY: Create an aesthetic worldview to be expressed through design
• MINIMAL TEXT: Always emphasize that text is sparse, essential-only, integrated as visual element - never lengthy
• SPATIAL EXPRESSION: Ideas communicate through space, form, color, composition - not paragraphs
• ARTISTIC FREEDOM: The next Claude interprets the philosophy visually - provide creative room
• PURE DESIGN: This is about making ART OBJECTS, not documents with decoration
• EXPERT CRAFTSMANSHIP: Repeatedly emphasize the final work must look meticulously crafted, labored over with care, the product of countless hours by someone at the top of their field

The design philosophy should be 4-6 paragraphs long. Fill it with poetic design philosophy that brings together the core vision. Avoid repeating the same points. Keep the design philosophy generic without mentioning the intention of the art, as if it can be used wherever. Output the design philosophy as a .md file.

DEDUCING THE SUBTLE REFERENCE

CRITICAL STEP: Before creating the canvas, identify the subtle conceptual thread from the original request.

THE ESSENTIAL PRINCIPLE: The topic is a subtle, niche reference embedded within the art itself - not always literal, always sophisticated. Someone familiar with the subject should feel it intuitively, while others simply experience a masterful abstract composition. The design philosophy provides the aesthetic language. The deduced topic provides the soul - the quiet conceptual DNA woven invisibly into form, color, and composition.

This is VERY IMPORTANT: The reference must be refined so it enhances the work's depth without announcing itself. Think like a jazz musician quoting another song - only those who know will catch it, but everyone appreciates the music.

CANVAS CREATION

With both the philosophy and the conceptual framework established, express it on a canvas. Take a moment to gather thoughts and clear the mind. Use the design philosophy created and the instructions below to craft a masterpiece, embodying all aspects of the philosophy with expert craftsmanship.

IMPORTANT: For any type of content, even if the user requests something for a movie/game/book, the approach should still be sophisticated. Never lose sight of the idea that this should be art, not something that's cartoony or amateur.

To create museum or magazine quality work, use the design philosophy as the foundation. Create one single page, highly visual, design-forward PDF or PNG output (unless asked for more pages). Generally use repeating patterns and perfect shapes. Treat the abstract philosophical design as if it were a scientific bible, borrowing the visual language of systematic observation—dense accumulation of marks, repeated elements, or layered patterns that build meaning through patient repetition and reward sustained viewing. Add sparse, clinical typography and systematic reference markers that suggest this could be a diagram from an imaginary discipline, treating the invisible subject with the same reverence typically reserved for documenting observable phenomena. Anchor the piece with simple phrase(s) or details positioned subtly, using a limited color palette that feels intentional and cohesive. Embrace the paradox of using analytical visual language to express ideas about human experience: the result should feel like an artifact that proves something ephemeral can be studied, mapped, and understood through careful attention. This is true art.

Text as a contextual element: Text is always minimal and visual-first, but let context guide whether that means whisper-quiet labels or bold typographic gestures. A punk venue poster might have larger, more aggressive type than a minimalist ceramics studio identity. Most of the time, font should be thin. All use of fonts must be design-forward and prioritize visual communication. Regardless of text scale, nothing falls off the page and nothing overlaps. Every element must be contained within the canvas boundaries with proper margins. Check carefully that all text, graphics, and visual elements have breathing room and clear separation. This is non-negotiable for professional execution. IMPORTANT: Use different fonts if writing text. Search the ./canvas-fonts directory. Regardless of approach, sophistication is non-negotiable.

Download and use whatever fonts are needed to make this a reality. Get creative by making the typography actually part of the art itself -- if the art is abstract, bring the font onto the canvas, not typeset digitally.

To push boundaries, follow design instinct/intuition while using the philosophy as a guiding principle. Embrace ultimate design freedom and choice. Push aesthetics and design to the frontier.

CRITICAL: To achieve human-crafted quality (not AI-generated), create work that looks like it took countless hours. Make it appear as though someone at the absolute top of their field labored over every detail with painstaking care. Ensure the composition, spacing, color choices, typography - everything screams expert-level craftsmanship. Double-check that nothing overlaps, formatting is flawless, every detail perfect. Create something that could be shown to people to prove expertise and rank as undeniably impressive.

Output the final result as a single, downloadable .pdf or .png file, alongside the design philosophy used as a .md file.

FINAL STEP

IMPORTANT: The user ALREADY said "It isn't perfect enough. It must be pristine, a masterpiece if craftsmanship, as if it were about to be displayed in a museum."

CRITICAL: To refine the work, avoid adding more graphics; instead refine what has been created and make it extremely crisp, respecting the design philosophy and the principles of minimalism entirely. Rather than adding a fun filter or refactoring a font, consider how to make the existing composition more cohesive with the art. If the instinct is to call a new function or draw a new shape, STOP and instead ask: "How can I make what's already here more of a piece of art?"

Take a second pass. Go back to the code and refine/polish further to make this a philosophically designed masterpiece.

MULTI-PAGE OPTION

To create additional pages when requested, create more creative pages along the same lines as the design philosophy but distinctly different as well. Bundle those pages in the same .pdf or many .pngs. Treat the first page as just a single page in a whole coffee table book waiting to be filled. Make the next pages unique twists and memories of the original. Have them almost tell a story in a very tasteful way. Exercise full creative freedom.

Changelog Generator

This skill transforms technical git commits into polished, user-friendly changelogs that your customers and users will actually understand and appreciate.

When to Use This Skill

• Preparing release notes for a new version
• Creating weekly or monthly product update summaries
• Documenting changes for customers
• Writing changelog entries for app store submissions
• Generating update notifications
• Creating internal release documentation
• Maintaining a public changelog/product updates page

What This Skill Does

1. Scans Git History: Analyzes commits from a specific time period or between versions
2. Categorizes Changes: Groups commits into logical categories (features, improvements, bug fixes, breaking changes, security)
3. Translates Technical → User-Friendly: Converts developer commits into customer language
4. Formats Professionally: Creates clean, structured changelog entries
5. Filters Noise: Excludes internal commits (refactoring, tests, etc.)
6. Follows Best Practices: Applies changelog guidelines and your brand voice

How to Use

Basic Usage

From your project repository:

Create a changelog from commits since last release

Generate changelog for all commits from the past week

Create release notes for version 2.5.0

With Specific Date Range

Create a changelog for all commits between March 1 and March 15

With Custom Guidelines

Create a changelog for commits since v2.4.0, using my changelog 
guidelines from CHANGELOG_STYLE.md

Example

User: "Create a changelog for commits from the past 7 days"

Output:

# Updates - Week of March 10, 2024

## ✨ New Features

- **Team Workspaces**: Create separate workspaces for different 
  projects. Invite team members and keep everything organized.

- **Keyboard Shortcuts**: Press ? to see all available shortcuts. 
  Navigate faster without touching your mouse.

## 🔧 Improvements

- **Faster Sync**: Files now sync 2x faster across devices
- **Better Search**: Search now includes file contents, not just titles

## 🐛 Fixes

- Fixed issue where large images wouldn't upload
- Resolved timezone confusion in scheduled posts
- Corrected notification badge count

Inspired by: Manik Aggarwal's use case from Lenny's Newsletter

Tips

• Run from your git repository root
• Specify date ranges for focused changelogs
• Use your CHANGELOG_STYLE.md for consistent formatting
• Review and adjust the generated changelog before publishing
• Save output directly to CHANGELOG.md

Related Use Cases

• Creating GitHub release notes
• Writing app store update descriptions
• Generating email updates for users
• Creating social media announcement posts

Competitive Ads Extractor

This skill extracts your competitors' ads from ad libraries and analyzes what's working—the problems they're highlighting, use cases they're targeting, and copy/creative that's resonating.

When to Use This Skill

• Researching competitor ad strategies
• Finding inspiration for your own ads
• Understanding market positioning
• Identifying successful ad patterns
• Analyzing messaging that works
• Discovering new use cases or pain points
• Planning ad campaigns with proven concepts

What This Skill Does

1. Extracts Ads: Scrapes ads from Facebook Ad Library, LinkedIn, etc.
2. Captures Screenshots: Saves visual copies of all ads
3. Analyzes Messaging: Identifies problems, use cases, and value props
4. Categorizes Ads: Groups by theme, audience, or format
5. Identifies Patterns: Finds common successful approaches
6. Provides Insights: Explains why certain ads likely perform well

How to Use

Basic Extraction

Extract all current ads from [Competitor Name] on Facebook Ad Library

Scrape ads from [Company] and analyze their messaging

Specific Analysis

Get all ads from [Competitor] focusing on their messaging 
about [specific problem]. What pain points are they highlighting?

Competitive Set

Extract ads from these 5 competitors: [list]. 
Compare their approaches and tell me what's working.

Specific Platform

Get LinkedIn ads from [Competitor] and analyze their 
B2B positioning strategy

Example

User: "Extract ads from Notion on Facebook Ad Library and tell me what messaging is working for them."

Process:

Accessing Facebook Ad Library...
Searching for: Notion
Found: 23 active ads

Extracting screenshots...
[████████████████████] 100%

Saved to: competitor-ads/notion/
- ad-001-collaboration.png
- ad-002-productivity.png
- ad-003-templates.png
...

Analyzing messaging...

Output:

# Notion Ad Analysis

## Overview
- Total Ads: 23 active
- Primary Themes: Productivity (35%), Collaboration (30%), 
  Templates (20%), AI Features (15%)
- Ad Formats: Static images (60%), Video (40%)
- CTA Patterns: "Try for free", "Get started"

## Key Problems They're Highlighting

1. **Scattered Information** (8 ads)
   Copy: "Stop switching between 10 different tools"
   Why it works: Direct pain point many teams face

2. **Meeting Overload** (5 ads)
   Copy: "Replace unnecessary meetings with async updates"
   Why it works: Post-COVID remote work pain point

3. **Lost Documentation** (4 ads)
   Copy: "Never ask 'where is that doc?' again"
   Why it works: Universal workplace frustration

## Successful Creative Patterns

### Pattern 1: Before/After Split
- Shows chaotic tool landscape → Clean Notion workspace
- Used in 6 high-performing ads
- Visual metaphor is immediately clear

### Pattern 2: Feature Showcase
- GIF of actual product usage
- Shows specific feature in 5 seconds
- Used for new features (AI, templates)

### Pattern 3: Social Proof
- "Join 20M users" messaging
- Customer logos
- Used in 4 ads targeting enterprise

## Copy That's Working

Best Headlines:
1. "Your team's knowledge, finally in one place"
   → Benefit-focused, addresses pain directly
   
2. "The all-in-one workspace"
   → Clear positioning, broad appeal
   
3. "AI that actually helps you work"
   → Addresses AI skepticism, practical angle

Best Body Copy Patterns:
- Short sentences (under 10 words)
- Focus on outcomes not features
- Include specific numbers ("Cut meetings by 50%")

## Audience Targeting Insights

Based on ad variations:
- Startup founders: Solo productivity angle
- Team leads: Collaboration and alignment
- Enterprise: Security and compliance mentions
- Students: Free plan, templates, organization

## Recommendations for Your Ads

1. **Test the "tool sprawl" pain point**
   → Strong resonance based on their ad frequency

2. **Use product screenshots over abstract visuals**
   → All their top ads show actual UI

3. **Lead with the problem, not the solution**
   → "Tired of X?" performs better than "Introducing Y"

4. **Keep copy under 100 characters**
   → Their shortest ads seem most frequent

5. **Test before/after visual formats**
   → Proven pattern in their creative

## Files Saved
- All ads: ~/competitor-ads/notion/
- Analysis: ~/competitor-ads/notion/analysis.md
- Best performers: ~/competitor-ads/notion/top-10/

Inspired by: Sumant Subrahmanya's use case from Lenny's Newsletter

What You Can Learn

Messaging Analysis

• What problems they emphasize
• How they position against competition
• Value propositions that resonate
• Target audience segments

Creative Patterns

• Visual styles that work
• Video vs. static image performance
• Color schemes and branding
• Layout patterns

Copy Formulas

• Headline structures
• Call-to-action patterns
• Length and tone
• Emotional triggers

Campaign Strategy

• Seasonal campaigns
• Product launch approaches
• Feature announcement tactics
• Retargeting patterns

Best Practices

Legal & Ethical

✓ Only use for research and inspiration ✓ Don't copy ads directly ✓ Respect intellectual property ✓ Use insights to inform original creative ✗ Don't plagiarize copy or steal designs

Analysis Tips

1. Look for patterns: What themes repeat?
2. Track over time: Save ads monthly to see evolution
3. Test hypotheses: Adapt successful patterns for your brand
4. Segment by audience: Different messages for different targets
5. Compare platforms: LinkedIn vs Facebook messaging differs

Advanced Features

Trend Tracking

Compare [Competitor]'s ads from Q1 vs Q2. 
What messaging has changed?

Multi-Competitor Analysis

Extract ads from [Company A], [Company B], [Company C]. 
What are the common patterns? Where do they differ?

Industry Benchmarks

Show me ad patterns across the top 10 project management 
tools. What problems do they all focus on?

Format Analysis

Analyze video ads vs static image ads from [Competitor]. 
Which gets more engagement? (if data available)

Common Workflows

Ad Campaign Planning

1. Extract competitor ads
2. Identify successful patterns
3. Note gaps in their messaging
4. Brainstorm unique angles
5. Draft test ad variations

Positioning Research

1. Get ads from 5 competitors
2. Map their positioning
3. Find underserved angles
4. Develop differentiated messaging
5. Test against their approaches

Creative Inspiration

1. Extract ads by theme
2. Analyze visual patterns
3. Note color and layout trends
4. Adapt successful patterns
5. Create original variations

Tips for Success

1. Regular Monitoring: Check monthly for changes
2. Broad Research: Look at adjacent competitors too
3. Save Everything: Build a reference library
4. Test Insights: Run your own experiments
5. Track Performance: A/B test inspired concepts
6. Stay Original: Use for inspiration, not copying
7. Multiple Platforms: Compare Facebook, LinkedIn, TikTok, etc.

Output Formats

• Screenshots: All ads saved as images
• Analysis Report: Markdown summary of insights
• Spreadsheet: CSV with ad copy, CTAs, themes
• Presentation: Visual deck of top performers
• Pattern Library: Categorized by approach

Related Use Cases

• Writing better ad copy for your campaigns
• Understanding market positioning
• Finding content gaps in your messaging
• Discovering new use cases for your product
• Planning product marketing strategy
• Inspiring social media content

Content Research Writer

This skill acts as your writing partner, helping you research, outline, draft, and refine content while maintaining your unique voice and style.

When to Use This Skill

• Writing blog posts, articles, or newsletters
• Creating educational content or tutorials
• Drafting thought leadership pieces
• Researching and writing case studies
• Producing technical documentation with sources
• Writing with proper citations and references
• Improving hooks and introductions
• Getting section-by-section feedback while writing

What This Skill Does

1. Collaborative Outlining: Helps you structure ideas into coherent outlines
2. Research Assistance: Finds relevant information and adds citations
3. Hook Improvement: Strengthens your opening to capture attention
4. Section Feedback: Reviews each section as you write
5. Voice Preservation: Maintains your writing style and tone
6. Citation Management: Adds and formats references properly
7. Iterative Refinement: Helps you improve through multiple drafts

How to Use

Setup Your Writing Environment

Create a dedicated folder for your article:

mkdir ~/writing/my-article-title
cd ~/writing/my-article-title

Create your draft file:

touch article-draft.md

Open Claude Code from this directory and start writing.

Basic Workflow

1. Start with an outline:

Help me create an outline for an article about [topic]

2. Research and add citations:

Research [specific topic] and add citations to my outline

3. Improve the hook:

Here's my introduction. Help me make the hook more compelling.

4. Get section feedback:

I just finished the "Why This Matters" section. Review it and give feedback.

5. Refine and polish:

Review the full draft for flow, clarity, and consistency.

Instructions

When a user requests writing assistance:

1. Understand the Writing Project

   Ask clarifying questions:

   • What's the topic and main argument?
   • Who's the target audience?
   • What's the desired length/format?
   • What's your goal? (educate, persuade, entertain, explain)
   • Any existing research or sources to include?
   • What's your writing style? (formal, conversational, technical)

2. Collaborative Outlining

   Help structure the content:

   # Article Outline: [Title]
   
   ## Hook
   - [Opening line/story/statistic]
   - [Why reader should care]
   
   ## Introduction
   - Context and background
   - Problem statement
   - What this article covers
   
   ## Main Sections
   
   ### Section 1: [Title]
   - Key point A
   - Key point B
   - Example/evidence
   - [Research needed: specific topic]
   
   ### Section 2: [Title]
   - Key point C
   - Key point D
   - Data/citation needed
   
   ### Section 3: [Title]
   - Key point E
   - Counter-arguments
   - Resolution
   
   ## Conclusion
   - Summary of main points
   - Call to action
   - Final thought
   
   ## Research To-Do
   - [ ] Find data on [topic]
   - [ ] Get examples of [concept]
   - [ ] Source citation for [claim]
   

   Iterate on outline:

   • Adjust based on feedback
   • Ensure logical flow
   • Identify research gaps
   • Mark sections for deep dives

3. Conduct Research

   When user requests research on a topic:

   • Search for relevant information
   • Find credible sources
   • Extract key facts, quotes, and data
   • Add citations in requested format

   Example output:

   ## Research: AI Impact on Productivity
   
   Key Findings:
   
   1. **Productivity Gains**: Studies show 40% time savings for 
      content creation tasks [1]
   
   2. **Adoption Rates**: 67% of knowledge workers use AI tools 
      weekly [2]
   
   3. **Expert Quote**: "AI augments rather than replaces human 
      creativity" - Dr. Jane Smith, MIT [3]
   
   Citations:
   [1] McKinsey Global Institute. (2024). "The Economic Potential 
       of Generative AI"
   [2] Stack Overflow Developer Survey (2024)
   [3] Smith, J. (2024). MIT Technology Review interview
   
   Added to outline under Section 2.
   

4. Improve Hooks

   When user shares an introduction, analyze and strengthen:

   Current Hook Analysis:

   • What works: [positive elements]
   • What could be stronger: [areas for improvement]
   • Emotional impact: [current vs. potential]

   Suggested Alternatives:

   Option 1: [Bold statement]

   [Example] Why it works: [explanation]

   Option 2: [Personal story]

   [Example] Why it works: [explanation]

   Option 3: [Surprising data]

   [Example] Why it works: [explanation]

   Questions to hook:

   • Does it create curiosity?
   • Does it promise value?
   • Is it specific enough?
   • Does it match the audience?

5. Provide Section-by-Section Feedback

   As user writes each section, review for:

   # Feedback: [Section Name]
   
   ## What Works Well ✓
   - [Strength 1]
   - [Strength 2]
   - [Strength 3]
   
   ## Suggestions for Improvement
   
   ### Clarity
   - [Specific issue] → [Suggested fix]
   - [Complex sentence] → [Simpler alternative]
   
   ### Flow
   - [Transition issue] → [Better connection]
   - [Paragraph order] → [Suggested reordering]
   
   ### Evidence
   - [Claim needing support] → [Add citation or example]
   - [Generic statement] → [Make more specific]
   
   ### Style
   - [Tone inconsistency] → [Match your voice better]
   - [Word choice] → [Stronger alternative]
   
   ## Specific Line Edits
   
   Original:
   > [Exact quote from draft]
   
   Suggested:
   > [Improved version]
   
   Why: [Explanation]
   
   ## Questions to Consider
   - [Thought-provoking question 1]
   - [Thought-provoking question 2]
   
   Ready to move to next section!
   

6. Preserve Writer's Voice

   Important principles:

   • Learn their style: Read existing writing samples
   • Suggest, don't replace: Offer options, not directives
   • Match tone: Formal, casual, technical, friendly
   • Respect choices: If they prefer their version, support it
   • Enhance, don't override: Make their writing better, not different

   Ask periodically:

   • "Does this sound like you?"
   • "Is this the right tone?"
   • "Should I be more/less [formal/casual/technical]?"

7. Citation Management

   Handle references based on user preference:

   Inline Citations:

   Studies show 40% productivity improvement (McKinsey, 2024).
   

   Numbered References:

   Studies show 40% productivity improvement [1].
   
   [1] McKinsey Global Institute. (2024)...
   

   Footnote Style:

   Studies show 40% productivity improvement^1
   
   ^1: McKinsey Global Institute. (2024)...
   

   Maintain a running citations list:

   ## References
   
   1. Author. (Year). "Title". Publication.
   2. Author. (Year). "Title". Publication.
   ...
   

8. Final Review and Polish

   When draft is complete, provide comprehensive feedback:

   # Full Draft Review
   
   ## Overall Assessment
   
   **Strengths**:
   - [Major strength 1]
   - [Major strength 2]
   - [Major strength 3]
   
   **Impact**: [Overall effectiveness assessment]
   
   ## Structure & Flow
   - [Comments on organization]
   - [Transition quality]
   - [Pacing assessment]
   
   ## Content Quality
   - [Argument strength]
   - [Evidence sufficiency]
   - [Example effectiveness]
   
   ## Technical Quality
   - Grammar and mechanics: [assessment]
   - Consistency: [assessment]
   - Citations: [completeness check]
   
   ## Readability
   - Clarity score: [evaluation]
   - Sentence variety: [evaluation]
   - Paragraph length: [evaluation]
   
   ## Final Polish Suggestions
   
   1. **Introduction**: [Specific improvements]
   2. **Body**: [Specific improvements]
   3. **Conclusion**: [Specific improvements]
   4. **Title**: [Options if needed]
   
   ## Pre-Publish Checklist
   - [ ] All claims sourced
   - [ ] Citations formatted
   - [ ] Examples clear
   - [ ] Transitions smooth
   - [ ] Call to action present
   - [ ] Proofread for typos
   
   Ready to publish! 🚀
   

Examples

Example 1: Teresa Torres's Workflow

User: "I'm writing an article about continuous discovery. Help me create an outline."

Process:

1. Collaborates on outline structure
2. Identifies research needs
3. User starts writing introduction
4. Reviews and improves the hook
5. User writes each section
6. Provides feedback after each section
7. Conducts research and adds citations
8. Final review of complete draft
9. Polish and prep for publishing

Result: Well-researched, properly cited article written in Teresa's voice with strong structure and flow.

Example 2: Research-Heavy Article

User: "I'm writing about AI's impact on product management. Help me find current data and examples."

Output:

## Research Compiled

### Recent Data
- Gartner: 80% of PMs will use AI tools by 2025 [1]
- Survey: 45% report faster feature shipping [2]
- Case study: Airbnb's AI-assisted prioritization [3]

### Expert Quotes
- "AI amplifies PM judgment, not replaces it" - Marty Cagan
- [Additional quotes with citations]

### Real Examples
1. **Company A**: Used AI for user research synthesis
   - Result: 60% time savings
   - Source: [citation]

2. **Company B**: AI-powered roadmap analysis
   - Result: Better stakeholder alignment
   - Source: [citation]

All added to your outline with proper citations.

Example 3: Hook Improvement

User's Original Hook:

"Product management is changing because of AI. In this article, I'll discuss some ways AI affects product managers."

Improved Options:

Option 1 (Data-driven):

"Last month, I asked AI to analyze 500 customer interviews. It took 30 minutes instead of 3 weeks. Product management will never be the same."

Option 2 (Question):

"What if you could talk to every customer, read every review, and analyze every support ticket—all before your morning coffee?"

Option 3 (Story):

"Sarah spent two weeks building the wrong feature. Not because she didn't understand her users, but because she couldn't process the hundreds of interviews fast enough to spot the pattern."

Example 4: Section Feedback

User: "Just finished my 'Common Mistakes' section. Thoughts?"

Response:

# Feedback: Common Mistakes Section

## What Works Well ✓
- Strong examples (the Slack notification story)
- Clear structure (3 mistakes, clean layout)
- Practical advice for each mistake

## Suggestions

### Make It More Specific
Your second point says "Bad prioritization" but could be stronger:

Current:
> "Many teams prioritize badly by focusing on features instead of outcomes."

Suggested:
> "I've watched teams ship 14 features in a quarter yet move none of their key metrics. They prioritized activity over progress."

### Add Data
The third mistake would benefit from evidence:
> "[Add citation]: Studies show teams without regular user contact are 3x more likely to build unused features [needs source]"

### Flow Improvement
Consider reordering: Mistake 3 → Mistake 2 → Mistake 1
This builds from small to big impact.

Ready for the next section!

Writing Workflows

Blog Post Workflow

1. Outline together
2. Research key points
3. Write introduction → get feedback
4. Write body sections → feedback each
5. Write conclusion → final review
6. Polish and edit

Newsletter Workflow

1. Discuss hook ideas
2. Quick outline (shorter format)
3. Draft in one session
4. Review for clarity and links
5. Quick polish

Technical Tutorial Workflow

1. Outline steps
2. Write code examples
3. Add explanations
4. Test instructions
5. Add troubleshooting section
6. Final review for accuracy

Thought Leadership Workflow

1. Brainstorm unique angle
2. Research existing perspectives
3. Develop your thesis
4. Write with strong POV
5. Add supporting evidence
6. Craft compelling conclusion

Pro Tips

1. Work in VS Code: Better than web Claude for long-form writing
2. One section at a time: Get feedback incrementally
3. Save research separately: Keep a research.md file
4. Version your drafts: article-v1.md, article-v2.md, etc.
5. Read aloud: Use feedback to identify clunky sentences
6. Set deadlines: "I want to finish the draft today"
7. Take breaks: Write, get feedback, pause, revise

File Organization

Recommended structure for writing projects:

~/writing/article-name/
├── outline.md          # Your outline
├── research.md         # All research and citations
├── draft-v1.md         # First draft
├── draft-v2.md         # Revised draft
├── final.md            # Publication-ready
├── feedback.md         # Collected feedback
└── sources/            # Reference materials
    ├── study1.pdf
    └── article2.md

Best Practices

For Research

• Verify sources before citing
• Use recent data when possible
• Balance different perspectives
• Link to original sources

For Feedback

• Be specific about what you want: "Is this too technical?"
• Share your concerns: "I'm worried this section drags"
• Ask questions: "Does this flow logically?"
• Request alternatives: "What's another way to explain this?"

For Voice

• Share examples of your writing
• Specify tone preferences
• Point out good matches: "That sounds like me!"
• Flag mismatches: "Too formal for my style"

Related Use Cases

• Creating social media posts from articles
• Adapting content for different audiences
• Writing email newsletters
• Drafting technical documentation
• Creating presentation content
• Writing case studies
• Developing course outlines

DOCX creation, editing, and analysis

Overview

A user may ask you to create, edit, or analyze the contents of a .docx file. A .docx file is essentially a ZIP archive containing XML files and other resources that you can read or edit. You have different tools and workflows available for different tasks.

Workflow Decision Tree

Reading/Analyzing Content

Use "Text extraction" or "Raw XML access" sections below

Creating New Document

Use "Creating a new Word document" workflow

Editing Existing Document

• Your own document + simple changes Use "Basic OOXML editing" workflow

• Someone else's document Use "Redlining workflow" (recommended default)

• Legal, academic, business, or government docs Use "Redlining workflow" (required)

Reading and analyzing content

Text extraction

If you just need to read the text contents of a document, you should convert the document to markdown using pandoc. Pandoc provides excellent support for preserving document structure and can show tracked changes:

# Convert document to markdown with tracked changes
pandoc --track-changes=all path-to-file.docx -o output.md
# Options: --track-changes=accept/reject/all

Raw XML access

You need raw XML access for: comments, complex formatting, document structure, embedded media, and metadata. For any of these features, you'll need to unpack a document and read its raw XML contents.

Unpacking a file

python ooxml/scripts/unpack.py <office_file> <output_directory>

Key file structures

• word/document.xml - Main document contents
• word/comments.xml - Comments referenced in document.xml
• word/media/ - Embedded images and media files
• Tracked changes use <w:ins> (insertions) and <w:del> (deletions) tags

Creating a new Word document

When creating a new Word document from scratch, use docx-js, which allows you to create Word documents using JavaScript/TypeScript.

Workflow

1. MANDATORY - READ ENTIRE FILE: Read docx-js.md (~500 lines) completely from start to finish. NEVER set any range limits when reading this file. Read the full file content for detailed syntax, critical formatting rules, and best practices before proceeding with document creation.
2. Create a JavaScript/TypeScript file using Document, Paragraph, TextRun components (You can assume all dependencies are installed, but if not, refer to the dependencies section below)
3. Export as .docx using Packer.toBuffer()

Editing an existing Word document

When editing an existing Word document, use the Document library (a Python library for OOXML manipulation). The library automatically handles infrastructure setup and provides methods for document manipulation. For complex scenarios, you can access the underlying DOM directly through the library.

Workflow

1. MANDATORY - READ ENTIRE FILE: Read ooxml.md (~600 lines) completely from start to finish. NEVER set any range limits when reading this file. Read the full file content for the Document library API and XML patterns for directly editing document files.
2. Unpack the document: python ooxml/scripts/unpack.py <office_file> <output_directory>
3. Create and run a Python script using the Document library (see "Document Library" section in ooxml.md)
4. Pack the final document: python ooxml/scripts/pack.py <input_directory> <office_file>

The Document library provides both high-level methods for common operations and direct DOM access for complex scenarios.

Redlining workflow for document review

This workflow allows you to plan comprehensive tracked changes using markdown before implementing them in OOXML. CRITICAL: For complete tracked changes, you must implement ALL changes systematically.

Batching Strategy: Group related changes into batches of 3-10 changes. This makes debugging manageable while maintaining efficiency. Test each batch before moving to the next.

Principle: Minimal, Precise Edits When implementing tracked changes, only mark text that actually changes. Repeating unchanged text makes edits harder to review and appears unprofessional. Break replacements into: [unchanged text] + [deletion] + [insertion] + [unchanged text]. Preserve the original run's RSID for unchanged text by extracting the <w:r> element from the original and reusing it.

Example - Changing "30 days" to "60 days" in a sentence:

# BAD - Replaces entire sentence
'<w:del><w:r><w:delText>The term is 30 days.</w:delText></w:r></w:del><w:ins><w:r><w:t>The term is 60 days.</w:t></w:r></w:ins>'

# GOOD - Only marks what changed, preserves original <w:r> for unchanged text
'<w:r w:rsidR="00AB12CD"><w:t>The term is </w:t></w:r><w:del><w:r><w:delText>30</w:delText></w:r></w:del><w:ins><w:r><w:t>60</w:t></w:r></w:ins><w:r w:rsidR="00AB12CD"><w:t> days.</w:t></w:r>'

Tracked changes workflow

1. Get markdown representation: Convert document to markdown with tracked changes preserved:

   pandoc --track-changes=all path-to-file.docx -o current.md
   

2. Identify and group changes: Review the document and identify ALL changes needed, organizing them into logical batches:

   Location methods (for finding changes in XML):

   • Section/heading numbers (e.g., "Section 3.2", "Article IV")
   • Paragraph identifiers if numbered
   • Grep patterns with unique surrounding text
   • Document structure (e.g., "first paragraph", "signature block")
   • DO NOT use markdown line numbers - they don't map to XML structure

   Batch organization (group 3-10 related changes per batch):

   • By section: "Batch 1: Section 2 amendments", "Batch 2: Section 5 updates"
   • By type: "Batch 1: Date corrections", "Batch 2: Party name changes"
   • By complexity: Start with simple text replacements, then tackle complex structural changes
   • Sequential: "Batch 1: Pages 1-3", "Batch 2: Pages 4-6"

3. Read documentation and unpack:

   • MANDATORY - READ ENTIRE FILE: Read ooxml.md (~600 lines) completely from start to finish. NEVER set any range limits when reading this file. Pay special attention to the "Document Library" and "Tracked Change Patterns" sections.
   • Unpack the document: python ooxml/scripts/unpack.py <file.docx> <dir>
   • Note the suggested RSID: The unpack script will suggest an RSID to use for your tracked changes. Copy this RSID for use in step 4b.

4. Implement changes in batches: Group changes logically (by section, by type, or by proximity) and implement them together in a single script. This approach:

   • Makes debugging easier (smaller batch = easier to isolate errors)
   • Allows incremental progress
   • Maintains efficiency (batch size of 3-10 changes works well)

   Suggested batch groupings:

   • By document section (e.g., "Section 3 changes", "Definitions", "Termination clause")
   • By change type (e.g., "Date changes", "Party name updates", "Legal term replacements")
   • By proximity (e.g., "Changes on pages 1-3", "Changes in first half of document")

   For each batch of related changes:

   a. Map text to XML: Grep for text in word/document.xml to verify how text is split across <w:r> elements.

   b. Create and run script: Use get_node to find nodes, implement changes, then doc.save(). See "Document Library" section in ooxml.md for patterns.

   Note: Always grep word/document.xml immediately before writing a script to get current line numbers and verify text content. Line numbers change after each script run.

5. Pack the document: After all batches are complete, convert the unpacked directory back to .docx:

   python ooxml/scripts/pack.py unpacked reviewed-document.docx
   

6. Final verification: Do a comprehensive check of the complete document:

   • Convert final document to markdown:

     pandoc --track-changes=all reviewed-document.docx -o verification.md
     

   • Verify ALL changes were applied correctly:

     grep "original phrase" verification.md  # Should NOT find it
     grep "replacement phrase" verification.md  # Should find it
     

   • Check that no unintended changes were introduced

Converting Documents to Images

To visually analyze Word documents, convert them to images using a two-step process:

1. Convert DOCX to PDF:

   soffice --headless --convert-to pdf document.docx
   

2. Convert PDF pages to JPEG images:

   pdftoppm -jpeg -r 150 document.pdf page
   

   This creates files like page-1.jpg, page-2.jpg, etc.

Options:

• -r 150: Sets resolution to 150 DPI (adjust for quality/size balance)
• -jpeg: Output JPEG format (use -png for PNG if preferred)
• -f N: First page to convert (e.g., -f 2 starts from page 2)
• -l N: Last page to convert (e.g., -l 5 stops at page 5)
• page: Prefix for output files

Example for specific range:

pdftoppm -jpeg -r 150 -f 2 -l 5 document.pdf page  # Converts only pages 2-5

Code Style Guidelines

IMPORTANT: When generating code for DOCX operations:

• Write concise code
• Avoid verbose variable names and redundant operations
• Avoid unnecessary print statements

Dependencies

Required dependencies (install if not available):

• pandoc: sudo apt-get install pandoc (for text extraction)
• docx: npm install -g docx (for creating new documents)
• LibreOffice: sudo apt-get install libreoffice (for PDF conversion)
• Poppler: sudo apt-get install poppler-utils (for pdftoppm to convert PDF to images)
• defusedxml: pip install defusedxml (for secure XML parsing)

PDF Processing Guide

Overview

This guide covers essential PDF processing operations using Python libraries and command-line tools. For advanced features, JavaScript libraries, and detailed examples, see reference.md. If you need to fill out a PDF form, read forms.md and follow its instructions.

Quick Start

from pypdf import PdfReader, PdfWriter

# Read a PDF
reader = PdfReader("document.pdf")
print(f"Pages: {len(reader.pages)}")

# Extract text
text = ""
for page in reader.pages:
    text += page.extract_text()

Python Libraries

pypdf - Basic Operations

Merge PDFs

from pypdf import PdfWriter, PdfReader

writer = PdfWriter()
for pdf_file in ["doc1.pdf", "doc2.pdf", "doc3.pdf"]:
    reader = PdfReader(pdf_file)
    for page in reader.pages:
        writer.add_page(page)

with open("merged.pdf", "wb") as output:
    writer.write(output)

Split PDF

reader = PdfReader("input.pdf")
for i, page in enumerate(reader.pages):
    writer = PdfWriter()
    writer.add_page(page)
    with open(f"page_{i+1}.pdf", "wb") as output:
        writer.write(output)

Extract Metadata

reader = PdfReader("document.pdf")
meta = reader.metadata
print(f"Title: {meta.title}")
print(f"Author: {meta.author}")
print(f"Subject: {meta.subject}")
print(f"Creator: {meta.creator}")

Rotate Pages

reader = PdfReader("input.pdf")
writer = PdfWriter()

page = reader.pages[0]
page.rotate(90)  # Rotate 90 degrees clockwise
writer.add_page(page)

with open("rotated.pdf", "wb") as output:
    writer.write(output)

pdfplumber - Text and Table Extraction

Extract Text with Layout

import pdfplumber

with pdfplumber.open("document.pdf") as pdf:
    for page in pdf.pages:
        text = page.extract_text()
        print(text)

Extract Tables

with pdfplumber.open("document.pdf") as pdf:
    for i, page in enumerate(pdf.pages):
        tables = page.extract_tables()
        for j, table in enumerate(tables):
            print(f"Table {j+1} on page {i+1}:")
            for row in table:
                print(row)

Advanced Table Extraction

import pandas as pd

with pdfplumber.open("document.pdf") as pdf:
    all_tables = []
    for page in pdf.pages:
        tables = page.extract_tables()
        for table in tables:
            if table:  # Check if table is not empty
                df = pd.DataFrame(table[1:], columns=table[0])
                all_tables.append(df)

# Combine all tables
if all_tables:
    combined_df = pd.concat(all_tables, ignore_index=True)
    combined_df.to_excel("extracted_tables.xlsx", index=False)

reportlab - Create PDFs

Basic PDF Creation

from reportlab.lib.pagesizes import letter
from reportlab.pdfgen import canvas

c = canvas.Canvas("hello.pdf", pagesize=letter)
width, height = letter

# Add text
c.drawString(100, height - 100, "Hello World!")
c.drawString(100, height - 120, "This is a PDF created with reportlab")

# Add a line
c.line(100, height - 140, 400, height - 140)

# Save
c.save()

Create PDF with Multiple Pages

from reportlab.lib.pagesizes import letter
from reportlab.platypus import SimpleDocTemplate, Paragraph, Spacer, PageBreak
from reportlab.lib.styles import getSampleStyleSheet

doc = SimpleDocTemplate("report.pdf", pagesize=letter)
styles = getSampleStyleSheet()
story = []

# Add content
title = Paragraph("Report Title", styles['Title'])
story.append(title)
story.append(Spacer(1, 12))

body = Paragraph("This is the body of the report. " * 20, styles['Normal'])
story.append(body)
story.append(PageBreak())

# Page 2
story.append(Paragraph("Page 2", styles['Heading1']))
story.append(Paragraph("Content for page 2", styles['Normal']))

# Build PDF
doc.build(story)

Command-Line Tools

pdftotext (poppler-utils)

# Extract text
pdftotext input.pdf output.txt

# Extract text preserving layout
pdftotext -layout input.pdf output.txt

# Extract specific pages
pdftotext -f 1 -l 5 input.pdf output.txt  # Pages 1-5

qpdf

# Merge PDFs
qpdf --empty --pages file1.pdf file2.pdf -- merged.pdf

# Split pages
qpdf input.pdf --pages . 1-5 -- pages1-5.pdf
qpdf input.pdf --pages . 6-10 -- pages6-10.pdf

# Rotate pages
qpdf input.pdf output.pdf --rotate=+90:1  # Rotate page 1 by 90 degrees

# Remove password
qpdf --password=mypassword --decrypt encrypted.pdf decrypted.pdf

pdftk (if available)

# Merge
pdftk file1.pdf file2.pdf cat output merged.pdf

# Split
pdftk input.pdf burst

# Rotate
pdftk input.pdf rotate 1east output rotated.pdf

Common Tasks

Extract Text from Scanned PDFs

# Requires: pip install pytesseract pdf2image
import pytesseract
from pdf2image import convert_from_path

# Convert PDF to images
images = convert_from_path('scanned.pdf')

# OCR each page
text = ""
for i, image in enumerate(images):
    text += f"Page {i+1}:\n"
    text += pytesseract.image_to_string(image)
    text += "\n\n"

print(text)

Add Watermark

from pypdf import PdfReader, PdfWriter

# Create watermark (or load existing)
watermark = PdfReader("watermark.pdf").pages[0]

# Apply to all pages
reader = PdfReader("document.pdf")
writer = PdfWriter()

for page in reader.pages:
    page.merge_page(watermark)
    writer.add_page(page)

with open("watermarked.pdf", "wb") as output:
    writer.write(output)

Extract Images

# Using pdfimages (poppler-utils)
pdfimages -j input.pdf output_prefix

# This extracts all images as output_prefix-000.jpg, output_prefix-001.jpg, etc.

Password Protection

from pypdf import PdfReader, PdfWriter

reader = PdfReader("input.pdf")
writer = PdfWriter()

for page in reader.pages:
    writer.add_page(page)

# Add password
writer.encrypt("userpassword", "ownerpassword")

with open("encrypted.pdf", "wb") as output:
    writer.write(output)

Quick Reference

Next Steps

• For advanced pypdfium2 usage, see reference.md
• For JavaScript libraries (pdf-lib), see reference.md
• If you need to fill out a PDF form, follow the instructions in forms.md
• For troubleshooting guides, see reference.md

PPTX creation, editing, and analysis

Overview

A user may ask you to create, edit, or analyze the contents of a .pptx file. A .pptx file is essentially a ZIP archive containing XML files and other resources that you can read or edit. You have different tools and workflows available for different tasks.

Reading and analyzing content

Text extraction

If you just need to read the text contents of a presentation, you should convert the document to markdown:

# Convert document to markdown
python -m markitdown path-to-file.pptx

Raw XML access

You need raw XML access for: comments, speaker notes, slide layouts, animations, design elements, and complex formatting. For any of these features, you'll need to unpack a presentation and read its raw XML contents.

Unpacking a file

python ooxml/scripts/unpack.py <office_file> <output_dir>

Note: The unpack.py script is located at skills/pptx/ooxml/scripts/unpack.py relative to the project root. If the script doesn't exist at this path, use find . -name "unpack.py" to locate it.

Key file structures

• ppt/presentation.xml - Main presentation metadata and slide references
• ppt/slides/slide{N}.xml - Individual slide contents (slide1.xml, slide2.xml, etc.)
• ppt/notesSlides/notesSlide{N}.xml - Speaker notes for each slide
• ppt/comments/modernComment_*.xml - Comments for specific slides
• ppt/slideLayouts/ - Layout templates for slides
• ppt/slideMasters/ - Master slide templates
• ppt/theme/ - Theme and styling information
• ppt/media/ - Images and other media files

Typography and color extraction

When given an example design to emulate: Always analyze the presentation's typography and colors first using the methods below:

1. Read theme file: Check ppt/theme/theme1.xml for colors (<a:clrScheme>) and fonts (<a:fontScheme>)
2. Sample slide content: Examine ppt/slides/slide1.xml for actual font usage (<a:rPr>) and colors
3. Search for patterns: Use grep to find color (<a:solidFill>, <a:srgbClr>) and font references across all XML files

Creating a new PowerPoint presentation without a template

When creating a new PowerPoint presentation from scratch, use the html2pptx workflow to convert HTML slides to PowerPoint with accurate positioning.

Design Principles

CRITICAL: Before creating any presentation, analyze the content and choose appropriate design elements:

1. Consider the subject matter: What is this presentation about? What tone, industry, or mood does it suggest?
2. Check for branding: If the user mentions a company/organization, consider their brand colors and identity
3. Match palette to content: Select colors that reflect the subject
4. State your approach: Explain your design choices before writing code

Requirements:

• ✅ State your content-informed design approach BEFORE writing code
• ✅ Use web-safe fonts only: Arial, Helvetica, Times New Roman, Georgia, Courier New, Verdana, Tahoma, Trebuchet MS, Impact
• ✅ Create clear visual hierarchy through size, weight, and color
• ✅ Ensure readability: strong contrast, appropriately sized text, clean alignment
• ✅ Be consistent: repeat patterns, spacing, and visual language across slides

Color Palette Selection

Choosing colors creatively:

• Think beyond defaults: What colors genuinely match this specific topic? Avoid autopilot choices.
• Consider multiple angles: Topic, industry, mood, energy level, target audience, brand identity (if mentioned)
• Be adventurous: Try unexpected combinations - a healthcare presentation doesn't have to be green, finance doesn't have to be navy
• Build your palette: Pick 3-5 colors that work together (dominant colors + supporting tones + accent)
• Ensure contrast: Text must be clearly readable on backgrounds

Example color palettes (use these to spark creativity - choose one, adapt it, or create your own):

1. Classic Blue: Deep navy (#1C2833), slate gray (#2E4053), silver (#AAB7B8), off-white (#F4F6F6)
2. Teal & Coral: Teal (#5EA8A7), deep teal (#277884), coral (#FE4447), white (#FFFFFF)
3. Bold Red: Red (#C0392B), bright red (#E74C3C), orange (#F39C12), yellow (#F1C40F), green (#2ECC71)
4. Warm Blush: Mauve (#A49393), blush (#EED6D3), rose (#E8B4B8), cream (#FAF7F2)
5. Burgundy Luxury: Burgundy (#5D1D2E), crimson (#951233), rust (#C15937), gold (#997929)
6. Deep Purple & Emerald: Purple (#B165FB), dark blue (#181B24), emerald (#40695B), white (#FFFFFF)
7. Cream & Forest Green: Cream (#FFE1C7), forest green (#40695B), white (#FCFCFC)
8. Pink & Purple: Pink (#F8275B), coral (#FF574A), rose (#FF737D), purple (#3D2F68)
9. Lime & Plum: Lime (#C5DE82), plum (#7C3A5F), coral (#FD8C6E), blue-gray (#98ACB5)
10. Black & Gold: Gold (#BF9A4A), black (#000000), cream (#F4F6F6)
11. Sage & Terracotta: Sage (#87A96B), terracotta (#E07A5F), cream (#F4F1DE), charcoal (#2C2C2C)
12. Charcoal & Red: Charcoal (#292929), red (#E33737), light gray (#CCCBCB)
13. Vibrant Orange: Orange (#F96D00), light gray (#F2F2F2), charcoal (#222831)
14. Forest Green: Black (#191A19), green (#4E9F3D), dark green (#1E5128), white (#FFFFFF)
15. Retro Rainbow: Purple (#722880), pink (#D72D51), orange (#EB5C18), amber (#F08800), gold (#DEB600)
16. Vintage Earthy: Mustard (#E3B448), sage (#CBD18F), forest green (#3A6B35), cream (#F4F1DE)
17. Coastal Rose: Old rose (#AD7670), beaver (#B49886), eggshell (#F3ECDC), ash gray (#BFD5BE)
18. Orange & Turquoise: Light orange (#FC993E), grayish turquoise (#667C6F), white (#FCFCFC)

Visual Details Options

Geometric Patterns:

• Diagonal section dividers instead of horizontal
• Asymmetric column widths (30/70, 40/60, 25/75)
• Rotated text headers at 90° or 270°
• Circular/hexagonal frames for images
• Triangular accent shapes in corners
• Overlapping shapes for depth

Border & Frame Treatments:

• Thick single-color borders (10-20pt) on one side only
• Double-line borders with contrasting colors
• Corner brackets instead of full frames
• L-shaped borders (top+left or bottom+right)
• Underline accents beneath headers (3-5pt thick)

Typography Treatments:

• Extreme size contrast (72pt headlines vs 11pt body)
• All-caps headers with wide letter spacing
• Numbered sections in oversized display type
• Monospace (Courier New) for data/stats/technical content
• Condensed fonts (Arial Narrow) for dense information
• Outlined text for emphasis

Chart & Data Styling:

• Monochrome charts with single accent color for key data
• Horizontal bar charts instead of vertical
• Dot plots instead of bar charts
• Minimal gridlines or none at all
• Data labels directly on elements (no legends)
• Oversized numbers for key metrics

Layout Innovations:

• Full-bleed images with text overlays
• Sidebar column (20-30% width) for navigation/context
• Modular grid systems (3×3, 4×4 blocks)
• Z-pattern or F-pattern content flow
• Floating text boxes over colored shapes
• Magazine-style multi-column layouts

Background Treatments:

• Solid color blocks occupying 40-60% of slide
• Gradient fills (vertical or diagonal only)
• Split backgrounds (two colors, diagonal or vertical)
• Edge-to-edge color bands
• Negative space as a design element

Layout Tips

When creating slides with charts or tables:

• Two-column layout (PREFERRED): Use a header spanning the full width, then two columns below - text/bullets in one column and the featured content in the other. This provides better balance and makes charts/tables more readable. Use flexbox with unequal column widths (e.g., 40%/60% split) to optimize space for each content type.
• Full-slide layout: Let the featured content (chart/table) take up the entire slide for maximum impact and readability
• NEVER vertically stack: Do not place charts/tables below text in a single column - this causes poor readability and layout issues

Workflow

1. MANDATORY - READ ENTIRE FILE: Read html2pptx.md completely from start to finish. NEVER set any range limits when reading this file. Read the full file content for detailed syntax, critical formatting rules, and best practices before proceeding with presentation creation.
2. Create an HTML file for each slide with proper dimensions (e.g., 720pt × 405pt for 16:9)
   • Use <p>, <h1>-<h6>, <ul>, <ol> for all text content
   • Use class="placeholder" for areas where charts/tables will be added (render with gray background for visibility)
   • CRITICAL: Rasterize gradients and icons as PNG images FIRST using Sharp, then reference in HTML
   • LAYOUT: For slides with charts/tables/images, use either full-slide layout or two-column layout for better readability
3. Create and run a JavaScript file using the html2pptx.js library to convert HTML slides to PowerPoint and save the presentation
   • Use the html2pptx() function to process each HTML file
   • Add charts and tables to placeholder areas using PptxGenJS API
   • Save the presentation using pptx.writeFile()
4. Visual validation: Generate thumbnails and inspect for layout issues
   • Create thumbnail grid: python scripts/thumbnail.py output.pptx workspace/thumbnails --cols 4
   • Read and carefully examine the thumbnail image for:
     • Text cutoff: Text being cut off by header bars, shapes, or slide edges
     • Text overlap: Text overlapping with other text or shapes
     • Positioning issues: Content too close to slide boundaries or other elements
     • Contrast issues: Insufficient contrast between text and backgrounds
   • If issues found, adjust HTML margins/spacing/colors and regenerate the presentation
   • Repeat until all slides are visually correct

Editing an existing PowerPoint presentation

When edit slides in an existing PowerPoint presentation, you need to work with the raw Office Open XML (OOXML) format. This involves unpacking the .pptx file, editing the XML content, and repacking it.

Workflow

1. MANDATORY - READ ENTIRE FILE: Read ooxml.md (~500 lines) completely from start to finish. NEVER set any range limits when reading this file. Read the full file content for detailed guidance on OOXML structure and editing workflows before any presentation editing.
2. Unpack the presentation: python ooxml/scripts/unpack.py <office_file> <output_dir>
3. Edit the XML files (primarily ppt/slides/slide{N}.xml and related files)
4. CRITICAL: Validate immediately after each edit and fix any validation errors before proceeding: python ooxml/scripts/validate.py <dir> --original <file>
5. Pack the final presentation: python ooxml/scripts/pack.py <input_directory> <office_file>

Creating a new PowerPoint presentation using a template

When you need to create a presentation that follows an existing template's design, you'll need to duplicate and re-arrange template slides before then replacing placeholder context.

Workflow

1. Extract template text AND create visual thumbnail grid:

   • Extract text: python -m markitdown template.pptx > template-content.md
   • Read template-content.md: Read the entire file to understand the contents of the template presentation. NEVER set any range limits when reading this file.
   • Create thumbnail grids: python scripts/thumbnail.py template.pptx
   • See Creating Thumbnail Grids section for more details

2. Analyze template and save inventory to a file:

   • Visual Analysis: Review thumbnail grid(s) to understand slide layouts, design patterns, and visual structure
   • Create and save a template inventory file at template-inventory.md containing:

     # Template Inventory Analysis
     **Total Slides: [count]**
     **IMPORTANT: Slides are 0-indexed (first slide = 0, last slide = count-1)**
     
     ## [Category Name]
     - Slide 0: [Layout code if available] - Description/purpose
     - Slide 1: [Layout code] - Description/purpose
     - Slide 2: [Layout code] - Description/purpose
     [... EVERY slide must be listed individually with its index ...]
     

   • Using the thumbnail grid: Reference the visual thumbnails to identify:
     • Layout patterns (title slides, content layouts, section dividers)
     • Image placeholder locations and counts
     • Design consistency across slide groups
     • Visual hierarchy and structure
   • This inventory file is REQUIRED for selecting appropriate templates in the next step

3. Create presentation outline based on template inventory:

   • Review available templates from step 2.
   • Choose an intro or title template for the first slide. This should be one of the first templates.
   • Choose safe, text-based layouts for the other slides.
   • CRITICAL: Match layout structure to actual content:
     • Single-column layouts: Use for unified narrative or single topic
     • Two-column layouts: Use ONLY when you have exactly 2 distinct items/concepts
     • Three-column layouts: Use ONLY when you have exactly 3 distinct items/concepts
     • Image + text layouts: Use ONLY when you have actual images to insert
     • Quote layouts: Use ONLY for actual quotes from people (with attribution), never for emphasis
     • Never use layouts with more placeholders than you have content
     • If you have 2 items, don't force them into a 3-column layout
     • If you have 4+ items, consider breaking into multiple slides or using a list format
   • Count your actual content pieces BEFORE selecting the layout
   • Verify each placeholder in the chosen layout will be filled with meaningful content
   • Select one option representing the best layout for each content section.
   • Save outline.md with content AND template mapping that leverages available designs
   • Example template mapping:

     # Template slides to use (0-based indexing)
     # WARNING: Verify indices are within range! Template with 73 slides has indices 0-72
     # Mapping: slide numbers from outline -> template slide indices
     template_mapping = [
         0,   # Use slide 0 (Title/Cover)
         34,  # Use slide 34 (B1: Title and body)
         34,  # Use slide 34 again (duplicate for second B1)
         50,  # Use slide 50 (E1: Quote)
         54,  # Use slide 54 (F2: Closing + Text)
     ]
     

4. Duplicate, reorder, and delete slides using rearrange.py:

   • Use the scripts/rearrange.py script to create a new presentation with slides in the desired order:

     python scripts/rearrange.py template.pptx working.pptx 0,34,34,50,52
     

   • The script handles duplicating repeated slides, deleting unused slides, and reordering automatically
   • Slide indices are 0-based (first slide is 0, second is 1, etc.)
   • The same slide index can appear multiple times to duplicate that slide

5. Extract ALL text using the inventory.py script:

   • Run inventory extraction:

     python scripts/inventory.py working.pptx text-inventory.json
     

   • Read text-inventory.json: Read the entire text-inventory.json file to understand all shapes and their properties. NEVER set any range limits when reading this file.

   • The inventory JSON structure:

       {
         "slide-0": {
           "shape-0": {
             "placeholder_type": "TITLE",  // or null for non-placeholders
             "left": 1.5,                  // position in inches
             "top": 2.0,
             "width": 7.5,
             "height": 1.2,
             "paragraphs": [
               {
                 "text": "Paragraph text",
                 // Optional properties (only included when non-default):
                 "bullet": true,           // explicit bullet detected
                 "level": 0,               // only included when bullet is true
                 "alignment": "CENTER",    // CENTER, RIGHT (not LEFT)
                 "space_before": 10.0,     // space before paragraph in points
                 "space_after": 6.0,       // space after paragraph in points
                 "line_spacing": 22.4,     // line spacing in points
                 "font_name": "Arial",     // from first run
                 "font_size": 14.0,        // in points
                 "bold": true,
                 "italic": false,
                 "underline": false,
                 "color": "FF0000"         // RGB color
               }
             ]
           }
         }
       }
     

   • Key features:

     • Slides: Named as "slide-0", "slide-1", etc.
     • Shapes: Ordered by visual position (top-to-bottom, left-to-right) as "shape-0", "shape-1", etc.
     • Placeholder types: TITLE, CENTER_TITLE, SUBTITLE, BODY, OBJECT, or null
     • Default font size: default_font_size in points extracted from layout placeholders (when available)
     • Slide numbers are filtered: Shapes with SLIDE_NUMBER placeholder type are automatically excluded from inventory
     • Bullets: When bullet: true, level is always included (even if 0)
     • Spacing: space_before, space_after, and line_spacing in points (only included when set)
     • Colors: color for RGB (e.g., "FF0000"), theme_color for theme colors (e.g., "DARK_1")
     • Properties: Only non-default values are included in the output

6. Generate replacement text and save the data to a JSON file Based on the text inventory from the previous step:

   • CRITICAL: First verify which shapes exist in the inventory - only reference shapes that are actually present
   • VALIDATION: The replace.py script will validate that all shapes in your replacement JSON exist in the inventory
     • If you reference a non-existent shape, you'll get an error showing available shapes
     • If you reference a non-existent slide, you'll get an error indicating the slide doesn't exist
     • All validation errors are shown at once before the script exits
   • IMPORTANT: The replace.py script uses inventory.py internally to identify ALL text shapes
   • AUTOMATIC CLEARING: ALL text shapes from the inventory will be cleared unless you provide "paragraphs" for them
   • Add a "paragraphs" field to shapes that need content (not "replacement_paragraphs")
   • Shapes without "paragraphs" in the replacement JSON will have their text cleared automatically
   • Paragraphs with bullets will be automatically left aligned. Don't set the alignment property on when "bullet": true
   • Generate appropriate replacement content for placeholder text
   • Use shape size to determine appropriate content length
   • CRITICAL: Include paragraph properties from the original inventory - don't just provide text
   • IMPORTANT: When bullet: true, do NOT include bullet symbols (•, -, *) in text - they're added automatically
   • ESSENTIAL FORMATTING RULES:
     • Headers/titles should typically have "bold": true
     • List items should have "bullet": true, "level": 0 (level is required when bullet is true)
     • Preserve any alignment properties (e.g., "alignment": "CENTER" for centered text)
     • Include font properties when different from default (e.g., "font_size": 14.0, "font_name": "Lora")
     • Colors: Use "color": "FF0000" for RGB or "theme_color": "DARK_1" for theme colors
     • The replacement script expects properly formatted paragraphs, not just text strings
     • Overlapping shapes: Prefer shapes with larger default_font_size or more appropriate placeholder_type
   • Save the updated inventory with replacements to replacement-text.json
   • WARNING: Different template layouts have different shape counts - always check the actual inventory before creating replacements

   Example paragraphs field showing proper formatting:

   "paragraphs": [
     {
       "text": "New presentation title text",
       "alignment": "CENTER",
       "bold": true
     },
     {
       "text": "Section Header",
       "bold": true
     },
     {
       "text": "First bullet point without bullet symbol",
       "bullet": true,
       "level": 0
     },
     {
       "text": "Red colored text",
       "color": "FF0000"
     },
     {
       "text": "Theme colored text",
       "theme_color": "DARK_1"
     },
     {
       "text": "Regular paragraph text without special formatting"
     }
   ]
   

   Shapes not listed in the replacement JSON are automatically cleared:

   {
     "slide-0": {
       "shape-0": {
         "paragraphs": [...] // This shape gets new text
       }
       // shape-1 and shape-2 from inventory will be cleared automatically
     }
   }
   

   Common formatting patterns for presentations:

   • Title slides: Bold text, sometimes centered
   • Section headers within slides: Bold text
   • Bullet lists: Each item needs "bullet": true, "level": 0
   • Body text: Usually no special properties needed
   • Quotes: May have special alignment or font properties

7. Apply replacements using the replace.py script

   python scripts/replace.py working.pptx replacement-text.json output.pptx
   

   The script will:

   • First extract the inventory of ALL text shapes using functions from inventory.py
   • Validate that all shapes in the replacement JSON exist in the inventory
   • Clear text from ALL shapes identified in the inventory
   • Apply new text only to shapes with "paragraphs" defined in the replacement JSON
   • Preserve formatting by applying paragraph properties from the JSON
   • Handle bullets, alignment, font properties, and colors automatically
   • Save the updated presentation

   Example validation errors:

   ERROR: Invalid shapes in replacement JSON:
     - Shape 'shape-99' not found on 'slide-0'. Available shapes: shape-0, shape-1, shape-4
     - Slide 'slide-999' not found in inventory
   

   ERROR: Replacement text made overflow worse in these shapes:
     - slide-0/shape-2: overflow worsened by 1.25" (was 0.00", now 1.25")
   

Creating Thumbnail Grids

To create visual thumbnail grids of PowerPoint slides for quick analysis and reference:

python scripts/thumbnail.py template.pptx [output_prefix]

Features:

• Creates: thumbnails.jpg (or thumbnails-1.jpg, thumbnails-2.jpg, etc. for large decks)
• Default: 5 columns, max 30 slides per grid (5×6)
• Custom prefix: python scripts/thumbnail.py template.pptx my-grid
  • Note: The output prefix should include the path if you want output in a specific directory (e.g., workspace/my-grid)
• Adjust columns: --cols 4 (range: 3-6, affects slides per grid)
• Grid limits: 3 cols = 12 slides/grid, 4 cols = 20, 5 cols = 30, 6 cols = 42
• Slides are zero-indexed (Slide 0, Slide 1, etc.)

Use cases:

• Template analysis: Quickly understand slide layouts and design patterns
• Content review: Visual overview of entire presentation
• Navigation reference: Find specific slides by their visual appearance
• Quality check: Verify all slides are properly formatted

Examples:

# Basic usage
python scripts/thumbnail.py presentation.pptx

# Combine options: custom name, columns
python scripts/thumbnail.py template.pptx analysis --cols 4

Converting Slides to Images

To visually analyze PowerPoint slides, convert them to images using a two-step process:

1. Convert PPTX to PDF:

   soffice --headless --convert-to pdf template.pptx
   

2. Convert PDF pages to JPEG images:

   pdftoppm -jpeg -r 150 template.pdf slide
   

   This creates files like slide-1.jpg, slide-2.jpg, etc.

Options:

• -r 150: Sets resolution to 150 DPI (adjust for quality/size balance)
• -jpeg: Output JPEG format (use -png for PNG if preferred)
• -f N: First page to convert (e.g., -f 2 starts from page 2)
• -l N: Last page to convert (e.g., -l 5 stops at page 5)
• slide: Prefix for output files

Example for specific range:

pdftoppm -jpeg -r 150 -f 2 -l 5 template.pdf slide  # Converts only pages 2-5

Code Style Guidelines

IMPORTANT: When generating code for PPTX operations:

• Write concise code
• Avoid verbose variable names and redundant operations
• Avoid unnecessary print statements

Dependencies

Required dependencies (should already be installed):

• markitdown: pip install "markitdown[pptx]" (for text extraction from presentations)
• pptxgenjs: npm install -g pptxgenjs (for creating presentations via html2pptx)
• playwright: npm install -g playwright (for HTML rendering in html2pptx)
• react-icons: npm install -g react-icons react react-dom (for icons)
• sharp: npm install -g sharp (for SVG rasterization and image processing)
• LibreOffice: sudo apt-get install libreoffice (for PDF conversion)
• Poppler: sudo apt-get install poppler-utils (for pdftoppm to convert PDF to images)
• defusedxml: pip install defusedxml (for secure XML parsing)

Requirements for Outputs

All Excel files

Zero Formula Errors

• Every Excel model MUST be delivered with ZERO formula errors (#REF!, #DIV/0!, #VALUE!, #N/A, #NAME?)

Preserve Existing Templates (when updating templates)

• Study and EXACTLY match existing format, style, and conventions when modifying files
• Never impose standardized formatting on files with established patterns
• Existing template conventions ALWAYS override these guidelines

Financial models

Color Coding Standards

Unless otherwise stated by the user or existing template

Industry-Standard Color Conventions

• Blue text (RGB: 0,0,255): Hardcoded inputs, and numbers users will change for scenarios
• Black text (RGB: 0,0,0): ALL formulas and calculations
• Green text (RGB: 0,128,0): Links pulling from other worksheets within same workbook
• Red text (RGB: 255,0,0): External links to other files
• Yellow background (RGB: 255,255,0): Key assumptions needing attention or cells that need to be updated

Number Formatting Standards

Required Format Rules

• Years: Format as text strings (e.g., "2024" not "2,024")
• Currency: Use $#,##0 format; ALWAYS specify units in headers ("Revenue ($mm)")
• Zeros: Use number formatting to make all zeros "-", including percentages (e.g., "$#,##0;($#,##0);-")
• Percentages: Default to 0.0% format (one decimal)
• Multiples: Format as 0.0x for valuation multiples (EV/EBITDA, P/E)
• Negative numbers: Use parentheses (123) not minus -123

Formula Construction Rules

Assumptions Placement

• Place ALL assumptions (growth rates, margins, multiples, etc.) in separate assumption cells
• Use cell references instead of hardcoded values in formulas
• Example: Use =B5*(1+$B$6) instead of =B5*1.05

Formula Error Prevention

• Verify all cell references are correct
• Check for off-by-one errors in ranges
• Ensure consistent formulas across all projection periods
• Test with edge cases (zero values, negative numbers)
• Verify no unintended circular references

Documentation Requirements for Hardcodes

• Comment or in cells beside (if end of table). Format: "Source: [System/Document], [Date], [Specific Reference], [URL if applicable]"
• Examples:
  • "Source: Company 10-K, FY2024, Page 45, Revenue Note, [SEC EDGAR URL]"
  • "Source: Company 10-Q, Q2 2025, Exhibit 99.1, [SEC EDGAR URL]"
  • "Source: Bloomberg Terminal, 8/15/2025, AAPL US Equity"
  • "Source: FactSet, 8/20/2025, Consensus Estimates Screen"

XLSX creation, editing, and analysis

Overview

A user may ask you to create, edit, or analyze the contents of an .xlsx file. You have different tools and workflows available for different tasks.

Important Requirements

LibreOffice Required for Formula Recalculation: You can assume LibreOffice is installed for recalculating formula values using the recalc.py script. The script automatically configures LibreOffice on first run

Reading and analyzing data

Data analysis with pandas

For data analysis, visualization, and basic operations, use pandas which provides powerful data manipulation capabilities:

import pandas as pd

# Read Excel
df = pd.read_excel('file.xlsx')  # Default: first sheet
all_sheets = pd.read_excel('file.xlsx', sheet_name=None)  # All sheets as dict

# Analyze
df.head()      # Preview data
df.info()      # Column info
df.describe()  # Statistics

# Write Excel
df.to_excel('output.xlsx', index=False)

Excel File Workflows

CRITICAL: Use Formulas, Not Hardcoded Values

Always use Excel formulas instead of calculating values in Python and hardcoding them. This ensures the spreadsheet remains dynamic and updateable.

❌ WRONG - Hardcoding Calculated Values

# Bad: Calculating in Python and hardcoding result
total = df['Sales'].sum()
sheet['B10'] = total  # Hardcodes 5000

# Bad: Computing growth rate in Python
growth = (df.iloc[-1]['Revenue'] - df.iloc[0]['Revenue']) / df.iloc[0]['Revenue']
sheet['C5'] = growth  # Hardcodes 0.15

# Bad: Python calculation for average
avg = sum(values) / len(values)
sheet['D20'] = avg  # Hardcodes 42.5

✅ CORRECT - Using Excel Formulas

# Good: Let Excel calculate the sum
sheet['B10'] = '=SUM(B2:B9)'

# Good: Growth rate as Excel formula
sheet['C5'] = '=(C4-C2)/C2'

# Good: Average using Excel function
sheet['D20'] = '=AVERAGE(D2:D19)'

This applies to ALL calculations - totals, percentages, ratios, differences, etc. The spreadsheet should be able to recalculate when source data changes.

Common Workflow

1. Choose tool: pandas for data, openpyxl for formulas/formatting
2. Create/Load: Create new workbook or load existing file
3. Modify: Add/edit data, formulas, and formatting
4. Save: Write to file
5. Recalculate formulas (MANDATORY IF USING FORMULAS): Use the recalc.py script

   python recalc.py output.xlsx
   

6. Verify and fix any errors:
   • The script returns JSON with error details
   • If status is errors_found, check error_summary for specific error types and locations
   • Fix the identified errors and recalculate again
   • Common errors to fix:
     • #REF!: Invalid cell references
     • #DIV/0!: Division by zero
     • #VALUE!: Wrong data type in formula
     • #NAME?: Unrecognized formula name

Creating new Excel files

# Using openpyxl for formulas and formatting
from openpyxl import Workbook
from openpyxl.styles import Font, PatternFill, Alignment

wb = Workbook()
sheet = wb.active

# Add data
sheet['A1'] = 'Hello'
sheet['B1'] = 'World'
sheet.append(['Row', 'of', 'data'])

# Add formula
sheet['B2'] = '=SUM(A1:A10)'

# Formatting
sheet['A1'].font = Font(bold=True, color='FF0000')
sheet['A1'].fill = PatternFill('solid', start_color='FFFF00')
sheet['A1'].alignment = Alignment(horizontal='center')

# Column width
sheet.column_dimensions['A'].width = 20

wb.save('output.xlsx')

Editing existing Excel files

# Using openpyxl to preserve formulas and formatting
from openpyxl import load_workbook

# Load existing file
wb = load_workbook('existing.xlsx')
sheet = wb.active  # or wb['SheetName'] for specific sheet

# Working with multiple sheets
for sheet_name in wb.sheetnames:
    sheet = wb[sheet_name]
    print(f"Sheet: {sheet_name}")

# Modify cells
sheet['A1'] = 'New Value'
sheet.insert_rows(2)  # Insert row at position 2
sheet.delete_cols(3)  # Delete column 3

# Add new sheet
new_sheet = wb.create_sheet('NewSheet')
new_sheet['A1'] = 'Data'

wb.save('modified.xlsx')

Recalculating formulas

Excel files created or modified by openpyxl contain formulas as strings but not calculated values. Use the provided recalc.py script to recalculate formulas:

python recalc.py <excel_file> [timeout_seconds]

Example:

python recalc.py output.xlsx 30

The script:

• Automatically sets up LibreOffice macro on first run
• Recalculates all formulas in all sheets
• Scans ALL cells for Excel errors (#REF!, #DIV/0!, etc.)
• Returns JSON with detailed error locations and counts
• Works on both Linux and macOS

Formula Verification Checklist

Quick checks to ensure formulas work correctly:

Essential Verification

• Test 2-3 sample references: Verify they pull correct values before building full model
• Column mapping: Confirm Excel columns match (e.g., column 64 = BL, not BK)
• Row offset: Remember Excel rows are 1-indexed (DataFrame row 5 = Excel row 6)

Common Pitfalls

• NaN handling: Check for null values with pd.notna()
• Far-right columns: FY data often in columns 50+
• Multiple matches: Search all occurrences, not just first
• Division by zero: Check denominators before using / in formulas (#DIV/0!)
• Wrong references: Verify all cell references point to intended cells (#REF!)
• Cross-sheet references: Use correct format (Sheet1!A1) for linking sheets

Formula Testing Strategy

• Start small: Test formulas on 2-3 cells before applying broadly
• Verify dependencies: Check all cells referenced in formulas exist
• Test edge cases: Include zero, negative, and very large values

Interpreting recalc.py Output

The script returns JSON with error details:

{
  "status": "success",           // or "errors_found"
  "total_errors": 0,              // Total error count
  "total_formulas": 42,           // Number of formulas in file
  "error_summary": {              // Only present if errors found
    "#REF!": {
      "count": 2,
      "locations": ["Sheet1!B5", "Sheet1!C10"]
    }
  }
}

Best Practices

Library Selection

• pandas: Best for data analysis, bulk operations, and simple data export
• openpyxl: Best for complex formatting, formulas, and Excel-specific features

Working with openpyxl

• Cell indices are 1-based (row=1, column=1 refers to cell A1)
• Use data_only=True to read calculated values: load_workbook('file.xlsx', data_only=True)
• Warning: If opened with data_only=True and saved, formulas are replaced with values and permanently lost
• For large files: Use read_only=True for reading or write_only=True for writing
• Formulas are preserved but not evaluated - use recalc.py to update values

Working with pandas

• Specify data types to avoid inference issues: pd.read_excel('file.xlsx', dtype={'id': str})
• For large files, read specific columns: pd.read_excel('file.xlsx', usecols=['A', 'C', 'E'])
• Handle dates properly: pd.read_excel('file.xlsx', parse_dates=['date_column'])

Code Style Guidelines

IMPORTANT: When generating Python code for Excel operations:

• Write minimal, concise Python code without unnecessary comments
• Avoid verbose variable names and redundant operations
• Avoid unnecessary print statements

For Excel files themselves:

• Add comments to cells with complex formulas or important assumptions
• Document data sources for hardcoded values
• Include notes for key calculations and model sections

Domain Name Brainstormer

This skill helps you find the perfect domain name for your project by generating creative options and checking what's actually available to register.

When to Use This Skill

• Starting a new project or company
• Launching a product or service
• Creating a personal brand or portfolio site
• Rebranding an existing project
• Registering a domain for a side project
• Finding available alternatives when your first choice is taken

What This Skill Does

1. Understands Your Project: Analyzes what you're building and who it's for
2. Generates Creative Names: Creates relevant, memorable domain options
3. Checks Availability: Verifies which domains are actually available across multiple TLDs
4. Multiple Extensions: Suggests .com, .io, .dev, .ai, .app, and more
5. Provides Alternatives: Offers variations if top choices are taken
6. Branding Insights: Explains why certain names work well

How to Use

Basic Brainstorming

I'm building a project management tool for remote teams. 
Suggest domain names.

Help me brainstorm domain names for a personal finance app

Specific Preferences

I need a domain name for my AI writing assistant. 
Prefer short names with .ai or .io extension.

With Keywords

Suggest domain names using the words "pixel" or "studio" 
for my design agency

Example

User: "I'm building a tool for developers to share code snippets. Suggest creative domain names."

Output:

Analyzing your project...
Target audience: Developers
Key features: Code sharing, snippets, collaboration

🎯 Domain Name Suggestions

## Available (.com)
1. ✓ snippetbox.com - Clear, memorable, available!
   Why: Directly describes the product, easy to remember

2. ✓ codeclip.com - Short and snappy
   Why: Implies quick code sharing, only 8 characters

3. ✓ devpaste.com - Developer-focused
   Why: Familiar to devs (like pastebin), clear purpose

## Available (Alternative TLDs)
4. ✓ snippet.dev - Perfect extension for developers
   Why: .dev extension signals developer tool

5. ✓ codebox.io - Tech-forward
   Why: .io popular with tech startups, clean name

6. ✓ sharecode.app - Descriptive
   Why: .app extension, clearly states the action

## Premium/Taken (.com)
- codeshare.com (Taken, est. $2,500)
- snippets.com (Taken, premium domain)

## Recommendations

🏆 Top Pick: snippet.dev
- Perfect for developer audience
- Short and memorable  
- .dev extension adds credibility
- Available now!

🥈 Runner-up: snippetbox.com
- .com is universally recognized
- Slightly longer but descriptive
- Great brandability

Next steps:
1. Register your favorite before someone else does!
2. Want me to check more variations?
3. Need help with logo ideas for these names?

Inspired by: Ben Aiad's use case from Lenny's Newsletter

Domain Naming Tips

What Makes a Good Domain

✓ Short: Under 15 characters ideal ✓ Memorable: Easy to recall and spell ✓ Pronounceable: Can be said in conversation ✓ Descriptive: Hints at what you do ✓ Brandable: Unique enough to stand out ✓ No hyphens: Easier to share verbally

TLD Guide

• .com: Universal, trusted, great for businesses
• .io: Tech startups, developer tools
• .dev: Developer-focused products
• .ai: AI/ML products
• .app: Mobile or web applications
• .co: Alternative to .com
• .xyz: Modern, creative projects
• .design: Creative/design agencies
• .tech: Technology companies

Advanced Features

Check Similar Variations

Check availability for "codebase" and similar variations 
across .com, .io, .dev

Industry-Specific

Suggest domain names for a sustainable fashion brand, 
checking .eco and .fashion TLDs

Multilingual Options

Brainstorm domain names in English and Spanish for 
a language learning app

Competitor Analysis

Show me domain patterns used by successful project 
management tools, then suggest similar available ones

Example Workflows

Startup Launch

1. Describe your startup idea
2. Get 10-15 domain suggestions across TLDs
3. Review availability and pricing
4. Pick top 3 favorites
5. Register immediately

Personal Brand

1. Share your name and profession
2. Get variations (firstname.com, firstnamelastname.dev, etc.)
3. Check social media handle availability too
4. Register consistent brand across platforms

Product Naming

1. Describe product and target market
2. Get creative, brandable names
3. Check trademark conflicts
4. Verify domain and social availability
5. Test names with target audience

Tips for Success

1. Act Fast: Good domains get taken quickly
2. Register Variations: Get .com and .io to protect brand
3. Avoid Numbers: Hard to communicate verbally
4. Check Social Media: Make sure @username is available too
5. Say It Out Loud: Test if it's easy to pronounce
6. Check Trademarks: Ensure no legal conflicts
7. Think Long-term: Will it still make sense in 5 years?

Pricing Context

When suggesting domains, I'll note:

• Standard domains: ~$10-15/year
• Premium TLDs (.io, .ai): ~$30-50/year
• Taken domains: Market price if listed
• Premium domains: $hundreds to $thousands

Related Tools

After picking a domain:

• Check logo design options
• Verify social media handles
• Research trademark availability
• Plan brand identity colors/fonts

File Organizer

This skill acts as your personal organization assistant, helping you maintain a clean, logical file structure across your computer without the mental overhead of constant manual organization.

When to Use This Skill

• Your Downloads folder is a chaotic mess
• You can't find files because they're scattered everywhere
• You have duplicate files taking up space
• Your folder structure doesn't make sense anymore
• You want to establish better organization habits
• You're starting a new project and need a good structure
• You're cleaning up before archiving old projects

What This Skill Does

1. Analyzes Current Structure: Reviews your folders and files to understand what you have
2. Finds Duplicates: Identifies duplicate files across your system
3. Suggests Organization: Proposes logical folder structures based on your content
4. Automates Cleanup: Moves, renames, and organizes files with your approval
5. Maintains Context: Makes smart decisions based on file types, dates, and content
6. Reduces Clutter: Identifies old files you probably don't need anymore

How to Use

From Your Home Directory

cd ~

Then run Claude Code and ask for help:

Help me organize my Downloads folder

Find duplicate files in my Documents folder

Review my project directories and suggest improvements

Specific Organization Tasks

Organize these downloads into proper folders based on what they are

Find duplicate files and help me decide which to keep

Clean up old files I haven't touched in 6+ months

Create a better folder structure for my [work/projects/photos/etc]

Instructions

When a user requests file organization help:

1. Understand the Scope

   Ask clarifying questions:

   • Which directory needs organization? (Downloads, Documents, entire home folder?)
   • What's the main problem? (Can't find things, duplicates, too messy, no structure?)
   • Any files or folders to avoid? (Current projects, sensitive data?)
   • How aggressively to organize? (Conservative vs. comprehensive cleanup)

2. Analyze Current State

   Review the target directory:

   # Get overview of current structure
   ls -la [target_directory]
   
   # Check file types and sizes
   find [target_directory] -type f -exec file {} \; | head -20
   
   # Identify largest files
   du -sh [target_directory]/* | sort -rh | head -20
   
   # Count file types
   find [target_directory] -type f | sed 's/.*\.//' | sort | uniq -c | sort -rn
   

   Summarize findings:

   • Total files and folders
   • File type breakdown
   • Size distribution
   • Date ranges
   • Obvious organization issues

3. Identify Organization Patterns

   Based on the files, determine logical groupings:

   By Type:

   • Documents (PDFs, DOCX, TXT)
   • Images (JPG, PNG, SVG)
   • Videos (MP4, MOV)
   • Archives (ZIP, TAR, DMG)
   • Code/Projects (directories with code)
   • Spreadsheets (XLSX, CSV)
   • Presentations (PPTX, KEY)

   By Purpose:

   • Work vs. Personal
   • Active vs. Archive
   • Project-specific
   • Reference materials
   • Temporary/scratch files

   By Date:

   • Current year/month
   • Previous years
   • Very old (archive candidates)

4. Find Duplicates

   When requested, search for duplicates:

   # Find exact duplicates by hash
   find [directory] -type f -exec md5 {} \; | sort | uniq -d
   
   # Find files with same name
   find [directory] -type f -printf '%f\n' | sort | uniq -d
   
   # Find similar-sized files
   find [directory] -type f -printf '%s %p\n' | sort -n
   

   For each set of duplicates:

   • Show all file paths
   • Display sizes and modification dates
   • Recommend which to keep (usually newest or best-named)
   • Important: Always ask for confirmation before deleting

5. Propose Organization Plan

   Present a clear plan before making changes:

   # Organization Plan for [Directory]
   
   ## Current State
   - X files across Y folders
   - [Size] total
   - File types: [breakdown]
   - Issues: [list problems]
   
   ## Proposed Structure
   
   

   [Directory]/ ├── Work/ │ ├── Projects/ │ ├── Documents/ │ └── Archive/ ├── Personal/ │ ├── Photos/ │ ├── Documents/ │ └── Media/ └── Downloads/ ├── To-Sort/ └── Archive/

   
   ## Changes I'll Make
   
   1. **Create new folders**: [list]
   2. **Move files**:
      - X PDFs → Work/Documents/
      - Y images → Personal/Photos/
      - Z old files → Archive/
   3. **Rename files**: [any renaming patterns]
   4. **Delete**: [duplicates or trash files]
   
   ## Files Needing Your Decision
   
   - [List any files you're unsure about]
   
   Ready to proceed? (yes/no/modify)
   

6. Execute Organization

   After approval, organize systematically:

   # Create folder structure
   mkdir -p "path/to/new/folders"
   
   # Move files with clear logging
   mv "old/path/file.pdf" "new/path/file.pdf"
   
   # Rename files with consistent patterns
   # Example: "YYYY-MM-DD - Description.ext"
   

   Important Rules:

   • Always confirm before deleting anything
   • Log all moves for potential undo
   • Preserve original modification dates
   • Handle filename conflicts gracefully
   • Stop and ask if you encounter unexpected situations

7. Provide Summary and Maintenance Tips

   After organizing:

   # Organization Complete! ✨
   
   ## What Changed
   
   - Created [X] new folders
   - Organized [Y] files
   - Freed [Z] GB by removing duplicates
   - Archived [W] old files
   
   ## New Structure
   
   [Show the new folder tree]
   
   ## Maintenance Tips
   
   To keep this organized:
   
   1. **Weekly**: Sort new downloads
   2. **Monthly**: Review and archive completed projects
   3. **Quarterly**: Check for new duplicates
   4. **Yearly**: Archive old files
   
   ## Quick Commands for You
   
   ```bash
   # Find files modified this week
   find . -type f -mtime -7
   
   # Sort downloads by type
   [custom command for their setup]
   
   # Find duplicates
   [custom command]
   

   Want to organize another folder?

Examples

Example 1: Organizing Downloads (From Justin Dielmann)

User: "My Downloads folder is a mess with 500+ files. Help me organize it."

Process:

1. Analyzes Downloads folder
2. Finds patterns: work docs, personal photos, installers, random PDFs
3. Proposes structure:
   • Downloads/
     • Work/
     • Personal/
     • Installers/ (DMG, PKG files)
     • Archive/
     • ToSort/ (things needing decisions)
4. Asks for confirmation
5. Moves files intelligently based on content and names
6. Results: 500 files → 5 organized folders

Example 2: Finding and Removing Duplicates

User: "Find duplicate files in my Documents and help me decide which to keep."

Output:

# Found 23 Sets of Duplicates (156 MB total)

## Duplicate Set 1: "proposal.pdf"
- `/Documents/proposal.pdf` (2.3 MB, modified: 2024-03-15)
- `/Documents/old/proposal.pdf` (2.3 MB, modified: 2024-03-15)
- `/Desktop/proposal.pdf` (2.3 MB, modified: 2024-03-10)

**Recommendation**: Keep `/Documents/proposal.pdf` (most recent in correct location)
Delete the other 2 copies?

[Continue for all duplicates...]

Example 3: Restructuring Projects Folder

User: "Review my ~/Projects directory and suggest improvements."

Output:

# Analysis of ~/Projects

## Current Structure Issues
- Mix of active and archived projects (3+ years old)
- No consistent naming convention
- Some projects at root, others in random subfolders
- Duplicate folders (project-name, project-name-old, project-name-v2)

## Proposed Structure

Projects/ ├── Active/ │ ├── client-work/ │ ├── side-projects/ │ └── learning/ ├── Archive/ │ ├── 2022/ │ ├── 2023/ │ └── 2024/ └── Templates/

## Specific Changes
1. Move 12 projects not touched since 2022 → Archive/
2. Consolidate 4 duplicate project folders
3. Rename projects to consistent format: "client-name-project-name"
4. Create Archive for old work

Want me to implement this?

Example 4: Organizing Photos by Date

User: "Organize my photo folders by year and month."

Output: Creates structure like:

Photos/
├── 2023/
│   ├── 01-January/
│   ├── 02-February/
│   └── ...
├── 2024/
│   ├── 01-January/
│   └── ...
└── Unsorted/

Then moves photos based on EXIF data or file modification dates.

Common Organization Tasks

Downloads Cleanup

Organize my Downloads folder - move documents to Documents, 
images to Pictures, keep installers separate, and archive files 
older than 3 months.

Project Organization

Review my Projects folder structure and help me separate active 
projects from old ones I should archive.

Duplicate Removal

Find all duplicate files in my Documents folder and help me 
decide which ones to keep.

Desktop Cleanup

My Desktop is covered in files. Help me organize everything into 
my Documents folder properly.

Photo Organization

Organize all photos in this folder by date (year/month) based 
on when they were taken.

Work/Personal Separation

Help me separate my work files from personal files across my 
Documents folder.

Pro Tips

1. Start Small: Begin with one messy folder (like Downloads) to build trust
2. Regular Maintenance: Run weekly cleanup on Downloads
3. Consistent Naming: Use "YYYY-MM-DD - Description" format for important files
4. Archive Aggressively: Move old projects to Archive instead of deleting
5. Keep Active Separate: Maintain clear boundaries between active and archived work
6. Trust the Process: Let Claude handle the cognitive load of where things go

Best Practices

Folder Naming

• Use clear, descriptive names
• Avoid spaces (use hyphens or underscores)
• Be specific: "client-proposals" not "docs"
• Use prefixes for ordering: "01-current", "02-archive"

File Naming

• Include dates: "2024-10-17-meeting-notes.md"
• Be descriptive: "q3-financial-report.xlsx"
• Avoid version numbers in names (use version control instead)
• Remove download artifacts: "document-final-v2 (1).pdf" → "document.pdf"

When to Archive

• Projects not touched in 6+ months
• Completed work that might be referenced later
• Old versions after migration to new systems
• Files you're hesitant to delete (archive first)

Related Use Cases

• Setting up organization for a new computer
• Preparing files for backup/archiving
• Cleaning up before storage cleanup
• Organizing shared team folders
• Structuring new project directories

Image Enhancer

This skill takes your images and screenshots and makes them look better—sharper, clearer, and more professional.

When to Use This Skill

• Improving screenshot quality for blog posts or documentation
• Enhancing images before sharing on social media
• Preparing images for presentations or reports
• Upscaling low-resolution images
• Sharpening blurry photos
• Cleaning up compressed images

What This Skill Does

1. Analyzes Image Quality: Checks resolution, sharpness, and compression artifacts
2. Enhances Resolution: Upscales images intelligently
3. Improves Sharpness: Enhances edges and details
4. Reduces Artifacts: Cleans up compression artifacts and noise
5. Optimizes for Use Case: Adjusts based on intended use (web, print, social media)

How to Use

Basic Enhancement

Improve the image quality of screenshot.png

Enhance all images in this folder

Specific Improvements

Upscale this image to 4K resolution

Sharpen this blurry screenshot

Reduce compression artifacts in this image

Batch Processing

Improve the quality of all PNG files in this directory

Example

User: "Improve the image quality of screenshot-2024.png"

Output:

Analyzing screenshot-2024.png...

Current specs:
- Resolution: 1920x1080
- Format: PNG
- Quality: Good, but slight blur

Enhancements applied:
✓ Upscaled to 2560x1440 (retina)
✓ Sharpened edges
✓ Enhanced text clarity
✓ Optimized file size

Saved as: screenshot-2024-enhanced.png
Original preserved as: screenshot-2024-original.png

Inspired by: Lenny Rachitsky's workflow from his newsletter - used for screenshots in his articles

Tips

• Always keeps original files as backup
• Works best with screenshots and digital images
• Can batch process entire folders
• Specify output format if needed (PNG for quality, JPG for smaller size)
• For social media, mention the platform for optimal sizing

Common Use Cases

• Blog Posts: Enhance screenshots before publishing
• Documentation: Make UI screenshots crystal clear
• Social Media: Optimize images for Twitter, LinkedIn, Instagram
• Presentations: Upscale images for large screens
• Print Materials: Increase resolution for physical media

When to use this skill

To write internal communications, use this skill for:

• 3P updates (Progress, Plans, Problems)
• Company newsletters
• FAQ responses
• Status reports
• Leadership updates
• Project updates
• Incident reports

How to use this skill

To write any internal communication:

1. Identify the communication type from the request
2. Load the appropriate guideline file from the examples/ directory:
   • examples/3p-updates.md - For Progress/Plans/Problems team updates
   • examples/company-newsletter.md - For company-wide newsletters
   • examples/faq-answers.md - For answering frequently asked questions
   • examples/general-comms.md - For anything else that doesn't explicitly match one of the above
3. Follow the specific instructions in that file for formatting, tone, and content gathering

If the communication type doesn't match any existing guideline, ask for clarification or more context about the desired format.

Keywords

3P updates, company newsletter, company comms, weekly update, faqs, common questions, updates, internal comms

Invoice Organizer

This skill transforms chaotic folders of invoices, receipts, and financial documents into a clean, tax-ready filing system without manual effort.

When to Use This Skill

• Preparing for tax season and need organized records
• Managing business expenses across multiple vendors
• Organizing receipts from a messy folder or email downloads
• Setting up automated invoice filing for ongoing bookkeeping
• Archiving financial records by year or category
• Reconciling expenses for reimbursement
• Preparing documentation for accountants

What This Skill Does

1. Reads Invoice Content: Extracts information from PDFs, images, and documents:

   • Vendor/company name
   • Invoice number
   • Date
   • Amount
   • Product or service description
   • Payment method

2. Renames Files Consistently: Creates standardized filenames:

   • Format: YYYY-MM-DD Vendor - Invoice - ProductOrService.pdf
   • Examples: 2024-03-15 Adobe - Invoice - Creative Cloud.pdf

3. Organizes by Category: Sorts into logical folders:

   • By vendor
   • By expense category (software, office, travel, etc.)
   • By time period (year, quarter, month)
   • By tax category (deductible, personal, etc.)

4. Handles Multiple Formats: Works with:

   • PDF invoices
   • Scanned receipts (JPG, PNG)
   • Email attachments
   • Screenshots
   • Bank statements

5. Maintains Originals: Preserves original files while organizing copies

How to Use

Basic Usage

Navigate to your messy invoice folder:

cd ~/Desktop/receipts-to-sort

Then ask Claude Code:

Organize these invoices for taxes

Or more specifically:

Read all invoices in this folder, rename them to 
"YYYY-MM-DD Vendor - Invoice - Product.pdf" format, 
and organize them by vendor

Advanced Organization

Organize these invoices:
1. Extract date, vendor, and description from each file
2. Rename to standard format
3. Sort into folders by expense category (Software, Office, Travel, etc.)
4. Create a CSV spreadsheet with all invoice details for my accountant

Instructions

When a user requests invoice organization:

1. Scan the Folder

   Identify all invoice files:

   # Find all invoice-related files
   find . -type f \( -name "*.pdf" -o -name "*.jpg" -o -name "*.png" \) -print
   

   Report findings:

   • Total number of files
   • File types
   • Date range (if discernible from names)
   • Current organization (or lack thereof)

2. Extract Information from Each File

   For each invoice, extract:

   From PDF invoices:

   • Use text extraction to read invoice content
   • Look for common patterns:
     • "Invoice Date:", "Date:", "Issued:"
     • "Invoice #:", "Invoice Number:"
     • Company name (usually at top)
     • "Amount Due:", "Total:", "Amount:"
     • "Description:", "Service:", "Product:"

   From image receipts:

   • Read visible text from images
   • Identify vendor name (often at top)
   • Look for date (common formats)
   • Find total amount

   Fallback for unclear files:

   • Use filename clues
   • Check file creation/modification date
   • Flag for manual review if critical info missing

3. Determine Organization Strategy

   Ask user preference if not specified:

   I found [X] invoices from [date range].
   
   How would you like them organized?
   
   1. **By Vendor** (Adobe/, Amazon/, Stripe/, etc.)
   2. **By Category** (Software/, Office Supplies/, Travel/, etc.)
   3. **By Date** (2024/Q1/, 2024/Q2/, etc.)
   4. **By Tax Category** (Deductible/, Personal/, etc.)
   5. **Custom** (describe your structure)
   
   Or I can use a default structure: Year/Category/Vendor
   

4. Create Standardized Filename

   For each invoice, create a filename following this pattern:

   YYYY-MM-DD Vendor - Invoice - Description.ext
   

   Examples:

   • 2024-03-15 Adobe - Invoice - Creative Cloud.pdf
   • 2024-01-10 Amazon - Receipt - Office Supplies.pdf
   • 2023-12-01 Stripe - Invoice - Monthly Payment Processing.pdf

   Filename Best Practices:

   • Remove special characters except hyphens
   • Capitalize vendor names properly
   • Keep descriptions concise but meaningful
   • Use consistent date format (YYYY-MM-DD) for sorting
   • Preserve original file extension

5. Execute Organization

   Before moving files, show the plan:

   # Organization Plan
   
   ## Proposed Structure
   

   Invoices/ ├── 2023/ │ ├── Software/ │ │ ├── Adobe/ │ │ └── Microsoft/ │ ├── Services/ │ └── Office/ └── 2024/ ├── Software/ ├── Services/ └── Office/

   
   ## Sample Changes
   
   Before: `invoice_adobe_march.pdf`
   After: `2024-03-15 Adobe - Invoice - Creative Cloud.pdf`
   Location: `Invoices/2024/Software/Adobe/`
   
   Before: `IMG_2847.jpg`
   After: `2024-02-10 Staples - Receipt - Office Supplies.jpg`
   Location: `Invoices/2024/Office/Staples/`
   
   Process [X] files? (yes/no)
   

   After approval:

   # Create folder structure
   mkdir -p "Invoices/2024/Software/Adobe"
   
   # Copy (don't move) to preserve originals
   cp "original.pdf" "Invoices/2024/Software/Adobe/2024-03-15 Adobe - Invoice - Creative Cloud.pdf"
   
   # Or move if user prefers
   mv "original.pdf" "new/path/standardized-name.pdf"
   

6. Generate Summary Report

   Create a CSV file with all invoice details:

   Date,Vendor,Invoice Number,Description,Amount,Category,File Path
   2024-03-15,Adobe,INV-12345,Creative Cloud,52.99,Software,Invoices/2024/Software/Adobe/2024-03-15 Adobe - Invoice - Creative Cloud.pdf
   2024-03-10,Amazon,123-4567890-1234567,Office Supplies,127.45,Office,Invoices/2024/Office/Amazon/2024-03-10 Amazon - Receipt - Office Supplies.pdf
   ...
   

   This CSV is useful for:

   • Importing into accounting software
   • Sharing with accountants
   • Expense tracking and reporting
   • Tax preparation

7. Provide Completion Summary

   # Organization Complete! 📊
   
   ## Summary
   - **Processed**: [X] invoices
   - **Date range**: [earliest] to [latest]
   - **Total amount**: $[sum] (if amounts extracted)
   - **Vendors**: [Y] unique vendors
   
   ## New Structure
   

   Invoices/ ├── 2024/ (45 files) │ ├── Software/ (23 files) │ ├── Services/ (12 files) │ └── Office/ (10 files) └── 2023/ (12 files)

   
   ## Files Created
   - `/Invoices/` - Organized invoices
   - `/Invoices/invoice-summary.csv` - Spreadsheet for accounting
   - `/Invoices/originals/` - Original files (if copied)
   
   ## Files Needing Review
   [List any files where information couldn't be extracted completely]
   
   ## Next Steps
   1. Review the `invoice-summary.csv` file
   2. Check files in "Needs Review" folder
   3. Import CSV into your accounting software
   4. Set up auto-organization for future invoices
   
   Ready for tax season! 🎉
   

Examples

Example 1: Tax Preparation (From Martin Merschroth)

User: "I have a messy folder of invoices for taxes. Sort them and rename properly."

Process:

1. Scans folder: finds 147 PDFs and images
2. Reads each invoice to extract:
   • Date
   • Vendor name
   • Invoice number
   • Product/service description
3. Renames all files: YYYY-MM-DD Vendor - Invoice - Product.pdf
4. Organizes into: 2024/Software/, 2024/Travel/, etc.
5. Creates invoice-summary.csv for accountant
6. Result: Tax-ready organized invoices in minutes

Example 2: Monthly Expense Reconciliation

User: "Organize my business receipts from last month by category."

Output:

# March 2024 Receipts Organized

## By Category
- Software & Tools: $847.32 (12 invoices)
- Office Supplies: $234.18 (8 receipts)
- Travel & Meals: $1,456.90 (15 receipts)
- Professional Services: $2,500.00 (3 invoices)

Total: $5,038.40

All receipts renamed and filed in:
`Business-Receipts/2024/03-March/[Category]/`

CSV export: `march-2024-expenses.csv`

Example 3: Multi-Year Archive

User: "I have 3 years of random invoices. Organize them by year, then by vendor."

Output: Creates structure:

Invoices/
├── 2022/
│   ├── Adobe/
│   ├── Amazon/
│   └── ...
├── 2023/
│   ├── Adobe/
│   ├── Amazon/
│   └── ...
└── 2024/
    ├── Adobe/
    ├── Amazon/
    └── ...

Each file properly renamed with date and description.

Example 4: Email Downloads Cleanup

User: "I download invoices from Gmail. They're all named 'invoice.pdf', 'invoice(1).pdf', etc. Fix this mess."

Output:

Found 89 files all named "invoice*.pdf"

Reading each file to extract real information...

Renamed examples:
- invoice.pdf → 2024-03-15 Shopify - Invoice - Monthly Subscription.pdf
- invoice(1).pdf → 2024-03-14 Google - Invoice - Workspace.pdf
- invoice(2).pdf → 2024-03-10 Netlify - Invoice - Pro Plan.pdf

All files renamed and organized by vendor.

Common Organization Patterns

By Vendor (Simple)

Invoices/
├── Adobe/
├── Amazon/
├── Google/
└── Microsoft/

By Year and Category (Tax-Friendly)

Invoices/
├── 2023/
│   ├── Software/
│   ├── Hardware/
│   ├── Services/
│   └── Travel/
└── 2024/
    └── ...

By Quarter (Detailed Tracking)

Invoices/
├── 2024/
│   ├── Q1/
│   │   ├── Software/
│   │   ├── Office/
│   │   └── Travel/
│   └── Q2/
│       └── ...

By Tax Category (Accountant-Ready)

Invoices/
├── Deductible/
│   ├── Software/
│   ├── Office/
│   └── Professional-Services/
├── Partially-Deductible/
│   └── Meals-Travel/
└── Personal/

Automation Setup

For ongoing organization:

Create a script that watches my ~/Downloads/invoices folder 
and auto-organizes any new invoice files using our standard 
naming and folder structure.

This creates a persistent solution that organizes invoices as they arrive.

Pro Tips

1. Scan emails to PDF: Use Preview or similar to save email invoices as PDFs first
2. Consistent downloads: Save all invoices to one folder for batch processing
3. Monthly routine: Organize invoices monthly, not annually
4. Backup originals: Keep original files before reorganizing
5. Include amounts in CSV: Useful for budget tracking
6. Tag by deductibility: Note which expenses are tax-deductible
7. Keep receipts 7 years: Standard audit period

Handling Special Cases

Missing Information

If date/vendor can't be extracted:

• Flag file for manual review
• Use file modification date as fallback
• Create "Needs-Review/" folder

Duplicate Invoices

If same invoice appears multiple times:

• Compare file hashes
• Keep highest quality version
• Note duplicates in summary

Multi-Page Invoices

For invoices split across files:

• Merge PDFs if needed
• Use consistent naming for parts
• Note in CSV if invoice is split

Non-Standard Formats

For unusual receipt formats:

• Extract what's possible
• Standardize what you can
• Flag for review if critical info missing

Related Use Cases

• Creating expense reports for reimbursement
• Organizing bank statements
• Managing vendor contracts
• Archiving old financial records
• Preparing for audits
• Tracking subscription costs over time

Lead Research Assistant

This skill helps you identify and qualify potential leads for your business by analyzing your product/service, understanding your ideal customer profile, and providing actionable outreach strategies.

When to Use This Skill

• Finding potential customers or clients for your product/service
• Building a list of companies to reach out to for partnerships
• Identifying target accounts for sales outreach
• Researching companies that match your ideal customer profile
• Preparing for business development activities

What This Skill Does

1. Understands Your Business: Analyzes your product/service, value proposition, and target market
2. Identifies Target Companies: Finds companies that match your ideal customer profile based on:
   • Industry and sector
   • Company size and location
   • Technology stack and tools they use
   • Growth stage and funding
   • Pain points your product solves
3. Prioritizes Leads: Ranks companies based on fit score and relevance
4. Provides Contact Strategies: Suggests how to approach each lead with personalized messaging
5. Enriches Data: Gathers relevant information about decision-makers and company context

How to Use

Basic Usage

Simply describe your product/service and what you're looking for:

I'm building [product description]. Find me 10 companies in [location/industry] 
that would be good leads for this.

With Your Codebase

For even better results, run this from your product's source code directory:

Look at what I'm building in this repository and identify the top 10 companies 
in [location/industry] that would benefit from this product.

Advanced Usage

For more targeted research:

My product: [description]
Ideal customer profile:
- Industry: [industry]
- Company size: [size range]
- Location: [location]
- Current pain points: [pain points]
- Technologies they use: [tech stack]

Find me 20 qualified leads with contact strategies for each.

Instructions

When a user requests lead research:

1. Understand the Product/Service

   • If in a code directory, analyze the codebase to understand the product
   • Ask clarifying questions about the value proposition
   • Identify key features and benefits
   • Understand what problems it solves

2. Define Ideal Customer Profile

   • Determine target industries and sectors
   • Identify company size ranges
   • Consider geographic preferences
   • Understand relevant pain points
   • Note any technology requirements

3. Research and Identify Leads

   • Search for companies matching the criteria
   • Look for signals of need (job postings, tech stack, recent news)
   • Consider growth indicators (funding, expansion, hiring)
   • Identify companies with complementary products/services
   • Check for budget indicators

4. Prioritize and Score

   • Create a fit score (1-10) for each lead
   • Consider factors like:
     • Alignment with ICP
     • Signals of immediate need
     • Budget availability
     • Competitive landscape
     • Timing indicators

5. Provide Actionable Output

   For each lead, provide:

   • Company Name and website
   • Why They're a Good Fit: Specific reasons based on their business
   • Priority Score: 1-10 with explanation
   • Decision Maker: Role/title to target (e.g., "VP of Engineering")
   • Contact Strategy: Personalized approach suggestions
   • Value Proposition: How your product solves their specific problem
   • Conversation Starters: Specific points to mention in outreach
   • LinkedIn URL: If available, for easy connection

6. Format the Output

   Present results in a clear, scannable format:

   # Lead Research Results
   
   ## Summary
   - Total leads found: [X]
   - High priority (8-10): [X]
   - Medium priority (5-7): [X]
   - Average fit score: [X]
   
   ---
   
   ## Lead 1: [Company Name]
   
   **Website**: [URL]
   **Priority Score**: [X/10]
   **Industry**: [Industry]
   **Size**: [Employee count/revenue range]
   
   **Why They're a Good Fit**:
   [2-3 specific reasons based on their business]
   
   **Target Decision Maker**: [Role/Title]
   **LinkedIn**: [URL if available]
   
   **Value Proposition for Them**:
   [Specific benefit for this company]
   
   **Outreach Strategy**:
   [Personalized approach - mention specific pain points, recent company news, or relevant context]
   
   **Conversation Starters**:
   - [Specific point 1]
   - [Specific point 2]
   
   ---
   
   [Repeat for each lead]
   

7. Offer Next Steps

   • Suggest saving results to a CSV for CRM import
   • Offer to draft personalized outreach messages
   • Recommend prioritization based on timing
   • Suggest follow-up research for top leads

Examples

Example 1: From Lenny's Newsletter

User: "I'm building a tool that masks sensitive data in AI coding assistant queries. Find potential leads."

Output: Creates a prioritized list of companies that:

• Use AI coding assistants (Copilot, Cursor, etc.)
• Handle sensitive data (fintech, healthcare, legal)
• Have evidence in their GitHub repos of using coding agents
• May have accidentally exposed sensitive data in code
• Includes LinkedIn URLs of relevant decision-makers

Example 2: Local Business

User: "I run a consulting practice for remote team productivity. Find me 10 companies in the Bay Area that recently went remote."

Output: Identifies companies that:

• Recently posted remote job listings
• Announced remote-first policies
• Are hiring distributed teams
• Show signs of remote work challenges
• Provides personalized outreach strategies for each

Tips for Best Results

• Be specific about your product and its unique value
• Run from your codebase if applicable for automatic context
• Provide context about your ideal customer profile
• Specify constraints like industry, location, or company size
• Request follow-up research on promising leads for deeper insights

Related Use Cases

• Drafting personalized outreach emails after identifying leads
• Building a CRM-ready CSV of qualified prospects
• Researching specific companies in detail
• Analyzing competitor customer bases
• Identifying partnership opportunities

MCP Server Development Guide

Overview

To create high-quality MCP (Model Context Protocol) servers that enable LLMs to effectively interact with external services, use this skill. An MCP server provides tools that allow LLMs to access external services and APIs. The quality of an MCP server is measured by how well it enables LLMs to accomplish real-world tasks using the tools provided.

Process

🚀 High-Level Workflow

Creating a high-quality MCP server involves four main phases:

Phase 1: Deep Research and Planning

1.1 Understand Agent-Centric Design Principles

Before diving into implementation, understand how to design tools for AI agents by reviewing these principles:

Build for Workflows, Not Just API Endpoints:

• Don't simply wrap existing API endpoints - build thoughtful, high-impact workflow tools
• Consolidate related operations (e.g., schedule_event that both checks availability and creates event)
• Focus on tools that enable complete tasks, not just individual API calls
• Consider what workflows agents actually need to accomplish

Optimize for Limited Context:

• Agents have constrained context windows - make every token count
• Return high-signal information, not exhaustive data dumps
• Provide "concise" vs "detailed" response format options
• Default to human-readable identifiers over technical codes (names over IDs)
• Consider the agent's context budget as a scarce resource

Design Actionable Error Messages:

• Error messages should guide agents toward correct usage patterns
• Suggest specific next steps: "Try using filter='active_only' to reduce results"
• Make errors educational, not just diagnostic
• Help agents learn proper tool usage through clear feedback

Follow Natural Task Subdivisions:

• Tool names should reflect how humans think about tasks
• Group related tools with consistent prefixes for discoverability
• Design tools around natural workflows, not just API structure

Use Evaluation-Driven Development:

• Create realistic evaluation scenarios early
• Let agent feedback drive tool improvements
• Prototype quickly and iterate based on actual agent performance

1.3 Study MCP Protocol Documentation

Fetch the latest MCP protocol documentation:

Use WebFetch to load: https://modelcontextprotocol.io/llms-full.txt

This comprehensive document contains the complete MCP specification and guidelines.

1.4 Study Framework Documentation

Load and read the following reference files:

• MCP Best Practices: 📋 View Best Practices - Core guidelines for all MCP servers

For Python implementations, also load:

• Python SDK Documentation: Use WebFetch to load https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md
• 🐍 Python Implementation Guide - Python-specific best practices and examples

For Node/TypeScript implementations, also load:

• TypeScript SDK Documentation: Use WebFetch to load https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md
• ⚡ TypeScript Implementation Guide - Node/TypeScript-specific best practices and examples

1.5 Exhaustively Study API Documentation

To integrate a service, read through ALL available API documentation:

• Official API reference documentation
• Authentication and authorization requirements
• Rate limiting and pagination patterns
• Error responses and status codes
• Available endpoints and their parameters
• Data models and schemas

To gather comprehensive information, use web search and the WebFetch tool as needed.

1.6 Create a Comprehensive Implementation Plan

Based on your research, create a detailed plan that includes:

Tool Selection:

• List the most valuable endpoints/operations to implement
• Prioritize tools that enable the most common and important use cases
• Consider which tools work together to enable complex workflows

Shared Utilities and Helpers:

• Identify common API request patterns
• Plan pagination helpers
• Design filtering and formatting utilities
• Plan error handling strategies

Input/Output Design:

• Define input validation models (Pydantic for Python, Zod for TypeScript)
• Design consistent response formats (e.g., JSON or Markdown), and configurable levels of detail (e.g., Detailed or Concise)
• Plan for large-scale usage (thousands of users/resources)
• Implement character limits and truncation strategies (e.g., 25,000 tokens)

Error Handling Strategy:

• Plan graceful failure modes
• Design clear, actionable, LLM-friendly, natural language error messages which prompt further action
• Consider rate limiting and timeout scenarios
• Handle authentication and authorization errors

Phase 2: Implementation

Now that you have a comprehensive plan, begin implementation following language-specific best practices.

2.1 Set Up Project Structure

For Python:

• Create a single .py file or organize into modules if complex (see 🐍 Python Guide)
• Use the MCP Python SDK for tool registration
• Define Pydantic models for input validation

For Node/TypeScript:

• Create proper project structure (see ⚡ TypeScript Guide)
• Set up package.json and tsconfig.json
• Use MCP TypeScript SDK
• Define Zod schemas for input validation

2.2 Implement Core Infrastructure First

To begin implementation, create shared utilities before implementing tools:

• API request helper functions
• Error handling utilities
• Response formatting functions (JSON and Markdown)
• Pagination helpers
• Authentication/token management

2.3 Implement Tools Systematically

For each tool in the plan:

Define Input Schema:

• Use Pydantic (Python) or Zod (TypeScript) for validation
• Include proper constraints (min/max length, regex patterns, min/max values, ranges)
• Provide clear, descriptive field descriptions
• Include diverse examples in field descriptions

Write Comprehensive Docstrings/Descriptions:

• One-line summary of what the tool does
• Detailed explanation of purpose and functionality
• Explicit parameter types with examples
• Complete return type schema
• Usage examples (when to use, when not to use)
• Error handling documentation, which outlines how to proceed given specific errors

Implement Tool Logic:

• Use shared utilities to avoid code duplication
• Follow async/await patterns for all I/O
• Implement proper error handling
• Support multiple response formats (JSON and Markdown)
• Respect pagination parameters
• Check character limits and truncate appropriately

Add Tool Annotations:

• readOnlyHint: true (for read-only operations)
• destructiveHint: false (for non-destructive operations)
• idempotentHint: true (if repeated calls have same effect)
• openWorldHint: true (if interacting with external systems)

2.4 Follow Language-Specific Best Practices

At this point, load the appropriate language guide:

For Python: Load 🐍 Python Implementation Guide and ensure the following:

• Using MCP Python SDK with proper tool registration
• Pydantic v2 models with model_config
• Type hints throughout
• Async/await for all I/O operations
• Proper imports organization
• Module-level constants (CHARACTER_LIMIT, API_BASE_URL)

For Node/TypeScript: Load ⚡ TypeScript Implementation Guide and ensure the following:

• Using server.registerTool properly
• Zod schemas with .strict()
• TypeScript strict mode enabled
• No any types - use proper types
• Explicit Promise<T> return types
• Build process configured (npm run build)

Phase 3: Review and Refine

After initial implementation:

3.1 Code Quality Review

To ensure quality, review the code for:

• DRY Principle: No duplicated code between tools
• Composability: Shared logic extracted into functions
• Consistency: Similar operations return similar formats
• Error Handling: All external calls have error handling
• Type Safety: Full type coverage (Python type hints, TypeScript types)
• Documentation: Every tool has comprehensive docstrings/descriptions

3.2 Test and Build

Important: MCP servers are long-running processes that wait for requests over stdio/stdin or sse/http. Running them directly in your main process (e.g., python server.py or node dist/index.js) will cause your process to hang indefinitely.

Safe ways to test the server:

• Use the evaluation harness (see Phase 4) - recommended approach
• Run the server in tmux to keep it outside your main process
• Use a timeout when testing: timeout 5s python server.py

For Python:

• Verify Python syntax: python -m py_compile your_server.py
• Check imports work correctly by reviewing the file
• To manually test: Run server in tmux, then test with evaluation harness in main process
• Or use the evaluation harness directly (it manages the server for stdio transport)

For Node/TypeScript:

• Run npm run build and ensure it completes without errors
• Verify dist/index.js is created
• To manually test: Run server in tmux, then test with evaluation harness in main process
• Or use the evaluation harness directly (it manages the server for stdio transport)

3.3 Use Quality Checklist

To verify implementation quality, load the appropriate checklist from the language-specific guide:

• Python: see "Quality Checklist" in 🐍 Python Guide
• Node/TypeScript: see "Quality Checklist" in ⚡ TypeScript Guide

Phase 4: Create Evaluations

After implementing your MCP server, create comprehensive evaluations to test its effectiveness.

Load ✅ Evaluation Guide for complete evaluation guidelines.

4.1 Understand Evaluation Purpose

Evaluations test whether LLMs can effectively use your MCP server to answer realistic, complex questions.

4.2 Create 10 Evaluation Questions

To create effective evaluations, follow the process outlined in the evaluation guide:

1. Tool Inspection: List available tools and understand their capabilities
2. Content Exploration: Use READ-ONLY operations to explore available data
3. Question Generation: Create 10 complex, realistic questions
4. Answer Verification: Solve each question yourself to verify answers

4.3 Evaluation Requirements

Each question must be:

• Independent: Not dependent on other questions
• Read-only: Only non-destructive operations required
• Complex: Requiring multiple tool calls and deep exploration
• Realistic: Based on real use cases humans would care about
• Verifiable: Single, clear answer that can be verified by string comparison
• Stable: Answer won't change over time

4.4 Output Format

Create an XML file with this structure:

<evaluation>
  <qa_pair>
    <question>Find discussions about AI model launches with animal codenames. One model needed a specific safety designation that uses the format ASL-X. What number X was being determined for the model named after a spotted wild cat?</question>
    <answer>3</answer>
  </qa_pair>
<!-- More qa_pairs... -->
</evaluation>

Reference Files

📚 Documentation Library

Load these resources as needed during development:

Core MCP Documentation (Load First)

• MCP Protocol: Fetch from https://modelcontextprotocol.io/llms-full.txt - Complete MCP specification
• 📋 MCP Best Practices - Universal MCP guidelines including:
  • Server and tool naming conventions
  • Response format guidelines (JSON vs Markdown)
  • Pagination best practices
  • Character limits and truncation strategies
  • Tool development guidelines
  • Security and error handling standards

SDK Documentation (Load During Phase 1/2)

• Python SDK: Fetch from https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md
• TypeScript SDK: Fetch from https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md

Language-Specific Implementation Guides (Load During Phase 2)

• 🐍 Python Implementation Guide - Complete Python/FastMCP guide with:

  • Server initialization patterns
  • Pydantic model examples
  • Tool registration with @mcp.tool
  • Complete working examples
  • Quality checklist

• ⚡ TypeScript Implementation Guide - Complete TypeScript guide with:

  • Project structure
  • Zod schema patterns
  • Tool registration with server.registerTool
  • Complete working examples
  • Quality checklist

Evaluation Guide (Load During Phase 4)

• ✅ Evaluation Guide - Complete evaluation creation guide with:
  • Question creation guidelines
  • Answer verification strategies
  • XML format specifications
  • Example questions and answers
  • Running an evaluation with the provided scripts

Meeting Insights Analyzer

This skill transforms your meeting transcripts into actionable insights about your communication patterns, helping you become a more effective communicator and leader.

When to Use This Skill

• Analyzing your communication patterns across multiple meetings
• Getting feedback on your leadership and facilitation style
• Identifying when you avoid difficult conversations
• Understanding your speaking habits and filler words
• Tracking improvement in communication skills over time
• Preparing for performance reviews with concrete examples
• Coaching team members on their communication style

What This Skill Does

1. Pattern Recognition: Identifies recurring behaviors across meetings like:

   • Conflict avoidance or indirect communication
   • Speaking ratios and turn-taking
   • Question-asking vs. statement-making patterns
   • Active listening indicators
   • Decision-making approaches

2. Communication Analysis: Evaluates communication effectiveness:

   • Clarity and directness
   • Use of filler words and hedging language
   • Tone and sentiment patterns
   • Meeting control and facilitation

3. Actionable Feedback: Provides specific, timestamped examples with:

   • What happened
   • Why it matters
   • How to improve

4. Trend Tracking: Compares patterns over time when analyzing multiple meetings

How to Use

Basic Setup

1. Download your meeting transcripts to a folder (e.g., ~/meetings/)
2. Navigate to that folder in Claude Code
3. Ask for the analysis you want

Quick Start Examples

Analyze all meetings in this folder and tell me when I avoided conflict.

Look at my meetings from the past month and identify my communication patterns.

Compare my facilitation style between these two meeting folders.

Advanced Analysis

Analyze all transcripts in this folder and:
1. Identify when I interrupted others
2. Calculate my speaking ratio
3. Find moments I avoided giving direct feedback
4. Track my use of filler words
5. Show examples of good active listening

Instructions

When a user requests meeting analysis:

1. Discover Available Data

   • Scan the folder for transcript files (.txt, .md, .vtt, .srt, .docx)
   • Check if files contain speaker labels and timestamps
   • Confirm the date range of meetings
   • Identify the user's name/identifier in transcripts

2. Clarify Analysis Goals

   If not specified, ask what they want to learn:

   • Specific behaviors (conflict avoidance, interruptions, filler words)
   • Communication effectiveness (clarity, directness, listening)
   • Meeting facilitation skills
   • Speaking patterns and ratios
   • Growth areas for improvement

3. Analyze Patterns

   For each requested insight:

   Conflict Avoidance:

   • Look for hedging language ("maybe", "kind of", "I think")
   • Indirect phrasing instead of direct requests
   • Changing subject when tension arises
   • Agreeing without commitment ("yeah, but...")
   • Not addressing obvious problems

   Speaking Ratios:

   • Calculate percentage of meeting spent speaking
   • Count interruptions (by and of the user)
   • Measure average speaking turn length
   • Track question vs. statement ratios

   Filler Words:

   • Count "um", "uh", "like", "you know", "actually", etc.
   • Note frequency per minute or per speaking turn
   • Identify situations where they increase (nervous, uncertain)

   Active Listening:

   • Questions that reference others' previous points
   • Paraphrasing or summarizing others' ideas
   • Building on others' contributions
   • Asking clarifying questions

   Leadership & Facilitation:

   • Decision-making approach (directive vs. collaborative)
   • How disagreements are handled
   • Inclusion of quieter participants
   • Time management and agenda control
   • Follow-up and action item clarity

4. Provide Specific Examples

   For each pattern found, include:

   ### [Pattern Name]
   
   **Finding**: [One-sentence summary of the pattern]
   
   **Frequency**: [X times across Y meetings]
   
   **Examples**:
   
   1. **[Meeting Name/Date]** - [Timestamp]
   
      **What Happened**:
      > [Actual quote from transcript]
   
      **Why This Matters**:
      [Explanation of the impact or missed opportunity]
   
      **Better Approach**:
      [Specific alternative phrasing or behavior]
   
   [Repeat for 2-3 strongest examples]
   

5. Synthesize Insights

   After analyzing all patterns, provide:

   # Meeting Insights Summary
   
   **Analysis Period**: [Date range]
   **Meetings Analyzed**: [X meetings]
   **Total Duration**: [X hours]
   
   ## Key Patterns Identified
   
   ### 1. [Primary Pattern]
   - **Observed**: [What you saw]
   - **Impact**: [Why it matters]
   - **Recommendation**: [How to improve]
   
   ### 2. [Second Pattern]
   [Same structure]
   
   ## Communication Strengths
   
   1. [Strength 1 with example]
   2. [Strength 2 with example]
   3. [Strength 3 with example]
   
   ## Growth Opportunities
   
   1. **[Area 1]**: [Specific, actionable advice]
   2. **[Area 2]**: [Specific, actionable advice]
   3. **[Area 3]**: [Specific, actionable advice]
   
   ## Speaking Statistics
   
   - Average speaking time: [X% of meeting]
   - Questions asked: [X per meeting average]
   - Filler words: [X per minute]
   - Interruptions: [X given / Y received per meeting]
   
   ## Next Steps
   
   [3-5 concrete actions to improve communication]
   

6. Offer Follow-Up Options

   • Track these same metrics in future meetings
   • Deep dive into specific meetings or patterns
   • Compare to industry benchmarks
   • Create a personal communication development plan
   • Generate a summary for performance reviews

Examples

Example 1: Conflict Avoidance Analysis (Inspired by Dan Shipper)

User: "I download all of my meeting recordings and put them in a folder. Tell me all the times I've subtly avoided conflict."

Output:

# Conflict Avoidance Patterns

Found 23 instances across 15 meetings where you used indirect 
communication or avoided addressing tensions directly.

## Pattern: Hedging on Critical Feedback

**Frequency**: 8 times across 7 meetings

**Example 1: 1:1 with Sarah** - 00:14:32

**What Happened**:
> "So, I was thinking... maybe we could, like, potentially 
> consider looking at the timeline again? I mean, if you 
> think that makes sense. But whatever you think is best!"

**Why This Matters**:
You needed to address that Sarah's project was behind schedule, 
but the hedging language ("maybe", "potentially", "if you think") 
and the deflection at the end ("whatever you think") made it easy 
for her to miss the urgency.

**Better Approach**:
"Sarah, the project is two weeks behind schedule. We need to 
discuss what's blocking progress and create a new timeline 
today."

[Additional examples...]

## Recommendations

1. **Name the issue directly** in the first sentence
2. **Remove hedging words** like "maybe," "kind of," "sort of"
3. **Ask specific questions** instead of hinting
4. **Schedule difficult conversations** instead of raising them casually

Example 2: Leadership Facilitation

User: "Analyze my team meetings and tell me about my facilitation style."

Output: Provides insights on:

• How much you speak vs. team members (60% vs. 40%)
• Whether you ask questions or make statements (3:1 ratio)
• How you handle disagreements (tendency to resolve too quickly)
• Who speaks least and whether you draw them in
• Examples of good and missed facilitation moments

Example 3: Personal Development Tracking

User: "Compare my meetings from Q1 vs. Q2 to see if I've improved my listening skills."

Output: Creates a comparative analysis showing:

• Decrease in interruptions (8 per meeting → 3 per meeting)
• Increase in clarifying questions (2 → 7 per meeting)
• Improvement in building on others' ideas
• Specific examples showing the difference
• Remaining areas for growth

Setup Tips

Getting Meeting Transcripts

From Granola (free with Lenny's newsletter subscription):

• Granola auto-transcribes your meetings
• Export transcripts to a folder: [Instructions on how]
• Point Claude Code to that folder

From Zoom:

• Enable cloud recording with transcription
• Download VTT or SRT files after meetings
• Store in a dedicated folder

From Google Meet:

• Use Google Docs auto-transcription
• Save transcript docs to a folder
• Download as .txt files or give Claude Code access

From Fireflies.ai, Otter.ai, etc.:

• Export transcripts in bulk
• Store in a local folder
• Run analysis on the folder

Best Practices

1. Consistent naming: Use YYYY-MM-DD - Meeting Name.txt format
2. Regular analysis: Review monthly or quarterly for trends
3. Specific queries: Ask about one behavior at a time for depth
4. Privacy: Keep sensitive meeting data local
5. Action-oriented: Focus on one improvement area at a time

Common Analysis Requests

• "When do I avoid difficult conversations?"
• "How often do I interrupt others?"
• "What's my speaking vs. listening ratio?"
• "Do I ask good questions?"
• "How do I handle disagreement?"
• "Am I inclusive of all voices?"
• "Do I use too many filler words?"
• "How clear are my action items?"
• "Do I stay on agenda or get sidetracked?"
• "How has my communication changed over time?"

Related Use Cases

• Creating a personal development plan from insights
• Preparing performance review materials with examples
• Coaching direct reports on their communication
• Analyzing customer calls for sales or support patterns
• Studying negotiation tactics and outcomes

Knowledge Capture

Transforms conversations, discussions, and insights into structured documentation in your Notion workspace. Captures knowledge from chat context, formats it appropriately, and saves it to the right location with proper organization and linking.

Quick Start

When asked to save information to Notion:

1. Extract content: Identify key information from conversation context
2. Structure information: Organize into appropriate documentation format
3. Determine location: Use Notion:notion-search to find appropriate wiki page/database
4. Create page: Use Notion:notion-create-pages to save content
5. Make discoverable: Link from relevant hub pages, add to databases, or update wiki navigation so others can find it

Knowledge Capture Workflow

Step 1: Identify content to capture

From conversation context, extract:
- Key concepts and definitions
- Decisions made and rationale
- How-to information and procedures
- Important insights or learnings
- Q&A pairs
- Examples and use cases

Step 2: Determine content type

Classify the knowledge:
- Concept/Definition
- How-to Guide
- Decision Record
- FAQ Entry
- Meeting Summary
- Learning/Post-mortem
- Reference Documentation

Step 3: Structure the content

Format appropriately based on content type:
- Use templates for consistency
- Add clear headings and sections
- Include examples where helpful
- Add relevant metadata
- Link to related pages

Step 4: Determine destination

Where to save:
- Wiki page (general knowledge base)
- Specific project page (project-specific knowledge)
- Documentation database (structured docs)
- FAQ database (questions and answers)
- Decision log (architecture/product decisions)
- Team wiki (team-specific knowledge)

Step 5: Create the page

Use Notion:notion-create-pages:
- Set appropriate title
- Use structured content from template
- Set properties if in database
- Add tags/categories
- Link to related pages

Step 6: Make content discoverable

Link the new page so others can find it:

1. Update hub/index pages:
   - Add link to wiki table of contents page
   - Add link from relevant project page
   - Add link from category/topic page (e.g., "Engineering Docs")
   
2. If page is in a database:
   - Set appropriate tags/categories
   - Set status (e.g., "Published")
   - Add to relevant views
   
3. Optionally update parent page:
   - If saved under a project, add to project's "Documentation" section
   - If in team wiki, ensure it's linked from team homepage

Example:
Notion:notion-update-page
page_id: "team-wiki-homepage-id"
command: "insert_content_after"
selection_with_ellipsis: "## How-To Guides..."
new_str: "- <mention-page url='...'>How to Deploy to Production</mention-page>"

This step ensures the knowledge doesn't become "orphaned" - it's properly connected to your workspace's navigation structure.

Content Types

Choose appropriate structure based on content:

Concept: Overview → Definition → Characteristics → Examples → Use Cases → Related How-To: Overview → Prerequisites → Steps (numbered) → Verification → Troubleshooting → Related Decision: Context → Decision → Rationale → Options Considered → Consequences → Implementation FAQ: Short Answer → Detailed Explanation → Examples → When to Use → Related Questions Learning: What Happened → What Went Well → What Didn't → Root Causes → Learnings → Actions

Destination Patterns

General Wiki: Standalone page → add to index → tag → link from related pages

Project Wiki: Child of project page → link from project overview → tag with project name

Documentation Database: Use properties (Title, Type, Category, Tags, Last Updated, Owner)

Decision Log Database: Use properties (Decision, Date, Status, Domain, Deciders, Impact)

FAQ Database: Use properties (Question, Category, Tags, Last Reviewed, Useful Count)

See reference/database-best-practices.md for database selection guide and individual schema files.

Content Extraction from Conversations

Chat Discussion: Key points, conclusions, resources, action items, Q&A

Problem-Solving: Problem statement, approaches tried, solution, why it worked, future considerations

Knowledge Sharing: Concept explained, examples, best practices, common pitfalls, resources

Decision Discussion: Question, options, trade-offs, decision, rationale, next steps

Formatting Best Practices

Structure: Use # (title), ## (sections), ### (subsections) consistently

Writing: Start with overview, use bullets, keep paragraphs short, add examples

Linking: Link related pages, mention people, reference resources, create bidirectional links

Metadata: Include date, author, tags, status

Searchability: Clear titles, natural keywords, common search tags, image alt-text

Indexing and Organization

Wiki Index: Organize by sections (Getting Started, How-To Guides, Reference, FAQs, Decisions) with page links

Category Pages: Create landing pages with overview, doc links, and recent updates

Tagging Strategy: Use consistent tags for technology/tools, topics, audience, and status

Update Management

Create New: Content is substantive (>2 paragraphs), will be referenced multiple times, part of knowledge base, needs independent discovery

Update Existing: Adding to existing topic, correcting info, expanding concept, updating for changes

Versioning: Add update history section for significant changes (date, author, what changed, why)

Best Practices

1. Capture promptly: Document while context is fresh
2. Structure consistently: Use templates for similar content
3. Link extensively: Connect related knowledge
4. Write for discovery: Use searchable titles and tags
5. Include context: Why this matters, when to use
6. Add examples: Concrete examples aid understanding
7. Maintain: Review and update periodically
8. Get feedback: Ask if documentation is helpful

Advanced Features

Documentation databases: See reference/database-best-practices.md for database schema patterns.

Common Issues

"Not sure where to save": Default to general wiki, can move later "Content is fragmentary": Group related fragments into cohesive doc "Already exists": Search first, update existing if appropriate "Too informal": Clean up language while preserving insights

Examples

See examples/ for complete workflows:

• examples/conversation-to-faq.md - FAQ from Q&A
• examples/decision-capture.md - Decision record
• examples/how-to-guide.md - How-to from discussion

Meeting Intelligence

Prepares you for meetings by gathering context from Notion, enriching it with Claude research, and creating comprehensive meeting materials. Generates both an internal pre-read for attendees and an external-facing agenda for the meeting itself.

Quick Start

When asked to prep for a meeting:

1. Gather Notion context: Use Notion:notion-search to find related pages
2. Fetch details: Use Notion:notion-fetch to read relevant content
3. Enrich with research: Use Claude's knowledge to add context, industry insights, or best practices
4. Create internal pre-read: Use Notion:notion-create-pages for background context document (for attendees)
5. Create external agenda: Use Notion:notion-create-pages for meeting agenda (shared with all participants)
6. Link resources: Connect both docs to related projects and each other

Meeting Prep Workflow

Step 1: Understand meeting context

Collect meeting details:
- Meeting topic/title
- Attendees (internal team + external participants)
- Meeting purpose (decision, brainstorm, status update, customer demo, etc.)
- Meeting type (internal only vs. external participants)
- Related project/initiative
- Specific topics to cover

Step 2: Search for Notion context

Use Notion:notion-search to find:
- Project pages related to meeting topic
- Previous meeting notes
- Specifications or design docs
- Related tasks or issues
- Recent updates or reports
- Customer/partner information (if applicable)

Search strategies:
- Topic-based: "mobile app redesign"
- Project-scoped: search within project teamspace
- Attendee-created: filter by created_by_user_ids
- Recent updates: use created_date_range filters

Step 3: Fetch and analyze Notion content

For each relevant page:
1. Fetch with Notion:notion-fetch
2. Extract key information:
   - Project status and timeline
   - Recent decisions and updates
   - Open questions or blockers
   - Relevant metrics or data
   - Action items from previous meetings
3. Note gaps in information

Step 4: Enrich with Claude research

Beyond Notion context, add value through:

For technical meetings:
- Explain complex concepts for broader audience
- Summarize industry best practices
- Provide competitive context
- Suggest discussion frameworks

For customer meetings:
- Research company background (if public info)
- Industry trends relevant to discussion
- Common pain points in their sector
- Best practices for similar customers

For decision meetings:
- Decision-making frameworks
- Risk analysis patterns
- Trade-off considerations
- Implementation best practices

Note: Use general knowledge only - don't fabricate specific facts

Step 5: Create internal pre-read

Use Notion:notion-create-pages for internal doc:

Title: "[Meeting Topic] - Pre-Read (Internal)"

Content structure:
- **Meeting Overview**: Date, time, attendees, purpose
- **Background Context**: 
  - What this meeting is about (2-3 sentences)
  - Why it matters (business context)
  - Links to related Notion pages
- **Current Status**: 
  - Where we are now (from Notion content)
  - Recent updates and progress
  - Key metrics or data
- **Context & Insights** (from Claude research):
  - Industry context or best practices
  - Relevant considerations
  - Potential approaches to discuss
- **Key Discussion Points**:
  - Topics that need airtime
  - Open questions to resolve
  - Decisions required
- **What We Need from This Meeting**:
  - Expected outcomes
  - Decisions to make
  - Next steps to define

Audience: Internal attendees only
Purpose: Give team full context and alignment before meeting

Step 6: Create external agenda

Use Notion:notion-create-pages for meeting doc:

Title: "[Meeting Topic] - Agenda"

Content structure:
- **Meeting Details**: Date, time, attendees
- **Objective**: Clear meeting goal (1-2 sentences)
- **Agenda Items** (with time allocations):
  1. Topic 1 (10 min)
  2. Topic 2 (20 min)
  3. Topic 3 (15 min)
- **Discussion Topics**: 
  - Key items to cover
  - Questions to answer
- **Decisions Needed**: 
  - Clear decision points
- **Action Items**: 
  - (To be filled during meeting)
- **Related Resources**:
  - Links to relevant pages
  - Link to pre-read document

Audience: All participants (internal + external)
Purpose: Structure the meeting, keep it on track
Tone: Professional, focused, clear

See reference/template-selection-guide.md for full templates.

Step 7: Link documents

1. Link pre-read to agenda:
   - Add mention in agenda: "See <mention-page>Pre-Read</mention-page> for background"

2. Link both to project:
   - Update project page with meeting links
   - Add to "Meetings" section

3. Cross-reference:
   - Agenda mentions pre-read for internal attendees
   - Pre-read mentions agenda for meeting structure

Document Types

Internal Pre-Read (for team)

More comprehensive, internal context:

• Full background and history
• Internal metrics and data
• Honest assessment of challenges
• Strategic considerations
• What we need to achieve
• Internal discussion points

When to create: Always for important meetings with internal team

External Agenda (for all participants)

Clean, professional, focused:

• Clear objectives
• Structured agenda with times
• Discussion topics
• Decision items
• Professional tone

When to create: Every meeting

Agenda Types by Meeting Purpose

Decision Meeting: Meeting Details → Objective → Options (Pros/Cons) → Recommendation → Discussion → Decision → Action Items

Status Update: Meeting Details → Project Status → Progress → Upcoming Work → Blockers → Discussion → Action Items

Customer/External: Meeting Details → Objective → Agenda Items (timed) → Discussion Topics → Next Steps

Brainstorming: Meeting Details → Objective → Constraints → Ideas → Discussion → Next Steps

See reference/template-selection-guide.md for complete templates.

Research Enrichment Patterns

Beyond Notion content, add value through Claude's capabilities:

Technical Context: Explain technologies, architectures, or approaches. Provide industry standard practices. Compare common solutions. Suggest evaluation criteria.

Business Context: Industry trends affecting topic. Competitive landscape insights. Common challenges in space. ROI considerations.

Decision Support: Decision-making frameworks (e.g., RICE, cost-benefit). Risk assessment patterns. Trade-off analysis approaches. Success criteria suggestions.

Customer Context (for external meetings): Industry-specific challenges. Common pain points. Best practices from similar companies. Value proposition framing.

Process Guidance: Meeting facilitation techniques. Discussion frameworks. Retrospective patterns. Brainstorming structures.

Note: Use general knowledge and analytical capabilities. Don't fabricate specific facts. Clearly distinguish Notion facts from Claude insights.

Meeting Context Sources

Project Pages: Status, goals, team, timelines (most important) Previous Meeting Notes: Historical discussions, action items, decisions (recurring meetings) Task/Issue Database: Current status, blockers, completed/upcoming work (project meetings) Specifications/Designs: Requirements, decisions, approach, open questions (technical meetings) Reports/Dashboards: Metrics, KPIs, performance data, trends (executive meetings)

Linking Meetings to Projects

Forward Link: Add meeting to project page's "Meetings" section Backward Link: Include "Related Project" section in agenda with project mention Maintain bidirectional links for easy navigation

Meeting Series Management

Recurring Meetings: Create series parent page with schedule, meeting notes list, standing agenda, and action items tracker. Link individual meetings to parent.

Meeting Database: For organizations, use database with properties: Meeting Title, Date, Type (Decision/Status/Brainstorm), Project, Attendees, Status (Scheduled/Completed)

Post-Meeting Actions

Update agenda with:

Decisions: List each decision with rationale and owner Action Items: Checkbox list with owner and due date (consider creating tasks in database) Key Outcomes: Bullet list of main outcomes

Meeting Prep Timing

Day-Before (next-day meetings): Gather context → create agenda → share with attendees → allow review time Hour-Before (last-minute): Quick context → brief pre-read → basic agenda → essentials only Week-Before (major meetings): Comprehensive research → detailed pre-read → structured agenda → pre-meeting reviews

Best Practices

1. Create both documents: Internal pre-read + external agenda for important meetings
2. Distinguish sources: Label what's from Notion vs. Claude research
3. Start with search: Cast wide net in Notion, then narrow
4. Keep pre-read concise: 2-3 pages maximum, even with research
5. Professional external docs: Agenda should be polished and focused
6. Enrich thoughtfully: Claude research should add real value, not fluff
7. Link documents: Pre-read mentions agenda, agenda mentions pre-read
8. Include metrics: Data from Notion helps ground discussions
9. Share appropriately: Pre-read to internal team, agenda to all participants
10. Share early: Give attendees time to review (24hr+ for important meetings)
11. Update post-meeting: Capture decisions and actions in agenda

Advanced Features

Meeting templates: See reference/template-selection-guide.md for comprehensive template library

Common Issues

"Too much context": Split into pre-read (internal, comprehensive) and agenda (external, focused) "Can't find relevant pages": Broaden search, try different terms, ask user for page URLs "Meeting purpose unclear": Ask user to clarify before proceeding "No recent updates": Note that in pre-read, focus on historical context and strategic considerations "External meeting - no internal context": Create simpler structure with just agenda, skip internal pre-read or keep it minimal "Claude research too generic": Focus on specific insights relevant to the actual meeting topic, not general platitudes

Examples

See examples/ for complete workflows:

• examples/project-decision.md - Decision meeting prep with pre-read
• examples/sprint-planning.md - Sprint planning meeting
• examples/executive-review.md - Executive review prep
• examples/customer-meeting.md - External meeting with customer (pre-read + agenda)

Research & Documentation

Enables comprehensive research workflows: search for information across your Notion workspace, fetch and analyze relevant pages, synthesize findings, and create well-structured documentation.

Quick Start

When asked to research and document a topic:

1. Search for relevant content: Use Notion:notion-search to find pages
2. Fetch detailed information: Use Notion:notion-fetch to read full page content
3. Synthesize findings: Analyze and combine information from multiple sources
4. Create structured output: Use Notion:notion-create-pages to write documentation

Research Workflow

Step 1: Search for relevant information

Use Notion:notion-search with the research topic
Filter by teamspace if scope is known
Review search results to identify most relevant pages

Step 2: Fetch page content

Use Notion:notion-fetch for each relevant page URL
Collect content from all relevant sources
Note key findings, quotes, and data points

Step 3: Synthesize findings

Analyze the collected information:

• Identify key themes and patterns
• Connect related concepts across sources
• Note gaps or conflicting information
• Organize findings logically

Step 4: Create structured documentation

Use the appropriate documentation template (see reference/format-selection-guide.md) to structure output:

• Clear title and executive summary
• Well-organized sections with headings
• Citations linking back to source pages
• Actionable conclusions or next steps

Output Formats

Choose the appropriate format based on request:

Research Summary: See reference/research-summary-format.md Comprehensive Report: See reference/comprehensive-report-format.md Quick Brief: See reference/quick-brief-format.md

Best Practices

1. Cast a wide net first: Start with broad searches, then narrow down
2. Cite sources: Always link back to source pages using mentions
3. Verify recency: Check page last-edited dates for current information
4. Cross-reference: Validate findings across multiple sources
5. Structure clearly: Use headings, bullets, and formatting for readability

Page Placement

By default, create research documents as standalone pages. If the user specifies:

• A parent page → use page_id parent
• A database → fetch the database first, then use appropriate data_source_id
• A teamspace → create in that context

Advanced Features

Search filtering: See reference/advanced-search.md Citation styles: See reference/citations.md

Common Issues

"No results found": Try broader search terms or different teamspaces "Too many results": Add filters or search within specific pages "Can't access page": User may lack permissions, ask them to verify access

Examples

See examples/ for complete workflow demonstrations:

• examples/market-research.md - Researching market trends
• examples/technical-investigation.md - Technical deep-dive
• examples/competitor-analysis.md - Multi-source synthesis

Spec to Implementation

Transforms specifications into actionable implementation plans with progress tracking. Fetches spec documents, extracts requirements, breaks down into tasks, and manages implementation workflow.

Quick Start

When asked to implement a specification:

1. Find spec: Use Notion:notion-search to locate specification page
2. Fetch spec: Use Notion:notion-fetch to read specification content
3. Extract requirements: Parse and structure requirements from spec
4. Create plan: Use Notion:notion-create-pages for implementation plan
5. Find task database: Use Notion:notion-search to locate tasks database
6. Create tasks: Use Notion:notion-create-pages for individual tasks in task database
7. Track progress: Use Notion:notion-update-page to log progress and update status

Implementation Workflow

Step 1: Find the specification

1. Search for spec:
   - Use Notion:notion-search with spec name or topic
   - Apply filters if needed (e.g., created_date_range, teamspace_id)
   - Look for spec title or keyword matches
   - If not found or ambiguous, ask user for spec URL/ID

Example searches:
- "User Authentication spec"
- "Payment Integration specification"
- "Mobile App Redesign PRD"

Step 2: Fetch and analyze specification

1. Fetch spec page:
   - Use Notion:notion-fetch with spec URL/ID from search results
   - Read full content including requirements, design, constraints

2. Parse specification:
   - Identify functional requirements
   - Note non-functional requirements (performance, security, etc.)
   - Extract acceptance criteria
   - Identify dependencies and blockers

See reference/spec-parsing.md for parsing patterns.

Step 3: Create implementation plan

1. Break down into phases/milestones
2. Identify technical approach
3. List required tasks
4. Estimate effort
5. Identify risks

Use implementation plan template (see [reference/standard-implementation-plan.md](reference/standard-implementation-plan.md) or [reference/quick-implementation-plan.md](reference/quick-implementation-plan.md))

Step 4: Create implementation plan page

Use Notion:notion-create-pages:
- Title: "Implementation Plan: [Feature Name]"
- Content: Structured plan with phases, tasks, timeline
- Link back to original spec
- Add to appropriate location (project page, database)

Step 5: Find task database

1. Search for task database:
   - Use Notion:notion-search to find "Tasks" or "Task Management" database
   - Look for engineering/project task tracking system
   - If not found or ambiguous, ask user for database location

2. Fetch database schema:
   - Use Notion:notion-fetch with database URL/ID
   - Get property names, types, and options
   - Identify correct data source from <data-source> tags
   - Note required properties for new tasks

Step 6: Create implementation tasks

For each task in plan:
1. Create task in task database using Notion:notion-create-pages
2. Use parent: { data_source_id: 'collection://...' }
3. Set properties from schema:
   - Name/Title: Task description
   - Status: To Do
   - Priority: Based on criticality
   - Related Tasks: Link to spec and plan
4. Add implementation details in content

See reference/task-creation.md for task patterns.

Step 7: Begin implementation

1. Update task status to "In Progress"
2. Add initial progress note
3. Document approach and decisions
4. Link relevant resources

Step 8: Track progress

Regular updates:
1. Update task properties (status, progress)
2. Add progress notes with:
   - What's completed
   - Current focus
   - Blockers/issues
3. Update implementation plan with milestone completion
4. Link to related work (PRs, designs, etc.)

See reference/progress-tracking.md for tracking patterns.

Spec Analysis Patterns

Functional Requirements: User stories, feature descriptions, workflows, data requirements, integration points

Non-Functional Requirements: Performance targets, security requirements, scalability needs, availability, compliance

Acceptance Criteria: Testable conditions, user validation points, performance benchmarks, completion definitions

See reference/spec-parsing.md for detailed parsing techniques.

Implementation Plan Structure

Plan includes: Overview → Linked Spec → Requirements Summary → Technical Approach → Implementation Phases (Goal, Tasks checklist, Estimated effort) → Dependencies → Risks & Mitigation → Timeline → Success Criteria

See reference/standard-implementation-plan.md for full plan template.

Task Breakdown Patterns

By Component: Database, API endpoints, frontend components, integration, testing By Feature Slice: Vertical slices (auth flow, data entry, report generation) By Priority: P0 (must have), P1 (important), P2 (nice to have)

Progress Logging

Daily Updates (active work): Add progress note with completed items, current focus, blockers Milestone Updates (major progress): Update plan checkboxes, add milestone summary, adjust timeline Status Changes (task transitions): Update properties (In Progress → In Review → Done), add completion notes, link deliverables

Progress Format: Date heading → Completed → In Progress → Next Steps → Blockers → Notes

See reference/progress-tracking.md for detailed patterns.

Linking Spec to Implementation

Forward Links: Update spec page with "Implementation" section linking to plan and tasks Backward Links: Reference spec in plan and tasks with "Specification" section Bidirectional Traceability: Maintain both directions for easy tracking

Implementation Status Tracking

Plan Status: Update with phase completion (✅ Complete, 🔄 In Progress %, ⏳ Not Started) and overall percentage Task Aggregation: Query task database by plan ID to generate summary (complete, in progress, blocked, not started)

Handling Spec Changes

Detection: Fetch updated spec → compare with plan → identify new requirements → assess impact Propagation: Update plan → create new tasks → update affected tasks → add change note → notify via comments Change Log: Track spec evolution with date, what changed, and impact

Common Patterns

Feature Flag: Backend (behind flag) → Testing → Frontend (flagged) → Internal rollout → External rollout Database Migration: Schema design → Migration script → Staging test → Production migration → Validation API Development: API design → Backend implementation → Testing & docs → Client integration → Deployment

Best Practices

1. Always link spec and implementation: Maintain bidirectional references
2. Break down into small tasks: Each task should be completable in 1-2 days
3. Extract clear acceptance criteria: Know when "done" is done
4. Identify dependencies early: Note blockers in plan
5. Update progress regularly: Daily notes for active work
6. Track changes: Document spec updates and their impact
7. Use checklists: Visual progress indicators help everyone
8. Link deliverables: PRs, designs, docs should link back to tasks

Advanced Features

For additional implementation patterns and techniques, see the reference files in reference/.

Common Issues

"Can't find spec": Use Notion:notion-search with spec name/topic, try broader terms, or ask user for URL "Multiple specs found": Ask user which spec to implement or show options "Can't find task database": Search for "Tasks" or "Task Management", or ask user for database location "Spec unclear": Note ambiguities in plan, create clarification tasks "Requirements conflicting": Document conflicts, create decision task "Scope too large": Break into smaller specs/phases

Examples

See examples/ for complete workflows:

• examples/api-feature.md - API feature implementation
• examples/ui-component.md - Frontend component
• examples/database-migration.md - Schema changes

Raffle Winner Picker

This skill randomly selects winners from lists, spreadsheets, or Google Sheets for giveaways and contests.

When to Use This Skill

• Running social media giveaways
• Picking raffle winners at events
• Randomly selecting participants for surveys or tests
• Choosing winners from contest submissions
• Fair distribution of limited spots or resources
• Random team assignments

What This Skill Does

1. Random Selection: Uses cryptographically random selection
2. Multiple Sources: Works with CSV, Excel, Google Sheets, or plain lists
3. Multiple Winners: Can pick one or multiple winners
4. Duplicate Prevention: Ensures the same person can't win twice
5. Transparent Results: Shows the selection process clearly
6. Winner Details: Displays all relevant information about winners

How to Use

From Google Sheets

Pick a random row from this Google Sheet to select a winner 
for a giveaway: [Sheet URL]

From Local File

Pick 3 random winners from entries.csv

From List

Pick a random winner from this list:
- Alice (alice@email.com)
- Bob (bob@email.com)
- Carol (carol@email.com)
...

Multiple Winners

Pick 5 random winners from contest-entries.xlsx, 
make sure no duplicates

Example

User: "Pick a random row from this Google Sheet to select a winner for a giveaway."

Output:

Accessing Google Sheet...
Total entries found: 247

Randomly selecting winner...

🎉 WINNER SELECTED! 🎉

Row #142
Name: Sarah Johnson
Email: sarah.j@email.com
Entry Date: March 10, 2024
Comment: "Love your newsletter!"

Selection method: Cryptographically random
Timestamp: 2024-03-15 14:32:18 UTC

Would you like to:
- Pick another winner (excluding Sarah)?
- Export winner details?
- Pick runner-ups?

Inspired by: Lenny's use case - picking a Sora 2 giveaway winner from his subscriber Slack community

Features

Fair Selection

• Uses secure random number generation
• No bias or patterns
• Transparent process
• Repeatable with seed (for verification)

Exclusions

Pick a random winner excluding previous winners: 
Alice, Bob, Carol

Weighted Selection

Pick a winner with weighted probability based on 
the "entries" column (1 entry = 1 ticket)

Runner-ups

Pick 1 winner and 3 runner-ups from the list

Example Workflows

Social Media Giveaway

1. Export entries from Google Form to Sheets
2. "Pick a random winner from [Sheet URL]"
3. Verify winner details
4. Announce publicly with timestamp

Event Raffle

1. Create CSV of attendee names and emails
2. "Pick 10 random winners from attendees.csv"
3. Export winner list
4. Email winners directly

Team Assignment

1. Have list of participants
2. "Randomly split this list into 4 equal teams"
3. Review assignments
4. Share team rosters

Tips

• Document the process: Save the timestamp and method
• Public announcement: Share selection details for transparency
• Check eligibility: Verify winner meets contest rules
• Have backups: Pick runner-ups in case winner is ineligible
• Export results: Save winner list for records

Privacy & Fairness

✓ Uses cryptographically secure randomness ✓ No manipulation possible ✓ Timestamp recorded for verification ✓ Can provide seed for third-party verification ✓ Respects data privacy

Common Use Cases

• Newsletter subscriber giveaways
• Product launch raffles
• Conference ticket drawings
• Beta tester selection
• Focus group participant selection
• Random prize distribution at events

Resemble Detect — Deepfake Detection & Media Safety

Analyze audio, image, video, and text for synthetic manipulation, AI-generated content, watermarks, speaker identity, and media intelligence using the Resemble AI platform.

Core Principle — THE IRON LAW

"NEVER DECLARE MEDIA AS REAL OR FAKE WITHOUT A COMPLETED DETECTION RESULT."

Do not guess, infer, or speculate about media authenticity. Every authenticity claim must be backed by a completed Resemble detect job with a returned label, score, and status: "completed". If the detection is still processing, wait. If it failed, say so — do not substitute your own judgment.

When to Use

Use this skill whenever the user's request involves any of these:

• Checking if audio, video, image, or text is AI-generated or manipulated
• Detecting deepfakes in any media format
• Verifying media authenticity or provenance
• Identifying which AI platform synthesized audio (source tracing)
• Applying or detecting watermarks on media
• Analyzing media for speaker info, emotion, transcription, or misinformation
• Asking natural-language questions about detection results
• Matching or verifying speaker identity against known voice profiles
• Detecting AI-generated or machine-written text
• Any mention of: "deepfake", "fake detection", "synthetic media", "voice verification", "watermark", "media forensics", "authenticity check", "source tracing", "is this real", "AI-written text", "text detection"

Do NOT use for text-to-speech generation, voice cloning, or speech-to-text transcription — those are separate Resemble capabilities.

Capability Decision Tree

When multiple capabilities apply (e.g., user wants deepfake detection AND intelligence), combine them in a single POST /detect call using the intelligence: true flag rather than making separate requests.

Required Setup

• API Key: Bearer token from the Resemble AI dashboard
• Base URL: https://app.resemble.ai/api/v2
• Auth Header: Authorization: Bearer <RESEMBLE_API_KEY>
• Media Requirement: All media must be at a publicly accessible HTTPS URL

If the user provides a local file path instead of a URL, inform them the file must be hosted at a public HTTPS URL first. Do not attempt to upload local files to the API.

MCP Tools Available

When the Resemble MCP server is connected, use these tools instead of raw API calls:

Tool usage pattern: Use resemble_docs_lookup with topic "detect" to get the full picture, then resemble_api_endpoint for exact request/response schemas before making API calls.

Phase 1: Deepfake Detection

The core capability. Submit any audio, image, or video for AI-generated content analysis.

Submit a Detection

POST /detect
Content-Type: application/json
Authorization: Bearer <API_KEY>

{
  "url": "https://example.com/media.mp4",
  "visualize": true,
  "intelligence": true,
  "audio_source_tracing": true
}

Parameters:

Supported formats:

• Audio: WAV, MP3, OGG, M4A, FLAC
• Video: MP4, MOV, AVI, WMV
• Image: JPG, PNG, GIF, WEBP

Poll for Results

Detection is asynchronous. Poll GET /detect/{uuid} until status is "completed" or "failed".

GET /detect/{uuid}
Authorization: Bearer <API_KEY>

Polling best practice: Start at 2s intervals, back off to 5s, then 10s. Most detections complete within 10–60 seconds depending on media length.

Reading Results by Media Type

Audio results — in metrics:

{
  "label": "fake",
  "score": ["0.92", "0.88", "0.95"],
  "consistency": "0.91",
  "aggregated_score": "0.92",
  "image": "https://..."
}

• label: "fake" or "real" — the verdict
• score: Per-chunk prediction scores (array)
• aggregated_score: Overall confidence (0.0–1.0, higher = more likely synthetic)
• consistency: How consistent the prediction is across chunks
• image: Visualization heatmap URL (if visualize: true)

Image results — in image_metrics:

{
  "type": "ImageAnalysis",
  "label": "fake",
  "score": 0.87,
  "image": "https://...",
  "ifl": { "score": 0.82, "heatmap": "https://..." },
  "reverse_image_search_sources": [
    { "url": "...", "title": "...", "verdict": "known_fake", "similarity": 0.95 }
  ]
}

• label / score: Verdict and confidence
• ifl: Invisible Frequency Layer analysis with heatmap
• reverse_image_search_sources: Known sources found online (if use_reverse_search: true)

Video results — in video_metrics:

{
  "label": "fake",
  "score": 0.89,
  "certainty": 0.91,
  "children": [
    {
      "type": "VideoResult",
      "conclusion": "Fake",
      "score": 0.89,
      "timestamp": 2.5,
      "children": [...]
    }
  ]
}

• Hierarchical tree of frame-level and segment-level results
• Each child has timestamp, score, certainty, and may have nested children
• Video with audio track returns both metrics (audio) and video_metrics (visual)

Interpreting Scores

Always present scores with context. Say "The detection returned a score of 0.87, indicating high confidence that this audio is AI-generated" — never just "it's fake."

Phase 2: Intelligence — Media Analysis

Analyze media for rich structured insights independent of or alongside detection.

Standalone Intelligence

POST /intelligence
Content-Type: application/json
Authorization: Bearer <API_KEY>

{
  "url": "https://example.com/audio.mp3",
  "json": true
}

Parameters:

Audio/Video structured response (json: true):

• speaker_info — speaker description (age, gender)
• language / dialect — detected language
• emotion — detected emotional state
• speaking_style — conversational, formal, etc.
• context — inferred context of the speech
• message — content summary
• abnormalities — anomalies detected in the media
• transcription — full transcript
• translation — translation if non-English
• misinformation — misinformation analysis

Image structured response:

• scene_description — what the image shows
• subjects — people/objects identified
• authenticity_analysis — visual authenticity assessment
• context_and_setting — environment description
• abnormalities — visual anomalies
• misinformation — misinformation analysis

Detect Intelligence — Ask Questions About Results

After a detection completes, ask natural-language questions about it:

POST /detects/{detect_uuid}/intelligence
Content-Type: application/json
Authorization: Bearer <API_KEY>

{
  "query": "How confident is the model that this audio is fake?"
}

This returns a question UUID. Poll GET /detects/{detect_uuid}/intelligence/{question_uuid} until status is "completed" to get the answer.

Good questions to suggest:

• "Summarize the detection results in plain language"
• "What specific indicators suggest this is AI-generated?"
• "How do the audio and video detection results differ?"
• "What is the confidence level and what does it mean?"
• "Are there any inconsistencies in the analysis?"

Status flow: pending → processing → completed (or failed)

Prerequisite: The detection must have status: "completed". Submitting a question against a processing or failed detection returns a 422 error.

Phase 3: Audio Source Tracing

When audio is detected as synthetic (label: "fake"), identify which AI platform generated it.

Enable it by setting audio_source_tracing: true in the POST /detect request.

Result appears in the detection response under audio_source_tracing:

{
  "label": "elevenlabs",
  "error_message": null
}

Known source labels include: resemble_ai, elevenlabs, real, and others as the model expands.

Important: Source tracing only runs when audio is labeled as "fake". If the audio is "real", no source tracing result will appear.

Standalone query:

• GET /audio_source_tracings — list all source tracing reports
• GET /audio_source_tracings/{uuid} — get specific report

Phase 4: Watermarking

Apply invisible watermarks to media for provenance tracking, or detect existing watermarks.

Apply a Watermark

POST /watermark/apply
Content-Type: application/json
Authorization: Bearer <API_KEY>
Prefer: wait

{
  "url": "https://example.com/image.png",
  "strength": 0.3,
  "custom_message": "my-organization"
}

• Add Prefer: wait header for synchronous response
• Without it, poll GET /watermark/apply/{uuid}/result
• Response includes watermarked_media URL to download the watermarked file

Detect a Watermark

POST /watermark/detect
Content-Type: application/json
Authorization: Bearer <API_KEY>
Prefer: wait

{
  "url": "https://example.com/suspect-image.png"
}

Audio detection result:

{ "has_watermark": true, "confidence": 0.95 }

Image/Video detection result:

{ "has_watermark": true }

Phase 5: Identity — Speaker Verification (Beta)

Create voice identity profiles and match incoming audio against them.

Beta feature — requires joining the preview program. Inform the user if they encounter access errors.

Create an Identity Profile

POST /identity
Content-Type: application/json
Authorization: Bearer <API_KEY>

{
  "audio_url": "https://example.com/known-speaker.wav",
  "name": "Jane Doe"
}

Search Against Known Identities

POST /identity/search
Content-Type: application/json
Authorization: Bearer <API_KEY>

{
  "audio_url": "https://example.com/unknown-speaker.wav",
  "top_k": 5
}

Response:

{
  "success": true,
  "item": [
    { "uuid": "...", "name": "Jane Doe", "confidence": 0.92, "distance": 0.08 }
  ]
}

Lower distance = closer match. Higher confidence = stronger match.

Phase 6: Text Detection

Detect whether text content is AI-generated or human-written.

Beta feature — requires the detect_beta_user role or a billing plan that includes the dfd_text product.

Submit a Text Detection

POST /text_detect
Content-Type: application/json
Authorization: Bearer <API_KEY>

Add the Prefer: wait header for a synchronous (blocking) response. Without it, the job runs asynchronously — poll or use a callback.

Parameters:

Response:

{
  "success": true,
  "item": {
    "uuid": "abc-123",
    "status": "completed",
    "prediction": "ai",
    "confidence": 0.91,
    "text_content": "This is some text to analyze.",
    "privacy_mode": false,
    "created_at": "...",
    "updated_at": "..."
  }
}

• prediction: "ai" or "human" — the verdict
• confidence: 0.0–1.0, higher = more confident in the prediction
• status: "processing", "completed", or "failed"

Poll for Results

If you did not use Prefer: wait, poll until status is "completed" or "failed":

GET /text_detect/{uuid}
Authorization: Bearer <API_KEY>

List Text Detections

GET /text_detect
Authorization: Bearer <API_KEY>

Returns paginated text detections for the team.

Callback

If callback_url was provided, a POST is sent on completion:

{ "success": true, "item": { ... } }

On failure:

{ "success": false, "item": { ... }, "error": "Error message here" }

Recommended Workflows

Full Media Forensics (Most Thorough)

For a comprehensive analysis, combine all capabilities:

1. Submit detection with all flags enabled:

   {
     "url": "https://example.com/suspect.mp4",
     "visualize": true,
     "intelligence": true,
     "audio_source_tracing": true,
     "use_reverse_search": true
   }
   

2. Poll until status: "completed"
3. Read metrics / image_metrics / video_metrics for the verdict
4. Read intelligence.description for structured media analysis
5. If audio labeled "fake", check audio_source_tracing.label for the source platform
6. Ask follow-up questions via Detect Intelligence if anything needs clarification
7. Check for watermarks via POST /watermark/detect if provenance is relevant

Quick Authenticity Check (Fastest)

For a fast pass/fail:

1. Submit minimal detection: { "url": "..." }
2. Poll until complete
3. Check label and aggregated_score (audio) or label and score (image/video)
4. Report result with score context

Provenance Pipeline (Content Creators)

For creators who want to prove their content is authentic:

1. Apply watermark to original content: POST /watermark/apply
2. Distribute watermarked media
3. Later, verify provenance: POST /watermark/detect against any copy

Red Flags — Stop and Reassess

• Declaring authenticity without a detection result — Never say media is real or fake based on visual/auditory inspection alone
• Ignoring the score and reporting only the label — A "fake" label with score 0.51 means something very different from score 0.95
• Submitting local file paths to the API — The API requires publicly accessible HTTPS URLs (does not apply to text detection)
• Sending text longer than 100,000 characters to text detection — Split into chunks or inform the user of the limit
• Polling too aggressively — Start at 2s intervals, back off exponentially; do not loop at <1s
• Asking Detect Intelligence questions before detection completes — Results in 422 error
• Expecting source tracing on "real" audio — Source tracing only runs on audio labeled "fake"
• Treating beta features (Identity) as production-ready — Warn users about beta status
• Ignoring zero_retention_mode for sensitive media — Always suggest this flag when the user indicates the media is sensitive or private
• Making multiple separate API calls when flags can combine — Use intelligence: true and audio_source_tracing: true on the detection call instead of separate requests

Response Presentation Guidelines

When presenting results to users:

1. Lead with the verdict — "The detection indicates this audio is likely AI-generated (score: 0.87)"
2. Provide score context — Use the score interpretation table above
3. Mention limitations — Detection is probabilistic, not absolute proof
4. Include actionable next steps — Suggest intelligence queries, source tracing, or watermark checks as appropriate
5. For inconclusive results (0.3–0.5) — Explicitly state the result is inconclusive and recommend additional analysis with different parameters or manual review
6. Never present detection as legal evidence — Detection results are analytical tools, not forensic certifications

Error Handling

Privacy & Compliance Notes

• Zero retention mode: Set zero_retention_mode: true to auto-delete media after analysis. The URL is redacted and media_deleted is set to true post-completion.
• Text privacy mode: Set privacy_mode: true on text detection to prevent text content from being stored after analysis.
• Data handling: Media URLs and text content are stored by default. For GDPR/compliance-sensitive workflows, enable zero retention (media) or privacy mode (text).
• Callback security: If using callback_url, ensure the endpoint is HTTPS and authenticated on the receiving end.

Skill Creator

This skill provides guidance for creating effective skills.

About Skills

Skills are modular, self-contained packages that extend Claude's capabilities by providing specialized knowledge, workflows, and tools. Think of them as "onboarding guides" for specific domains or tasks—they transform Claude from a general-purpose agent into a specialized agent equipped with procedural knowledge that no model can fully possess.

What Skills Provide

1. Specialized workflows - Multi-step procedures for specific domains
2. Tool integrations - Instructions for working with specific file formats or APIs
3. Domain expertise - Company-specific knowledge, schemas, business logic
4. Bundled resources - Scripts, references, and assets for complex and repetitive tasks

Anatomy of a Skill

Every skill consists of a required SKILL.md file and optional bundled resources:

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter metadata (required)
│   │   ├── name: (required)
│   │   └── description: (required)
│   └── Markdown instructions (required)
└── Bundled Resources (optional)
    ├── scripts/          - Executable code (Python/Bash/etc.)
    ├── references/       - Documentation intended to be loaded into context as needed
    └── assets/           - Files used in output (templates, icons, fonts, etc.)

SKILL.md (required)

Metadata Quality: The name and description in YAML frontmatter determine when Claude will use the skill. Be specific about what the skill does and when to use it. Use the third-person (e.g. "This skill should be used when..." instead of "Use this skill when...").

Bundled Resources (optional)

Scripts (scripts/)

Executable code (Python/Bash/etc.) for tasks that require deterministic reliability or are repeatedly rewritten.

• When to include: When the same code is being rewritten repeatedly or deterministic reliability is needed
• Example: scripts/rotate_pdf.py for PDF rotation tasks
• Benefits: Token efficient, deterministic, may be executed without loading into context
• Note: Scripts may still need to be read by Claude for patching or environment-specific adjustments

References (references/)

Documentation and reference material intended to be loaded as needed into context to inform Claude's process and thinking.

• When to include: For documentation that Claude should reference while working
• Examples: references/finance.md for financial schemas, references/mnda.md for company NDA template, references/policies.md for company policies, references/api_docs.md for API specifications
• Use cases: Database schemas, API documentation, domain knowledge, company policies, detailed workflow guides
• Benefits: Keeps SKILL.md lean, loaded only when Claude determines it's needed
• Best practice: If files are large (>10k words), include grep search patterns in SKILL.md
• Avoid duplication: Information should live in either SKILL.md or references files, not both. Prefer references files for detailed information unless it's truly core to the skill—this keeps SKILL.md lean while making information discoverable without hogging the context window. Keep only essential procedural instructions and workflow guidance in SKILL.md; move detailed reference material, schemas, and examples to references files.

Assets (assets/)

Files not intended to be loaded into context, but rather used within the output Claude produces.

• When to include: When the skill needs files that will be used in the final output
• Examples: assets/logo.png for brand assets, assets/slides.pptx for PowerPoint templates, assets/frontend-template/ for HTML/React boilerplate, assets/font.ttf for typography
• Use cases: Templates, images, icons, boilerplate code, fonts, sample documents that get copied or modified
• Benefits: Separates output resources from documentation, enables Claude to use files without loading them into context

Progressive Disclosure Design Principle

Skills use a three-level loading system to manage context efficiently:

1. Metadata (name + description) - Always in context (~100 words)
2. SKILL.md body - When skill triggers (<5k words)
3. Bundled resources - As needed by Claude (Unlimited*)

*Unlimited because scripts can be executed without reading into context window.

Skill Creation Process

To create a skill, follow the "Skill Creation Process" in order, skipping steps only if there is a clear reason why they are not applicable.

Step 1: Understanding the Skill with Concrete Examples

Skip this step only when the skill's usage patterns are already clearly understood. It remains valuable even when working with an existing skill.

To create an effective skill, clearly understand concrete examples of how the skill will be used. This understanding can come from either direct user examples or generated examples that are validated with user feedback.

For example, when building an image-editor skill, relevant questions include:

• "What functionality should the image-editor skill support? Editing, rotating, anything else?"
• "Can you give some examples of how this skill would be used?"
• "I can imagine users asking for things like 'Remove the red-eye from this image' or 'Rotate this image'. Are there other ways you imagine this skill being used?"
• "What would a user say that should trigger this skill?"

To avoid overwhelming users, avoid asking too many questions in a single message. Start with the most important questions and follow up as needed for better effectiveness.

Conclude this step when there is a clear sense of the functionality the skill should support.

Step 2: Planning the Reusable Skill Contents

To turn concrete examples into an effective skill, analyze each example by:

1. Considering how to execute on the example from scratch
2. Identifying what scripts, references, and assets would be helpful when executing these workflows repeatedly

Example: When building a pdf-editor skill to handle queries like "Help me rotate this PDF," the analysis shows:

1. Rotating a PDF requires re-writing the same code each time
2. A scripts/rotate_pdf.py script would be helpful to store in the skill

Example: When designing a frontend-webapp-builder skill for queries like "Build me a todo app" or "Build me a dashboard to track my steps," the analysis shows:

1. Writing a frontend webapp requires the same boilerplate HTML/React each time
2. An assets/hello-world/ template containing the boilerplate HTML/React project files would be helpful to store in the skill

Example: When building a big-query skill to handle queries like "How many users have logged in today?" the analysis shows:

1. Querying BigQuery requires re-discovering the table schemas and relationships each time
2. A references/schema.md file documenting the table schemas would be helpful to store in the skill

To establish the skill's contents, analyze each concrete example to create a list of the reusable resources to include: scripts, references, and assets.

Step 3: Initializing the Skill

At this point, it is time to actually create the skill.

Skip this step only if the skill being developed already exists, and iteration or packaging is needed. In this case, continue to the next step.

When creating a new skill from scratch, always run the init_skill.py script. The script conveniently generates a new template skill directory that automatically includes everything a skill requires, making the skill creation process much more efficient and reliable.

Usage:

scripts/init_skill.py <skill-name> --path <output-directory>

The script:

• Creates the skill directory at the specified path
• Generates a SKILL.md template with proper frontmatter and TODO placeholders
• Creates example resource directories: scripts/, references/, and assets/
• Adds example files in each directory that can be customized or deleted

After initialization, customize or remove the generated SKILL.md and example files as needed.

Step 4: Edit the Skill

When editing the (newly-generated or existing) skill, remember that the skill is being created for another instance of Claude to use. Focus on including information that would be beneficial and non-obvious to Claude. Consider what procedural knowledge, domain-specific details, or reusable assets would help another Claude instance execute these tasks more effectively.

Start with Reusable Skill Contents

To begin implementation, start with the reusable resources identified above: scripts/, references/, and assets/ files. Note that this step may require user input. For example, when implementing a brand-guidelines skill, the user may need to provide brand assets or templates to store in assets/, or documentation to store in references/.

Also, delete any example files and directories not needed for the skill. The initialization script creates example files in scripts/, references/, and assets/ to demonstrate structure, but most skills won't need all of them.

Update SKILL.md

Writing Style: Write the entire skill using imperative/infinitive form (verb-first instructions), not second person. Use objective, instructional language (e.g., "To accomplish X, do Y" rather than "You should do X" or "If you need to do X"). This maintains consistency and clarity for AI consumption.

To complete SKILL.md, answer the following questions:

1. What is the purpose of the skill, in a few sentences?
2. When should the skill be used?
3. In practice, how should Claude use the skill? All reusable skill contents developed above should be referenced so that Claude knows how to use them.

Step 5: Packaging a Skill

Once the skill is ready, it should be packaged into a distributable zip file that gets shared with the user. The packaging process automatically validates the skill first to ensure it meets all requirements:

scripts/package_skill.py <path/to/skill-folder>

Optional output directory specification:

scripts/package_skill.py <path/to/skill-folder> ./dist

The packaging script will:

1. Validate the skill automatically, checking:

   • YAML frontmatter format and required fields
   • Skill naming conventions and directory structure
   • Description completeness and quality
   • File organization and resource references

2. Package the skill if validation passes, creating a zip file named after the skill (e.g., my-skill.zip) that includes all files and maintains the proper directory structure for distribution.

If validation fails, the script will report the errors and exit without creating a package. Fix any validation errors and run the packaging command again.

Step 6: Iterate

After testing the skill, users may request improvements. Often this happens right after using the skill, with fresh context of how the skill performed.

Iteration workflow:

1. Use the skill on real tasks
2. Notice struggles or inefficiencies
3. Identify how SKILL.md or bundled resources should be updated
4. Implement changes and test again

Slack GIF Creator - Flexible Toolkit

A toolkit for creating animated GIFs optimized for Slack. Provides validators for Slack's constraints, composable animation primitives, and optional helper utilities. Apply these tools however needed to achieve the creative vision.

Slack's Requirements

Slack has specific requirements for GIFs based on their use:

Message GIFs:

• Max size: ~2MB
• Optimal dimensions: 480x480
• Typical FPS: 15-20
• Color limit: 128-256
• Duration: 2-5s

Emoji GIFs:

• Max size: 64KB (strict limit)
• Optimal dimensions: 128x128
• Typical FPS: 10-12
• Color limit: 32-48
• Duration: 1-2s

Emoji GIFs are challenging - the 64KB limit is strict. Strategies that help:

• Limit to 10-15 frames total
• Use 32-48 colors maximum
• Keep designs simple
• Avoid gradients
• Validate file size frequently

Toolkit Structure

This skill provides three types of tools:

1. Validators - Check if a GIF meets Slack's requirements
2. Animation Primitives - Composable building blocks for motion (shake, bounce, move, kaleidoscope)
3. Helper Utilities - Optional functions for common needs (text, colors, effects)

Complete creative freedom is available in how these tools are applied.

Core Validators

To ensure a GIF meets Slack's constraints, use these validators:

from core.gif_builder import GIFBuilder

# After creating your GIF, check if it meets requirements
builder = GIFBuilder(width=128, height=128, fps=10)
# ... add your frames however you want ...

# Save and check size
info = builder.save('emoji.gif', num_colors=48, optimize_for_emoji=True)

# The save method automatically warns if file exceeds limits
# info dict contains: size_kb, size_mb, frame_count, duration_seconds

File size validator:

from core.validators import check_slack_size

# Check if GIF meets size limits
passes, info = check_slack_size('emoji.gif', is_emoji=True)
# Returns: (True/False, dict with size details)

Dimension validator:

from core.validators import validate_dimensions

# Check dimensions
passes, info = validate_dimensions(128, 128, is_emoji=True)
# Returns: (True/False, dict with dimension details)

Complete validation:

from core.validators import validate_gif, is_slack_ready

# Run all validations
all_pass, results = validate_gif('emoji.gif', is_emoji=True)

# Or quick check
if is_slack_ready('emoji.gif', is_emoji=True):
    print("Ready to upload!")

Animation Primitives

These are composable building blocks for motion. Apply these to any object in any combination:

Shake

from templates.shake import create_shake_animation

# Shake an emoji
frames = create_shake_animation(
    object_type='emoji',
    object_data={'emoji': '😱', 'size': 80},
    num_frames=20,
    shake_intensity=15,
    direction='both'  # or 'horizontal', 'vertical'
)

Bounce

from templates.bounce import create_bounce_animation

# Bounce a circle
frames = create_bounce_animation(
    object_type='circle',
    object_data={'radius': 40, 'color': (255, 100, 100)},
    num_frames=30,
    bounce_height=150
)

Spin / Rotate

from templates.spin import create_spin_animation, create_loading_spinner

# Clockwise spin
frames = create_spin_animation(
    object_type='emoji',
    object_data={'emoji': '🔄', 'size': 100},
    rotation_type='clockwise',
    full_rotations=2
)

# Wobble rotation
frames = create_spin_animation(rotation_type='wobble', full_rotations=3)

# Loading spinner
frames = create_loading_spinner(spinner_type='dots')

Pulse / Heartbeat

from templates.pulse import create_pulse_animation, create_attention_pulse

# Smooth pulse
frames = create_pulse_animation(
    object_data={'emoji': '❤️', 'size': 100},
    pulse_type='smooth',
    scale_range=(0.8, 1.2)
)

# Heartbeat (double-pump)
frames = create_pulse_animation(pulse_type='heartbeat')

# Attention pulse for emoji GIFs
frames = create_attention_pulse(emoji='⚠️', num_frames=20)

Fade

from templates.fade import create_fade_animation, create_crossfade

# Fade in
frames = create_fade_animation(fade_type='in')

# Fade out
frames = create_fade_animation(fade_type='out')

# Crossfade between two emojis
frames = create_crossfade(
    object1_data={'emoji': '😊', 'size': 100},
    object2_data={'emoji': '😂', 'size': 100}
)

Zoom

from templates.zoom import create_zoom_animation, create_explosion_zoom

# Zoom in dramatically
frames = create_zoom_animation(
    zoom_type='in',
    scale_range=(0.1, 2.0),
    add_motion_blur=True
)

# Zoom out
frames = create_zoom_animation(zoom_type='out')

# Explosion zoom
frames = create_explosion_zoom(emoji='💥')

Explode / Shatter

from templates.explode import create_explode_animation, create_particle_burst

# Burst explosion
frames = create_explode_animation(
    explode_type='burst',
    num_pieces=25
)

# Shatter effect
frames = create_explode_animation(explode_type='shatter')

# Dissolve into particles
frames = create_explode_animation(explode_type='dissolve')

# Particle burst
frames = create_particle_burst(particle_count=30)

Wiggle / Jiggle

from templates.wiggle import create_wiggle_animation, create_excited_wiggle

# Jello wobble
frames = create_wiggle_animation(
    wiggle_type='jello',
    intensity=1.0,
    cycles=2
)

# Wave motion
frames = create_wiggle_animation(wiggle_type='wave')

# Excited wiggle for emoji GIFs
frames = create_excited_wiggle(emoji='🎉')

Slide

from templates.slide import create_slide_animation, create_multi_slide

# Slide in from left with overshoot
frames = create_slide_animation(
    direction='left',
    slide_type='in',
    overshoot=True
)

# Slide across
frames = create_slide_animation(direction='left', slide_type='across')

# Multiple objects sliding in sequence
objects = [
    {'data': {'emoji': '🎯', 'size': 60}, 'direction': 'left', 'final_pos': (120, 240)},
    {'data': {'emoji': '🎪', 'size': 60}, 'direction': 'right', 'final_pos': (240, 240)}
]
frames = create_multi_slide(objects, stagger_delay=5)

Flip

from templates.flip import create_flip_animation, create_quick_flip

# Horizontal flip between two emojis
frames = create_flip_animation(
    object1_data={'emoji': '😊', 'size': 120},
    object2_data={'emoji': '😂', 'size': 120},
    flip_axis='horizontal'
)

# Vertical flip
frames = create_flip_animation(flip_axis='vertical')

# Quick flip for emoji GIFs
frames = create_quick_flip('👍', '👎')

Morph / Transform

from templates.morph import create_morph_animation, create_reaction_morph

# Crossfade morph
frames = create_morph_animation(
    object1_data={'emoji': '😊', 'size': 100},
    object2_data={'emoji': '😂', 'size': 100},
    morph_type='crossfade'
)

# Scale morph (shrink while other grows)
frames = create_morph_animation(morph_type='scale')

# Spin morph (3D flip-like)
frames = create_morph_animation(morph_type='spin_morph')

Move Effect

from templates.move import create_move_animation

# Linear movement
frames = create_move_animation(
    object_type='emoji',
    object_data={'emoji': '🚀', 'size': 60},
    start_pos=(50, 240),
    end_pos=(430, 240),
    motion_type='linear',
    easing='ease_out'
)

# Arc movement (parabolic trajectory)
frames = create_move_animation(
    object_type='emoji',
    object_data={'emoji': '⚽', 'size': 60},
    start_pos=(50, 350),
    end_pos=(430, 350),
    motion_type='arc',
    motion_params={'arc_height': 150}
)

# Circular movement
frames = create_move_animation(
    object_type='emoji',
    object_data={'emoji': '🌍', 'size': 50},
    motion_type='circle',
    motion_params={
        'center': (240, 240),
        'radius': 120,
        'angle_range': 360  # full circle
    }
)

# Wave movement
frames = create_move_animation(
    motion_type='wave',
    motion_params={
        'wave_amplitude': 50,
        'wave_frequency': 2
    }
)

# Or use low-level easing functions
from core.easing import interpolate, calculate_arc_motion

for i in range(num_frames):
    t = i / (num_frames - 1)
    x = interpolate(start_x, end_x, t, easing='ease_out')
    # Or: x, y = calculate_arc_motion(start, end, height, t)

Kaleidoscope Effect

from templates.kaleidoscope import apply_kaleidoscope, create_kaleidoscope_animation

# Apply to a single frame
kaleido_frame = apply_kaleidoscope(frame, segments=8)

# Or create animated kaleidoscope
frames = create_kaleidoscope_animation(
    base_frame=my_frame,  # or None for demo pattern
    num_frames=30,
    segments=8,
    rotation_speed=1.0
)

# Simple mirror effects (faster)
from templates.kaleidoscope import apply_simple_mirror

mirrored = apply_simple_mirror(frame, mode='quad')  # 4-way mirror
# modes: 'horizontal', 'vertical', 'quad', 'radial'

To compose primitives freely, follow these patterns:

# Example: Bounce + shake for impact
for i in range(num_frames):
    frame = create_blank_frame(480, 480, bg_color)

    # Bounce motion
    t_bounce = i / (num_frames - 1)
    y = interpolate(start_y, ground_y, t_bounce, 'bounce_out')

    # Add shake on impact (when y reaches ground)
    if y >= ground_y - 5:
        shake_x = math.sin(i * 2) * 10
        x = center_x + shake_x
    else:
        x = center_x

    draw_emoji(frame, '⚽', (x, y), size=60)
    builder.add_frame(frame)

Helper Utilities

These are optional helpers for common needs. Use, modify, or replace these with custom implementations as needed.

GIF Builder (Assembly & Optimization)

from core.gif_builder import GIFBuilder

# Create builder with your chosen settings
builder = GIFBuilder(width=480, height=480, fps=20)

# Add frames (however you created them)
for frame in my_frames:
    builder.add_frame(frame)

# Save with optimization
builder.save('output.gif',
             num_colors=128,
             optimize_for_emoji=False)

Key features:

• Automatic color quantization
• Duplicate frame removal
• Size warnings for Slack limits
• Emoji mode (aggressive optimization)

Text Rendering

For small GIFs like emojis, text readability is challenging. A common solution involves adding outlines:

from core.typography import draw_text_with_outline, TYPOGRAPHY_SCALE

# Text with outline (helps readability)
draw_text_with_outline(
    frame, "BONK!",
    position=(240, 100),
    font_size=TYPOGRAPHY_SCALE['h1'],  # 60px
    text_color=(255, 68, 68),
    outline_color=(0, 0, 0),
    outline_width=4,
    centered=True
)

To implement custom text rendering, use PIL's ImageDraw.text() which works fine for larger GIFs.

Color Management

Professional-looking GIFs often use cohesive color palettes:

from core.color_palettes import get_palette

# Get a pre-made palette
palette = get_palette('vibrant')  # or 'pastel', 'dark', 'neon', 'professional'

bg_color = palette['background']
text_color = palette['primary']
accent_color = palette['accent']

To work with colors directly, use RGB tuples - whatever works for the use case.

Visual Effects

Optional effects for impact moments:

from core.visual_effects import ParticleSystem, create_impact_flash, create_shockwave_rings

# Particle system
particles = ParticleSystem()
particles.emit_sparkles(x=240, y=200, count=15)
particles.emit_confetti(x=240, y=200, count=20)

# Update and render each frame
particles.update()
particles.render(frame)

# Flash effect
frame = create_impact_flash(frame, position=(240, 200), radius=100)

# Shockwave rings
frame = create_shockwave_rings(frame, position=(240, 200), radii=[30, 60, 90])

Easing Functions

Smooth motion uses easing instead of linear interpolation:

from core.easing import interpolate

# Object falling (accelerates)
y = interpolate(start=0, end=400, t=progress, easing='ease_in')

# Object landing (decelerates)
y = interpolate(start=0, end=400, t=progress, easing='ease_out')

# Bouncing
y = interpolate(start=0, end=400, t=progress, easing='bounce_out')

# Overshoot (elastic)
scale = interpolate(start=0.5, end=1.0, t=progress, easing='elastic_out')

Available easings: linear, ease_in, ease_out, ease_in_out, bounce_out, elastic_out, back_out (overshoot), and more in core/easing.py.

Frame Composition

Basic drawing utilities if you need them:

from core.frame_composer import (
    create_gradient_background,  # Gradient backgrounds
    draw_emoji_enhanced,         # Emoji with optional shadow
    draw_circle_with_shadow,     # Shapes with depth
    draw_star                    # 5-pointed stars
)

# Gradient background
frame = create_gradient_background(480, 480, top_color, bottom_color)

# Emoji with shadow
draw_emoji_enhanced(frame, '🎉', position=(200, 200), size=80, shadow=True)

Optimization Strategies

When your GIF is too large:

For Message GIFs (>2MB):

1. Reduce frames (lower FPS or shorter duration)
2. Reduce colors (128 → 64 colors)
3. Reduce dimensions (480x480 → 320x320)
4. Enable duplicate frame removal

For Emoji GIFs (>64KB) - be aggressive:

1. Limit to 10-12 frames total
2. Use 32-40 colors maximum
3. Avoid gradients (solid colors compress better)
4. Simplify design (fewer elements)
5. Use optimize_for_emoji=True in save method

Example Composition Patterns

Simple Reaction (Pulsing)

builder = GIFBuilder(128, 128, 10)

for i in range(12):
    frame = Image.new('RGB', (128, 128), (240, 248, 255))

    # Pulsing scale
    scale = 1.0 + math.sin(i * 0.5) * 0.15
    size = int(60 * scale)

    draw_emoji_enhanced(frame, '😱', position=(64-size//2, 64-size//2),
                       size=size, shadow=False)
    builder.add_frame(frame)

builder.save('reaction.gif', num_colors=40, optimize_for_emoji=True)

# Validate
from core.validators import check_slack_size
check_slack_size('reaction.gif', is_emoji=True)

Action with Impact (Bounce + Flash)

builder = GIFBuilder(480, 480, 20)

# Phase 1: Object falls
for i in range(15):
    frame = create_gradient_background(480, 480, (240, 248, 255), (200, 230, 255))
    t = i / 14
    y = interpolate(0, 350, t, 'ease_in')
    draw_emoji_enhanced(frame, '⚽', position=(220, int(y)), size=80)
    builder.add_frame(frame)

# Phase 2: Impact + flash
for i in range(8):
    frame = create_gradient_background(480, 480, (240, 248, 255), (200, 230, 255))

    # Flash on first frames
    if i < 3:
        frame = create_impact_flash(frame, (240, 350), radius=120, intensity=0.6)

    draw_emoji_enhanced(frame, '⚽', position=(220, 350), size=80)

    # Text appears
    if i > 2:
        draw_text_with_outline(frame, "GOAL!", position=(240, 150),
                              font_size=60, text_color=(255, 68, 68),
                              outline_color=(0, 0, 0), outline_width=4, centered=True)

    builder.add_frame(frame)

builder.save('goal.gif', num_colors=128)

Combining Primitives (Move + Shake)

from templates.shake import create_shake_animation

# Create shake animation
shake_frames = create_shake_animation(
    object_type='emoji',
    object_data={'emoji': '😰', 'size': 70},
    num_frames=20,
    shake_intensity=12
)

# Create moving element that triggers the shake
builder = GIFBuilder(480, 480, 20)
for i in range(40):
    t = i / 39

    if i < 20:
        # Before trigger - use blank frame with moving object
        frame = create_blank_frame(480, 480, (255, 255, 255))
        x = interpolate(50, 300, t * 2, 'linear')
        draw_emoji_enhanced(frame, '🚗', position=(int(x), 300), size=60)
        draw_emoji_enhanced(frame, '😰', position=(350, 200), size=70)
    else:
        # After trigger - use shake frame
        frame = shake_frames[i - 20]
        # Add the car in final position
        draw_emoji_enhanced(frame, '🚗', position=(300, 300), size=60)

    builder.add_frame(frame)

builder.save('scare.gif')

Philosophy

This toolkit provides building blocks, not rigid recipes. To work with a GIF request:

1. Understand the creative vision - What should happen? What's the mood?
2. Design the animation - Break it into phases (anticipation, action, reaction)
3. Apply primitives as needed - Shake, bounce, move, effects - mix freely
4. Validate constraints - Check file size, especially for emoji GIFs
5. Iterate if needed - Reduce frames/colors if over size limits

The goal is creative freedom within Slack's technical constraints.

Dependencies

To use this toolkit, install these dependencies only if they aren't already present:

pip install pillow imageio numpy

Theme Factory Skill

This skill provides a curated collection of professional font and color themes themes, each with carefully selected color palettes and font pairings. Once a theme is chosen, it can be applied to any artifact.

Purpose

To apply consistent, professional styling to presentation slide decks, use this skill. Each theme includes:

• A cohesive color palette with hex codes
• Complementary font pairings for headers and body text
• A distinct visual identity suitable for different contexts and audiences

Usage Instructions

To apply styling to a slide deck or other artifact:

1. Show the theme showcase: Display the theme-showcase.pdf file to allow users to see all available themes visually. Do not make any modifications to it; simply show the file for viewing.
2. Ask for their choice: Ask which theme to apply to the deck
3. Wait for selection: Get explicit confirmation about the chosen theme
4. Apply the theme: Once a theme has been chosen, apply the selected theme's colors and fonts to the deck/artifact

Themes Available

The following 10 themes are available, each showcased in theme-showcase.pdf:

1. Ocean Depths - Professional and calming maritime theme
2. Sunset Boulevard - Warm and vibrant sunset colors
3. Forest Canopy - Natural and grounded earth tones
4. Modern Minimalist - Clean and contemporary grayscale
5. Golden Hour - Rich and warm autumnal palette
6. Arctic Frost - Cool and crisp winter-inspired theme
7. Desert Rose - Soft and sophisticated dusty tones
8. Tech Innovation - Bold and modern tech aesthetic
9. Botanical Garden - Fresh and organic garden colors
10. Midnight Galaxy - Dramatic and cosmic deep tones

Theme Details

Each theme is defined in the themes/ directory with complete specifications including:

• Cohesive color palette with hex codes
• Complementary font pairings for headers and body text
• Distinct visual identity suitable for different contexts and audiences

Application Process

After a preferred theme is selected:

1. Read the corresponding theme file from the themes/ directory
2. Apply the specified colors and fonts consistently throughout the deck
3. Ensure proper contrast and readability
4. Maintain the theme's visual identity across all slides

Create your Own Theme

To handle cases where none of the existing themes work for an artifact, create a custom theme. Based on provided inputs, generate a new theme similar to the ones above. Give the theme a similar name describing what the font/color combinations represent. Use any basic description provided to choose appropriate colors/fonts. After generating the theme, show it for review and verification. Following that, apply the theme as described above.

Video Downloader

This skill downloads videos from YouTube and other platforms directly to your computer.

When to Use This Skill

• Downloading YouTube videos for offline viewing
• Saving educational content for reference
• Archiving important videos
• Getting video files for editing or repurposing
• Downloading your own content from platforms
• Saving conference talks or webinars

What This Skill Does

1. Downloads Videos: Fetches videos from YouTube and other platforms
2. Quality Selection: Lets you choose resolution (480p, 720p, 1080p, 4K)
3. Format Options: Downloads in various formats (MP4, WebM, audio-only)
4. Batch Downloads: Can download multiple videos or playlists
5. Metadata Preservation: Saves title, description, and thumbnail

How to Use

Basic Download

Download this YouTube video: https://youtube.com/watch?v=...

Download this video in 1080p quality

Audio Only

Download the audio from this YouTube video as MP3

Playlist Download

Download all videos from this YouTube playlist: [URL]

Batch Download

Download these 5 YouTube videos:
1. [URL]
2. [URL]
...

Example

User: "Download this YouTube video: https://youtube.com/watch?v=abc123"

Output:

Downloading from YouTube...

Video: "How to Build Products Users Love"
Channel: Lenny's Podcast
Duration: 45:32
Quality: 1080p

Progress: ████████████████████ 100%

✓ Downloaded: how-to-build-products-users-love.mp4
✓ Saved thumbnail: how-to-build-products-users-love.jpg
✓ Size: 342 MB

Saved to: ~/Downloads/

Inspired by: Lenny's workflow from his newsletter

Important Notes

⚠️ Copyright & Fair Use

• Only download videos you have permission to download
• Respect copyright laws and platform terms of service
• Use for personal, educational, or fair use purposes
• Don't redistribute copyrighted content

Tips

• Specify quality if you need lower file size (720p vs 1080p)
• Use audio-only for podcasts or music to save space
• Download to a dedicated folder to stay organized
• Check file size before downloading on slow connections

Common Use Cases

• Education: Save tutorials and courses for offline learning
• Research: Archive videos for reference
• Content Creation: Download your own content from platforms
• Backup: Save important videos before they're removed
• Offline Viewing: Watch videos without internet access

Web Application Testing

To test local web applications, write native Python Playwright scripts.

Helper Scripts Available:

• scripts/with_server.py - Manages server lifecycle (supports multiple servers)

Always run scripts with --help first to see usage. DO NOT read the source until you try running the script first and find that a customized solution is abslutely necessary. These scripts can be very large and thus pollute your context window. They exist to be called directly as black-box scripts rather than ingested into your context window.

Decision Tree: Choosing Your Approach

User task → Is it static HTML?
    ├─ Yes → Read HTML file directly to identify selectors
    │         ├─ Success → Write Playwright script using selectors
    │         └─ Fails/Incomplete → Treat as dynamic (below)
    │
    └─ No (dynamic webapp) → Is the server already running?
        ├─ No → Run: python scripts/with_server.py --help
        │        Then use the helper + write simplified Playwright script
        │
        └─ Yes → Reconnaissance-then-action:
            1. Navigate and wait for networkidle
            2. Take screenshot or inspect DOM
            3. Identify selectors from rendered state
            4. Execute actions with discovered selectors

Example: Using with_server.py

To start a server, run --help first, then use the helper:

Single server:

python scripts/with_server.py --server "npm run dev" --port 5173 -- python your_automation.py

Multiple servers (e.g., backend + frontend):

python scripts/with_server.py \
  --server "cd backend && python server.py" --port 3000 \
  --server "cd frontend && npm run dev" --port 5173 \
  -- python your_automation.py

To create an automation script, include only Playwright logic (servers are managed automatically):

from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch(headless=True) # Always launch chromium in headless mode
    page = browser.new_page()
    page.goto('http://localhost:5173') # Server already running and ready
    page.wait_for_load_state('networkidle') # CRITICAL: Wait for JS to execute
    # ... your automation logic
    browser.close()

Reconnaissance-Then-Action Pattern

1. Inspect rendered DOM:

   page.screenshot(path='/tmp/inspect.png', full_page=True)
   content = page.content()
   page.locator('button').all()
   

2. Identify selectors from inspection results

3. Execute actions using discovered selectors

Common Pitfall

❌ Don't inspect the DOM before waiting for networkidle on dynamic apps ✅ Do wait for page.wait_for_load_state('networkidle') before inspection

Best Practices

• Use bundled scripts as black boxes - To accomplish a task, consider whether one of the scripts available in scripts/ can help. These scripts handle common, complex workflows reliably without cluttering the context window. Use --help to see usage, then invoke directly.
• Use sync_playwright() for synchronous scripts
• Always close the browser when done
• Use descriptive selectors: text=, role=, CSS selectors, or IDs
• Add appropriate waits: page.wait_for_selector() or page.wait_for_timeout()

Reference Files

• examples/ - Examples showing common patterns:
  • element_discovery.py - Discovering buttons, links, and inputs on a page
  • static_html_automation.py - Using file:// URLs for local HTML
  • console_logging.py - Capturing console logs during automation

Insert instructions below