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

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.

Doc Co-Authoring Workflow

This skill provides a structured workflow for guiding users through collaborative document creation. Act as an active guide, walking users through three stages: Context Gathering, Refinement & Structure, and Reader Testing.

When to Offer This Workflow

Trigger conditions:

• User mentions writing documentation: "write a doc", "draft a proposal", "create a spec", "write up"
• User mentions specific doc types: "PRD", "design doc", "decision doc", "RFC"
• User seems to be starting a substantial writing task

Initial offer: Offer the user a structured workflow for co-authoring the document. Explain the three stages:

1. Context Gathering: User provides all relevant context while Claude asks clarifying questions
2. Refinement & Structure: Iteratively build each section through brainstorming and editing
3. Reader Testing: Test the doc with a fresh Claude (no context) to catch blind spots before others read it

Explain that this approach helps ensure the doc works well when others read it (including when they paste it into Claude). Ask if they want to try this workflow or prefer to work freeform.

If user declines, work freeform. If user accepts, proceed to Stage 1.

Stage 1: Context Gathering

Goal: Close the gap between what the user knows and what Claude knows, enabling smart guidance later.

Initial Questions

Start by asking the user for meta-context about the document:

1. What type of document is this? (e.g., technical spec, decision doc, proposal)
2. Who's the primary audience?
3. What's the desired impact when someone reads this?
4. Is there a template or specific format to follow?
5. Any other constraints or context to know?

Inform them they can answer in shorthand or dump information however works best for them.

If user provides a template or mentions a doc type:

• Ask if they have a template document to share
• If they provide a link to a shared document, use the appropriate integration to fetch it
• If they provide a file, read it

If user mentions editing an existing shared document:

• Use the appropriate integration to read the current state
• Check for images without alt-text
• If images exist without alt-text, explain that when others use Claude to understand the doc, Claude won't be able to see them. Ask if they want alt-text generated. If so, request they paste each image into chat for descriptive alt-text generation.

Info Dumping

Once initial questions are answered, encourage the user to dump all the context they have. Request information such as:

• Background on the project/problem
• Related team discussions or shared documents
• Why alternative solutions aren't being used
• Organizational context (team dynamics, past incidents, politics)
• Timeline pressures or constraints
• Technical architecture or dependencies
• Stakeholder concerns

Advise them not to worry about organizing it - just get it all out. Offer multiple ways to provide context:

• Info dump stream-of-consciousness
• Point to team channels or threads to read
• Link to shared documents

If integrations are available (e.g., Slack, Teams, Google Drive, SharePoint, or other MCP servers), mention that these can be used to pull in context directly.

If no integrations are detected and in Claude.ai or Claude app: Suggest they can enable connectors in their Claude settings to allow pulling context from messaging apps and document storage directly.

Inform them clarifying questions will be asked once they've done their initial dump.

During context gathering:

• If user mentions team channels or shared documents:

  • If integrations available: Inform them the content will be read now, then use the appropriate integration
  • If integrations not available: Explain lack of access. Suggest they enable connectors in Claude settings, or paste the relevant content directly.

• If user mentions entities/projects that are unknown:

  • Ask if connected tools should be searched to learn more
  • Wait for user confirmation before searching

• As user provides context, track what's being learned and what's still unclear

Asking clarifying questions:

When user signals they've done their initial dump (or after substantial context provided), ask clarifying questions to ensure understanding:

Generate 5-10 numbered questions based on gaps in the context.

Inform them they can use shorthand to answer (e.g., "1: yes, 2: see #channel, 3: no because backwards compat"), link to more docs, point to channels to read, or just keep info-dumping. Whatever's most efficient for them.

Exit condition: Sufficient context has been gathered when questions show understanding - when edge cases and trade-offs can be asked about without needing basics explained.

Transition: Ask if there's any more context they want to provide at this stage, or if it's time to move on to drafting the document.

If user wants to add more, let them. When ready, proceed to Stage 2.

Stage 2: Refinement & Structure

Goal: Build the document section by section through brainstorming, curation, and iterative refinement.

Instructions to user: Explain that the document will be built section by section. For each section:

1. Clarifying questions will be asked about what to include
2. 5-20 options will be brainstormed
3. User will indicate what to keep/remove/combine
4. The section will be drafted
5. It will be refined through surgical edits

Start with whichever section has the most unknowns (usually the core decision/proposal), then work through the rest.

Section ordering:

If the document structure is clear: Ask which section they'd like to start with.

Suggest starting with whichever section has the most unknowns. For decision docs, that's usually the core proposal. For specs, it's typically the technical approach. Summary sections are best left for last.

If user doesn't know what sections they need: Based on the type of document and template, suggest 3-5 sections appropriate for the doc type.

Ask if this structure works, or if they want to adjust it.

Once structure is agreed:

Create the initial document structure with placeholder text for all sections.

If access to artifacts is available: Use create_file to create an artifact. This gives both Claude and the user a scaffold to work from.

Inform them that the initial structure with placeholders for all sections will be created.

Create artifact with all section headers and brief placeholder text like "[To be written]" or "[Content here]".

Provide the scaffold link and indicate it's time to fill in each section.

If no access to artifacts: Create a markdown file in the working directory. Name it appropriately (e.g., decision-doc.md, technical-spec.md).

Inform them that the initial structure with placeholders for all sections will be created.

Create file with all section headers and placeholder text.

Confirm the filename has been created and indicate it's time to fill in each section.

For each section:

Step 1: Clarifying Questions

Announce work will begin on the [SECTION NAME] section. Ask 5-10 clarifying questions about what should be included:

Generate 5-10 specific questions based on context and section purpose.

Inform them they can answer in shorthand or just indicate what's important to cover.

Step 2: Brainstorming

For the [SECTION NAME] section, brainstorm [5-20] things that might be included, depending on the section's complexity. Look for:

• Context shared that might have been forgotten
• Angles or considerations not yet mentioned

Generate 5-20 numbered options based on section complexity. At the end, offer to brainstorm more if they want additional options.

Step 3: Curation

Ask which points should be kept, removed, or combined. Request brief justifications to help learn priorities for the next sections.

Provide examples:

• "Keep 1,4,7,9"
• "Remove 3 (duplicates 1)"
• "Remove 6 (audience already knows this)"
• "Combine 11 and 12"

If user gives freeform feedback (e.g., "looks good" or "I like most of it but...") instead of numbered selections, extract their preferences and proceed. Parse what they want kept/removed/changed and apply it.

Step 4: Gap Check

Based on what they've selected, ask if there's anything important missing for the [SECTION NAME] section.

Step 5: Drafting

Use str_replace to replace the placeholder text for this section with the actual drafted content.

Announce the [SECTION NAME] section will be drafted now based on what they've selected.

If using artifacts: After drafting, provide a link to the artifact.

Ask them to read through it and indicate what to change. Note that being specific helps learning for the next sections.

If using a file (no artifacts): After drafting, confirm completion.

Inform them the [SECTION NAME] section has been drafted in [filename]. Ask them to read through it and indicate what to change. Note that being specific helps learning for the next sections.

Key instruction for user (include when drafting the first section): Provide a note: Instead of editing the doc directly, ask them to indicate what to change. This helps learning of their style for future sections. For example: "Remove the X bullet - already covered by Y" or "Make the third paragraph more concise".

Step 6: Iterative Refinement

As user provides feedback:

• Use str_replace to make edits (never reprint the whole doc)
• If using artifacts: Provide link to artifact after each edit
• If using files: Just confirm edits are complete
• If user edits doc directly and asks to read it: mentally note the changes they made and keep them in mind for future sections (this shows their preferences)

Continue iterating until user is satisfied with the section.

Quality Checking

After 3 consecutive iterations with no substantial changes, ask if anything can be removed without losing important information.

When section is done, confirm [SECTION NAME] is complete. Ask if ready to move to the next section.

Repeat for all sections.

Near Completion

As approaching completion (80%+ of sections done), announce intention to re-read the entire document and check for:

• Flow and consistency across sections
• Redundancy or contradictions
• Anything that feels like "slop" or generic filler
• Whether every sentence carries weight

Read entire document and provide feedback.

When all sections are drafted and refined: Announce all sections are drafted. Indicate intention to review the complete document one more time.

Review for overall coherence, flow, completeness.

Provide any final suggestions.

Ask if ready to move to Reader Testing, or if they want to refine anything else.

Stage 3: Reader Testing

Goal: Test the document with a fresh Claude (no context bleed) to verify it works for readers.

Instructions to user: Explain that testing will now occur to see if the document actually works for readers. This catches blind spots - things that make sense to the authors but might confuse others.

Testing Approach

If access to sub-agents is available (e.g., in Claude Code):

Perform the testing directly without user involvement.

Step 1: Predict Reader Questions

Announce intention to predict what questions readers might ask when trying to discover this document.

Generate 5-10 questions that readers would realistically ask.

Step 2: Test with Sub-Agent

Announce that these questions will be tested with a fresh Claude instance (no context from this conversation).

For each question, invoke a sub-agent with just the document content and the question.

Summarize what Reader Claude got right/wrong for each question.

Step 3: Run Additional Checks

Announce additional checks will be performed.

Invoke sub-agent to check for ambiguity, false assumptions, contradictions.

Summarize any issues found.

Step 4: Report and Fix

If issues found: Report that Reader Claude struggled with specific issues.

List the specific issues.

Indicate intention to fix these gaps.

Loop back to refinement for problematic sections.

If no access to sub-agents (e.g., claude.ai web interface):

The user will need to do the testing manually.

Step 1: Predict Reader Questions

Ask what questions people might ask when trying to discover this document. What would they type into Claude.ai?

Generate 5-10 questions that readers would realistically ask.

Step 2: Setup Testing

Provide testing instructions:

1. Open a fresh Claude conversation: https://claude.ai
2. Paste or share the document content (if using a shared doc platform with connectors enabled, provide the link)
3. Ask Reader Claude the generated questions

For each question, instruct Reader Claude to provide:

• The answer
• Whether anything was ambiguous or unclear
• What knowledge/context the doc assumes is already known

Check if Reader Claude gives correct answers or misinterprets anything.

Step 3: Additional Checks

Also ask Reader Claude:

• "What in this doc might be ambiguous or unclear to readers?"
• "What knowledge or context does this doc assume readers already have?"
• "Are there any internal contradictions or inconsistencies?"

Step 4: Iterate Based on Results

Ask what Reader Claude got wrong or struggled with. Indicate intention to fix those gaps.

Loop back to refinement for any problematic sections.

Exit Condition (Both Approaches)

When Reader Claude consistently answers questions correctly and doesn't surface new gaps or ambiguities, the doc is ready.

Final Review

When Reader Testing passes: Announce the doc has passed Reader Claude testing. Before completion:

1. Recommend they do a final read-through themselves - they own this document and are responsible for its quality
2. Suggest double-checking any facts, links, or technical details
3. Ask them to verify it achieves the impact they wanted

Ask if they want one more review, or if the work is done.

If user wants final review, provide it. Otherwise: Announce document completion. Provide a few final tips:

• Consider linking this conversation in an appendix so readers can see how the doc was developed
• Use appendices to provide depth without bloating the main doc
• Update the doc as feedback is received from real readers

Tips for Effective Guidance

Tone:

• Be direct and procedural
• Explain rationale briefly when it affects user behavior
• Don't try to "sell" the approach - just execute it

Handling Deviations:

• If user wants to skip a stage: Ask if they want to skip this and write freeform
• If user seems frustrated: Acknowledge this is taking longer than expected. Suggest ways to move faster
• Always give user agency to adjust the process

Context Management:

• Throughout, if context is missing on something mentioned, proactively ask
• Don't let gaps accumulate - address them as they come up

Artifact Management:

• Use create_file for drafting full sections
• Use str_replace for all edits
• Provide artifact link after every change
• Never use artifacts for brainstorming lists - that's just conversation

Quality over Speed:

• Don't rush through stages
• Each iteration should make meaningful improvements
• The goal is a document that actually works for readers

This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices.

The user provides frontend requirements: a component, page, application, or interface to build. They may include context about the purpose, audience, or technical constraints.

Design Thinking

Before coding, understand the context and commit to a BOLD aesthetic direction:

• Purpose: What problem does this interface solve? Who uses it?
• Tone: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction.
• Constraints: Technical requirements (framework, performance, accessibility).
• Differentiation: What makes this UNFORGETTABLE? What's the one thing someone will remember?

CRITICAL: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work - the key is intentionality, not intensity.

Then implement working code (HTML/CSS/JS, React, Vue, etc.) that is:

• Production-grade and functional
• Visually striking and memorable
• Cohesive with a clear aesthetic point-of-view
• Meticulously refined in every detail

Frontend Aesthetics Guidelines

Focus on:

• Typography: Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt instead for distinctive choices that elevate the frontend's aesthetics; unexpected, characterful font choices. Pair a distinctive display font with a refined body font.
• Color & Theme: Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colors with sharp accents outperform timid, evenly-distributed palettes.
• Motion: Use animations for effects and micro-interactions. Prioritize CSS-only solutions for HTML. Use Motion library for React when available. Focus on high-impact moments: one well-orchestrated page load with staggered reveals (animation-delay) creates more delight than scattered micro-interactions. Use scroll-triggering and hover states that surprise.
• Spatial Composition: Unexpected layouts. Asymmetry. Overlap. Diagonal flow. Grid-breaking elements. Generous negative space OR controlled density.
• Backgrounds & Visual Details: Create atmosphere and depth rather than defaulting to solid colors. Add contextual effects and textures that match the overall aesthetic. Apply creative forms like gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, decorative borders, custom cursors, and grain overlays.

NEVER use generic AI-generated aesthetics like overused font families (Inter, Roboto, Arial, system fonts), cliched color schemes (particularly purple gradients on white backgrounds), predictable layouts and component patterns, and cookie-cutter design that lacks context-specific character.

Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices (Space Grotesk, for example) across generations.

IMPORTANT: Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. Elegance comes from executing the vision well.

Remember: Claude is capable of extraordinary creative work. Don't hold back, show what can truly be created when thinking outside the box and committing fully to a distinctive vision.

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

MCP Server Development Guide

Overview

Create MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. The quality of an MCP server is measured by how well it enables LLMs to accomplish real-world tasks.

Process

🚀 High-Level Workflow

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

Phase 1: Deep Research and Planning

1.1 Understand Modern MCP Design

API Coverage vs. Workflow Tools: Balance comprehensive API endpoint coverage with specialized workflow tools. Workflow tools can be more convenient for specific tasks, while comprehensive coverage gives agents flexibility to compose operations. Performance varies by client—some clients benefit from code execution that combines basic tools, while others work better with higher-level workflows. When uncertain, prioritize comprehensive API coverage.

Tool Naming and Discoverability: Clear, descriptive tool names help agents find the right tools quickly. Use consistent prefixes (e.g., github_create_issue, github_list_repos) and action-oriented naming.

Context Management: Agents benefit from concise tool descriptions and the ability to filter/paginate results. Design tools that return focused, relevant data. Some clients support code execution which can help agents filter and process data efficiently.

Actionable Error Messages: Error messages should guide agents toward solutions with specific suggestions and next steps.

1.2 Study MCP Protocol Documentation

Navigate the MCP specification:

Start with the sitemap to find relevant pages: https://modelcontextprotocol.io/sitemap.xml

Then fetch specific pages with .md suffix for markdown format (e.g., https://modelcontextprotocol.io/specification/draft.md).

Key pages to review:

• Specification overview and architecture
• Transport mechanisms (streamable HTTP, stdio)
• Tool, resource, and prompt definitions

1.3 Study Framework Documentation

Recommended stack:

• Language: TypeScript (high-quality SDK support and good compatibility in many execution environments e.g. MCPB. Plus AI models are good at generating TypeScript code, benefiting from its broad usage, static typing and good linting tools)
• Transport: Streamable HTTP for remote servers, using stateless JSON (simpler to scale and maintain, as opposed to stateful sessions and streaming responses). stdio for local servers.

Load framework documentation:

• MCP Best Practices: 📋 View Best Practices - Core guidelines

For TypeScript (recommended):

• TypeScript SDK: Use WebFetch to load https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md
• ⚡ TypeScript Guide - TypeScript patterns and examples

For Python:

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

1.4 Plan Your Implementation

Understand the API: Review the service's API documentation to identify key endpoints, authentication requirements, and data models. Use web search and WebFetch as needed.

Tool Selection: Prioritize comprehensive API coverage. List endpoints to implement, starting with the most common operations.

Phase 2: Implementation

2.1 Set Up Project Structure

See language-specific guides for project setup:

• ⚡ TypeScript Guide - Project structure, package.json, tsconfig.json
• 🐍 Python Guide - Module organization, dependencies

2.2 Implement Core Infrastructure

Create shared utilities:

• API client with authentication
• Error handling helpers
• Response formatting (JSON/Markdown)
• Pagination support

2.3 Implement Tools

For each tool:

Input Schema:

• Use Zod (TypeScript) or Pydantic (Python)
• Include constraints and clear descriptions
• Add examples in field descriptions

Output Schema:

• Define outputSchema where possible for structured data
• Use structuredContent in tool responses (TypeScript SDK feature)
• Helps clients understand and process tool outputs

Tool Description:

• Concise summary of functionality
• Parameter descriptions
• Return type schema

Implementation:

• Async/await for I/O operations
• Proper error handling with actionable messages
• Support pagination where applicable
• Return both text content and structured data when using modern SDKs

Annotations:

• readOnlyHint: true/false
• destructiveHint: true/false
• idempotentHint: true/false
• openWorldHint: true/false

Phase 3: Review and Test

3.1 Code Quality

Review for:

• No duplicated code (DRY principle)
• Consistent error handling
• Full type coverage
• Clear tool descriptions

3.2 Build and Test

TypeScript:

• Run npm run build to verify compilation
• Test with MCP Inspector: npx @modelcontextprotocol/inspector

Python:

• Verify syntax: python -m py_compile your_server.py
• Test with MCP Inspector

See language-specific guides for detailed testing approaches and quality checklists.

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

Use evaluations to 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

Ensure each question is:

• 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: Start with sitemap at https://modelcontextprotocol.io/sitemap.xml, then fetch specific pages with .md suffix
• 📋 MCP Best Practices - Universal MCP guidelines including:
  • Server and tool naming conventions
  • Response format guidelines (JSON vs Markdown)
  • Pagination best practices
  • Transport selection (streamable HTTP vs stdio)
  • 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

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)

Subscripts and Superscripts

IMPORTANT: Never use Unicode subscript/superscript characters (₀₁₂₃₄₅₆₇₈₉, ⁰¹²³⁴⁵⁶⁷⁸⁹) in ReportLab PDFs. The built-in fonts do not include these glyphs, causing them to render as solid black boxes.

Instead, use ReportLab's XML markup tags in Paragraph objects:

from reportlab.platypus import Paragraph
from reportlab.lib.styles import getSampleStyleSheet

styles = getSampleStyleSheet()

# Subscripts: use <sub> tag
chemical = Paragraph("H<sub>2</sub>O", styles['Normal'])

# Superscripts: use <super> tag
squared = Paragraph("x<super>2</super> + y<super>2</super>", styles['Normal'])

For canvas-drawn text (not Paragraph objects), manually adjust font the size and position rather than using Unicode subscripts/superscripts.

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

Skill Creator

A skill for creating new skills and iteratively improving them.

At a high level, the process of creating a skill goes like this:

• Decide what you want the skill to do and roughly how it should do it
• Write a draft of the skill
• Create a few test prompts and run claude-with-access-to-the-skill on them
• Help the user evaluate the results both qualitatively and quantitatively
  • While the runs happen in the background, draft some quantitative evals if there aren't any (if there are some, you can either use as is or modify if you feel something needs to change about them). Then explain them to the user (or if they already existed, explain the ones that already exist)
  • Use the eval-viewer/generate_review.py script to show the user the results for them to look at, and also let them look at the quantitative metrics
• Rewrite the skill based on feedback from the user's evaluation of the results (and also if there are any glaring flaws that become apparent from the quantitative benchmarks)
• Repeat until you're satisfied
• Expand the test set and try again at larger scale

Your job when using this skill is to figure out where the user is in this process and then jump in and help them progress through these stages. So for instance, maybe they're like "I want to make a skill for X". You can help narrow down what they mean, write a draft, write the test cases, figure out how they want to evaluate, run all the prompts, and repeat.

On the other hand, maybe they already have a draft of the skill. In this case you can go straight to the eval/iterate part of the loop.

Of course, you should always be flexible and if the user is like "I don't need to run a bunch of evaluations, just vibe with me", you can do that instead.

Then after the skill is done (but again, the order is flexible), you can also run the skill description improver, which we have a whole separate script for, to optimize the triggering of the skill.

Cool? Cool.

Communicating with the user

The skill creator is liable to be used by people across a wide range of familiarity with coding jargon. If you haven't heard (and how could you, it's only very recently that it started), there's a trend now where the power of Claude is inspiring plumbers to open up their terminals, parents and grandparents to google "how to install npm". On the other hand, the bulk of users are probably fairly computer-literate.

So please pay attention to context cues to understand how to phrase your communication! In the default case, just to give you some idea:

• "evaluation" and "benchmark" are borderline, but OK
• for "JSON" and "assertion" you want to see serious cues from the user that they know what those things are before using them without explaining them

It's OK to briefly explain terms if you're in doubt, and feel free to clarify terms with a short definition if you're unsure if the user will get it.

Creating a skill

Capture Intent

Start by understanding the user's intent. The current conversation might already contain a workflow the user wants to capture (e.g., they say "turn this into a skill"). If so, extract answers from the conversation history first — the tools used, the sequence of steps, corrections the user made, input/output formats observed. The user may need to fill the gaps, and should confirm before proceeding to the next step.

1. What should this skill enable Claude to do?
2. When should this skill trigger? (what user phrases/contexts)
3. What's the expected output format?
4. Should we set up test cases to verify the skill works? Skills with objectively verifiable outputs (file transforms, data extraction, code generation, fixed workflow steps) benefit from test cases. Skills with subjective outputs (writing style, art) often don't need them. Suggest the appropriate default based on the skill type, but let the user decide.

Interview and Research

Proactively ask questions about edge cases, input/output formats, example files, success criteria, and dependencies. Wait to write test prompts until you've got this part ironed out.

Check available MCPs - if useful for research (searching docs, finding similar skills, looking up best practices), research in parallel via subagents if available, otherwise inline. Come prepared with context to reduce burden on the user.

Write the SKILL.md

Based on the user interview, fill in these components:

• name: Skill identifier
• description: When to trigger, what it does. This is the primary triggering mechanism - include both what the skill does AND specific contexts for when to use it. All "when to use" info goes here, not in the body. Note: currently Claude has a tendency to "undertrigger" skills -- to not use them when they'd be useful. To combat this, please make the skill descriptions a little bit "pushy". So for instance, instead of "How to build a simple fast dashboard to display internal Anthropic data.", you might write "How to build a simple fast dashboard to display internal Anthropic data. Make sure to use this skill whenever the user mentions dashboards, data visualization, internal metrics, or wants to display any kind of company data, even if they don't explicitly ask for a 'dashboard.'"
• compatibility: Required tools, dependencies (optional, rarely needed)
• the rest of the skill :)

Skill Writing Guide

Anatomy of a Skill

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter (name, description required)
│   └── Markdown instructions
└── Bundled Resources (optional)
    ├── scripts/    - Executable code for deterministic/repetitive tasks
    ├── references/ - Docs loaded into context as needed
    └── assets/     - Files used in output (templates, icons, fonts)

Progressive Disclosure

Skills use a three-level loading system:

1. Metadata (name + description) - Always in context (~100 words)
2. SKILL.md body - In context whenever skill triggers (<500 lines ideal)
3. Bundled resources - As needed (unlimited, scripts can execute without loading)

These word counts are approximate and you can feel free to go longer if needed.

Key patterns:

• Keep SKILL.md under 500 lines; if you're approaching this limit, add an additional layer of hierarchy along with clear pointers about where the model using the skill should go next to follow up.
• Reference files clearly from SKILL.md with guidance on when to read them
• For large reference files (>300 lines), include a table of contents

Domain organization: When a skill supports multiple domains/frameworks, organize by variant:

cloud-deploy/
├── SKILL.md (workflow + selection)
└── references/
    ├── aws.md
    ├── gcp.md
    └── azure.md

Claude reads only the relevant reference file.

Principle of Lack of Surprise

This goes without saying, but skills must not contain malware, exploit code, or any content that could compromise system security. A skill's contents should not surprise the user in their intent if described. Don't go along with requests to create misleading skills or skills designed to facilitate unauthorized access, data exfiltration, or other malicious activities. Things like a "roleplay as an XYZ" are OK though.

Writing Patterns

Prefer using the imperative form in instructions.

Defining output formats - You can do it like this:

## Report structure
ALWAYS use this exact template:
# [Title]
## Executive summary
## Key findings
## Recommendations

Examples pattern - It's useful to include examples. You can format them like this (but if "Input" and "Output" are in the examples you might want to deviate a little):

## Commit message format
**Example 1:**
Input: Added user authentication with JWT tokens
Output: feat(auth): implement JWT-based authentication

Writing Style

Try to explain to the model why things are important in lieu of heavy-handed musty MUSTs. Use theory of mind and try to make the skill general and not super-narrow to specific examples. Start by writing a draft and then look at it with fresh eyes and improve it.

Test Cases

After writing the skill draft, come up with 2-3 realistic test prompts — the kind of thing a real user would actually say. Share them with the user: [you don't have to use this exact language] "Here are a few test cases I'd like to try. Do these look right, or do you want to add more?" Then run them.

Save test cases to evals/evals.json. Don't write assertions yet — just the prompts. You'll draft assertions in the next step while the runs are in progress.

{
  "skill_name": "example-skill",
  "evals": [
    {
      "id": 1,
      "prompt": "User's task prompt",
      "expected_output": "Description of expected result",
      "files": []
    }
  ]
}

See references/schemas.md for the full schema (including the assertions field, which you'll add later).

Running and evaluating test cases

This section is one continuous sequence — don't stop partway through. Do NOT use /skill-test or any other testing skill.

Put results in <skill-name>-workspace/ as a sibling to the skill directory. Within the workspace, organize results by iteration (iteration-1/, iteration-2/, etc.) and within that, each test case gets a directory (eval-0/, eval-1/, etc.). Don't create all of this upfront — just create directories as you go.

Step 1: Spawn all runs (with-skill AND baseline) in the same turn

For each test case, spawn two subagents in the same turn — one with the skill, one without. This is important: don't spawn the with-skill runs first and then come back for baselines later. Launch everything at once so it all finishes around the same time.

With-skill run:

Execute this task:
- Skill path: <path-to-skill>
- Task: <eval prompt>
- Input files: <eval files if any, or "none">
- Save outputs to: <workspace>/iteration-<N>/eval-<ID>/with_skill/outputs/
- Outputs to save: <what the user cares about — e.g., "the .docx file", "the final CSV">

Baseline run (same prompt, but the baseline depends on context):

• Creating a new skill: no skill at all. Same prompt, no skill path, save to without_skill/outputs/.
• Improving an existing skill: the old version. Before editing, snapshot the skill (cp -r <skill-path> <workspace>/skill-snapshot/), then point the baseline subagent at the snapshot. Save to old_skill/outputs/.

Write an eval_metadata.json for each test case (assertions can be empty for now). Give each eval a descriptive name based on what it's testing — not just "eval-0". Use this name for the directory too. If this iteration uses new or modified eval prompts, create these files for each new eval directory — don't assume they carry over from previous iterations.

{
  "eval_id": 0,
  "eval_name": "descriptive-name-here",
  "prompt": "The user's task prompt",
  "assertions": []
}

Step 2: While runs are in progress, draft assertions

Don't just wait for the runs to finish — you can use this time productively. Draft quantitative assertions for each test case and explain them to the user. If assertions already exist in evals/evals.json, review them and explain what they check.

Good assertions are objectively verifiable and have descriptive names — they should read clearly in the benchmark viewer so someone glancing at the results immediately understands what each one checks. Subjective skills (writing style, design quality) are better evaluated qualitatively — don't force assertions onto things that need human judgment.

Update the eval_metadata.json files and evals/evals.json with the assertions once drafted. Also explain to the user what they'll see in the viewer — both the qualitative outputs and the quantitative benchmark.

Step 3: As runs complete, capture timing data

When each subagent task completes, you receive a notification containing total_tokens and duration_ms. Save this data immediately to timing.json in the run directory:

{
  "total_tokens": 84852,
  "duration_ms": 23332,
  "total_duration_seconds": 23.3
}

This is the only opportunity to capture this data — it comes through the task notification and isn't persisted elsewhere. Process each notification as it arrives rather than trying to batch them.

Step 4: Grade, aggregate, and launch the viewer

Once all runs are done:

1. Grade each run — spawn a grader subagent (or grade inline) that reads agents/grader.md and evaluates each assertion against the outputs. Save results to grading.json in each run directory. The grading.json expectations array must use the fields text, passed, and evidence (not name/met/details or other variants) — the viewer depends on these exact field names. For assertions that can be checked programmatically, write and run a script rather than eyeballing it — scripts are faster, more reliable, and can be reused across iterations.

2. Aggregate into benchmark — run the aggregation script from the skill-creator directory:

   python -m scripts.aggregate_benchmark <workspace>/iteration-N --skill-name <name>
   

   This produces benchmark.json and benchmark.md with pass_rate, time, and tokens for each configuration, with mean ± stddev and the delta. If generating benchmark.json manually, see references/schemas.md for the exact schema the viewer expects. Put each with_skill version before its baseline counterpart.

3. Do an analyst pass — read the benchmark data and surface patterns the aggregate stats might hide. See agents/analyzer.md (the "Analyzing Benchmark Results" section) for what to look for — things like assertions that always pass regardless of skill (non-discriminating), high-variance evals (possibly flaky), and time/token tradeoffs.

4. Launch the viewer with both qualitative outputs and quantitative data:

   nohup python <skill-creator-path>/eval-viewer/generate_review.py \
     <workspace>/iteration-N \
     --skill-name "my-skill" \
     --benchmark <workspace>/iteration-N/benchmark.json \
     > /dev/null 2>&1 &
   VIEWER_PID=$!
   

   For iteration 2+, also pass --previous-workspace <workspace>/iteration-<N-1>.

   Cowork / headless environments: If webbrowser.open() is not available or the environment has no display, use --static <output_path> to write a standalone HTML file instead of starting a server. Feedback will be downloaded as a feedback.json file when the user clicks "Submit All Reviews". After download, copy feedback.json into the workspace directory for the next iteration to pick up.

Note: please use generate_review.py to create the viewer; there's no need to write custom HTML.

5. Tell the user something like: "I've opened the results in your browser. There are two tabs — 'Outputs' lets you click through each test case and leave feedback, 'Benchmark' shows the quantitative comparison. When you're done, come back here and let me know."

What the user sees in the viewer

The "Outputs" tab shows one test case at a time:

• Prompt: the task that was given
• Output: the files the skill produced, rendered inline where possible
• Previous Output (iteration 2+): collapsed section showing last iteration's output
• Formal Grades (if grading was run): collapsed section showing assertion pass/fail
• Feedback: a textbox that auto-saves as they type
• Previous Feedback (iteration 2+): their comments from last time, shown below the textbox

The "Benchmark" tab shows the stats summary: pass rates, timing, and token usage for each configuration, with per-eval breakdowns and analyst observations.

Navigation is via prev/next buttons or arrow keys. When done, they click "Submit All Reviews" which saves all feedback to feedback.json.

Step 5: Read the feedback

When the user tells you they're done, read feedback.json:

{
  "reviews": [
    {"run_id": "eval-0-with_skill", "feedback": "the chart is missing axis labels", "timestamp": "..."},
    {"run_id": "eval-1-with_skill", "feedback": "", "timestamp": "..."},
    {"run_id": "eval-2-with_skill", "feedback": "perfect, love this", "timestamp": "..."}
  ],
  "status": "complete"
}

Empty feedback means the user thought it was fine. Focus your improvements on the test cases where the user had specific complaints.

Kill the viewer server when you're done with it:

kill $VIEWER_PID 2>/dev/null

Improving the skill

This is the heart of the loop. You've run the test cases, the user has reviewed the results, and now you need to make the skill better based on their feedback.

How to think about improvements

1. Generalize from the feedback. The big picture thing that's happening here is that we're trying to create skills that can be used a million times (maybe literally, maybe even more who knows) across many different prompts. Here you and the user are iterating on only a few examples over and over again because it helps move faster. The user knows these examples in and out and it's quick for them to assess new outputs. But if the skill you and the user are codeveloping works only for those examples, it's useless. Rather than put in fiddly overfitty changes, or oppressively constrictive MUSTs, if there's some stubborn issue, you might try branching out and using different metaphors, or recommending different patterns of working. It's relatively cheap to try and maybe you'll land on something great.

2. Keep the prompt lean. Remove things that aren't pulling their weight. Make sure to read the transcripts, not just the final outputs — if it looks like the skill is making the model waste a bunch of time doing things that are unproductive, you can try getting rid of the parts of the skill that are making it do that and seeing what happens.

3. Explain the why. Try hard to explain the why behind everything you're asking the model to do. Today's LLMs are smart. They have good theory of mind and when given a good harness can go beyond rote instructions and really make things happen. Even if the feedback from the user is terse or frustrated, try to actually understand the task and why the user is writing what they wrote, and what they actually wrote, and then transmit this understanding into the instructions. If you find yourself writing ALWAYS or NEVER in all caps, or using super rigid structures, that's a yellow flag — if possible, reframe and explain the reasoning so that the model understands why the thing you're asking for is important. That's a more humane, powerful, and effective approach.

4. Look for repeated work across test cases. Read the transcripts from the test runs and notice if the subagents all independently wrote similar helper scripts or took the same multi-step approach to something. If all 3 test cases resulted in the subagent writing a create_docx.py or a build_chart.py, that's a strong signal the skill should bundle that script. Write it once, put it in scripts/, and tell the skill to use it. This saves every future invocation from reinventing the wheel.

This task is pretty important (we are trying to create billions a year in economic value here!) and your thinking time is not the blocker; take your time and really mull things over. I'd suggest writing a draft revision and then looking at it anew and making improvements. Really do your best to get into the head of the user and understand what they want and need.

The iteration loop

After improving the skill:

1. Apply your improvements to the skill
2. Rerun all test cases into a new iteration-<N+1>/ directory, including baseline runs. If you're creating a new skill, the baseline is always without_skill (no skill) — that stays the same across iterations. If you're improving an existing skill, use your judgment on what makes sense as the baseline: the original version the user came in with, or the previous iteration.
3. Launch the reviewer with --previous-workspace pointing at the previous iteration
4. Wait for the user to review and tell you they're done
5. Read the new feedback, improve again, repeat

Keep going until:

• The user says they're happy
• The feedback is all empty (everything looks good)
• You're not making meaningful progress

Advanced: Blind comparison

For situations where you want a more rigorous comparison between two versions of a skill (e.g., the user asks "is the new version actually better?"), there's a blind comparison system. Read agents/comparator.md and agents/analyzer.md for the details. The basic idea is: give two outputs to an independent agent without telling it which is which, and let it judge quality. Then analyze why the winner won.

This is optional, requires subagents, and most users won't need it. The human review loop is usually sufficient.

Description Optimization

The description field in SKILL.md frontmatter is the primary mechanism that determines whether Claude invokes a skill. After creating or improving a skill, offer to optimize the description for better triggering accuracy.

Step 1: Generate trigger eval queries

Create 20 eval queries — a mix of should-trigger and should-not-trigger. Save as JSON:

[
  {"query": "the user prompt", "should_trigger": true},
  {"query": "another prompt", "should_trigger": false}
]

The queries must be realistic and something a Claude Code or Claude.ai user would actually type. Not abstract requests, but requests that are concrete and specific and have a good amount of detail. For instance, file paths, personal context about the user's job or situation, column names and values, company names, URLs. A little bit of backstory. Some might be in lowercase or contain abbreviations or typos or casual speech. Use a mix of different lengths, and focus on edge cases rather than making them clear-cut (the user will get a chance to sign off on them).

Bad: "Format this data", "Extract text from PDF", "Create a chart"

Good: "ok so my boss just sent me this xlsx file (its in my downloads, called something like 'Q4 sales final FINAL v2.xlsx') and she wants me to add a column that shows the profit margin as a percentage. The revenue is in column C and costs are in column D i think"

For the should-trigger queries (8-10), think about coverage. You want different phrasings of the same intent — some formal, some casual. Include cases where the user doesn't explicitly name the skill or file type but clearly needs it. Throw in some uncommon use cases and cases where this skill competes with another but should win.

For the should-not-trigger queries (8-10), the most valuable ones are the near-misses — queries that share keywords or concepts with the skill but actually need something different. Think adjacent domains, ambiguous phrasing where a naive keyword match would trigger but shouldn't, and cases where the query touches on something the skill does but in a context where another tool is more appropriate.

The key thing to avoid: don't make should-not-trigger queries obviously irrelevant. "Write a fibonacci function" as a negative test for a PDF skill is too easy — it doesn't test anything. The negative cases should be genuinely tricky.

Step 2: Review with user

Present the eval set to the user for review using the HTML template:

1. Read the template from assets/eval_review.html
2. Replace the placeholders:
   • __EVAL_DATA_PLACEHOLDER__ → the JSON array of eval items (no quotes around it — it's a JS variable assignment)
   • __SKILL_NAME_PLACEHOLDER__ → the skill's name
   • __SKILL_DESCRIPTION_PLACEHOLDER__ → the skill's current description
3. Write to a temp file (e.g., /tmp/eval_review_<skill-name>.html) and open it: open /tmp/eval_review_<skill-name>.html
4. The user can edit queries, toggle should-trigger, add/remove entries, then click "Export Eval Set"
5. The file downloads to ~/Downloads/eval_set.json — check the Downloads folder for the most recent version in case there are multiple (e.g., eval_set (1).json)

This step matters — bad eval queries lead to bad descriptions.

Step 3: Run the optimization loop

Tell the user: "This will take some time — I'll run the optimization loop in the background and check on it periodically."

Save the eval set to the workspace, then run in the background:

python -m scripts.run_loop \
  --eval-set <path-to-trigger-eval.json> \
  --skill-path <path-to-skill> \
  --model <model-id-powering-this-session> \
  --max-iterations 5 \
  --verbose

Use the model ID from your system prompt (the one powering the current session) so the triggering test matches what the user actually experiences.

While it runs, periodically tail the output to give the user updates on which iteration it's on and what the scores look like.

This handles the full optimization loop automatically. It splits the eval set into 60% train and 40% held-out test, evaluates the current description (running each query 3 times to get a reliable trigger rate), then calls Claude to propose improvements based on what failed. It re-evaluates each new description on both train and test, iterating up to 5 times. When it's done, it opens an HTML report in the browser showing the results per iteration and returns JSON with best_description — selected by test score rather than train score to avoid overfitting.

How skill triggering works

Understanding the triggering mechanism helps design better eval queries. Skills appear in Claude's available_skills list with their name + description, and Claude decides whether to consult a skill based on that description. The important thing to know is that Claude only consults skills for tasks it can't easily handle on its own — simple, one-step queries like "read this PDF" may not trigger a skill even if the description matches perfectly, because Claude can handle them directly with basic tools. Complex, multi-step, or specialized queries reliably trigger skills when the description matches.

This means your eval queries should be substantive enough that Claude would actually benefit from consulting a skill. Simple queries like "read file X" are poor test cases — they won't trigger skills regardless of description quality.

Step 4: Apply the result

Take best_description from the JSON output and update the skill's SKILL.md frontmatter. Show the user before/after and report the scores.

Package and Present (only if present_files tool is available)

Check whether you have access to the present_files tool. If you don't, skip this step. If you do, package the skill and present the .skill file to the user:

python -m scripts.package_skill <path/to/skill-folder>

After packaging, direct the user to the resulting .skill file path so they can install it.

Claude.ai-specific instructions

In Claude.ai, the core workflow is the same (draft → test → review → improve → repeat), but because Claude.ai doesn't have subagents, some mechanics change. Here's what to adapt:

Running test cases: No subagents means no parallel execution. For each test case, read the skill's SKILL.md, then follow its instructions to accomplish the test prompt yourself. Do them one at a time. This is less rigorous than independent subagents (you wrote the skill and you're also running it, so you have full context), but it's a useful sanity check — and the human review step compensates. Skip the baseline runs — just use the skill to complete the task as requested.

Reviewing results: If you can't open a browser (e.g., Claude.ai's VM has no display, or you're on a remote server), skip the browser reviewer entirely. Instead, present results directly in the conversation. For each test case, show the prompt and the output. If the output is a file the user needs to see (like a .docx or .xlsx), save it to the filesystem and tell them where it is so they can download and inspect it. Ask for feedback inline: "How does this look? Anything you'd change?"

Benchmarking: Skip the quantitative benchmarking — it relies on baseline comparisons which aren't meaningful without subagents. Focus on qualitative feedback from the user.

The iteration loop: Same as before — improve the skill, rerun the test cases, ask for feedback — just without the browser reviewer in the middle. You can still organize results into iteration directories on the filesystem if you have one.

Description optimization: This section requires the claude CLI tool (specifically claude -p) which is only available in Claude Code. Skip it if you're on Claude.ai.

Blind comparison: Requires subagents. Skip it.

Packaging: The package_skill.py script works anywhere with Python and a filesystem. On Claude.ai, you can run it and the user can download the resulting .skill file.

Updating an existing skill: The user might be asking you to update an existing skill, not create a new one. In this case:

• Preserve the original name. Note the skill's directory name and name frontmatter field -- use them unchanged. E.g., if the installed skill is research-helper, output research-helper.skill (not research-helper-v2).
• Copy to a writeable location before editing. The installed skill path may be read-only. Copy to /tmp/skill-name/, edit there, and package from the copy.
• If packaging manually, stage in /tmp/ first, then copy to the output directory -- direct writes may fail due to permissions.

Cowork-Specific Instructions

If you're in Cowork, the main things to know are:

• You have subagents, so the main workflow (spawn test cases in parallel, run baselines, grade, etc.) all works. (However, if you run into severe problems with timeouts, it's OK to run the test prompts in series rather than parallel.)
• You don't have a browser or display, so when generating the eval viewer, use --static <output_path> to write a standalone HTML file instead of starting a server. Then proffer a link that the user can click to open the HTML in their browser.
• For whatever reason, the Cowork setup seems to disincline Claude from generating the eval viewer after running the tests, so just to reiterate: whether you're in Cowork or in Claude Code, after running tests, you should always generate the eval viewer for the human to look at examples before revising the skill yourself and trying to make corrections, using generate_review.py (not writing your own boutique html code). Sorry in advance but I'm gonna go all caps here: GENERATE THE EVAL VIEWER BEFORE evaluating inputs yourself. You want to get them in front of the human ASAP!
• Feedback works differently: since there's no running server, the viewer's "Submit All Reviews" button will download feedback.json as a file. You can then read it from there (you may have to request access first).
• Packaging works — package_skill.py just needs Python and a filesystem.
• Description optimization (run_loop.py / run_eval.py) should work in Cowork just fine since it uses claude -p via subprocess, not a browser, but please save it until you've fully finished making the skill and the user agrees it's in good shape.
• Updating an existing skill: The user might be asking you to update an existing skill, not create a new one. Follow the update guidance in the claude.ai section above.

Reference files

The agents/ directory contains instructions for specialized subagents. Read them when you need to spawn the relevant subagent.

• agents/grader.md — How to evaluate assertions against outputs
• agents/comparator.md — How to do blind A/B comparison between two outputs
• agents/analyzer.md — How to analyze why one version beat another

The references/ directory has additional documentation:

• references/schemas.md — JSON structures for evals.json, grading.json, etc.

Repeating one more time the core loop here for emphasis:

• Figure out what the skill is about
• Draft or edit the skill
• Run claude-with-access-to-the-skill on test prompts
• With the user, evaluate the outputs:
  • Create benchmark.json and run eval-viewer/generate_review.py to help the user review them
  • Run quantitative evals
• Repeat until you and the user are satisfied
• Package the final skill and return it to the user.

Please add steps to your TodoList, if you have such a thing, to make sure you don't forget. If you're in Cowork, please specifically put "Create evals JSON and run eval-viewer/generate_review.py so human can review test cases" in your TodoList to make sure it happens.

Good luck!

Slack GIF Creator

A toolkit providing utilities and knowledge for creating animated GIFs optimized for Slack.

Slack Requirements

Dimensions:

• Emoji GIFs: 128x128 (recommended)
• Message GIFs: 480x480

Parameters:

• FPS: 10-30 (lower is smaller file size)
• Colors: 48-128 (fewer = smaller file size)
• Duration: Keep under 3 seconds for emoji GIFs

Core Workflow

from core.gif_builder import GIFBuilder
from PIL import Image, ImageDraw

# 1. Create builder
builder = GIFBuilder(width=128, height=128, fps=10)

# 2. Generate frames
for i in range(12):
    frame = Image.new('RGB', (128, 128), (240, 248, 255))
    draw = ImageDraw.Draw(frame)

    # Draw your animation using PIL primitives
    # (circles, polygons, lines, etc.)

    builder.add_frame(frame)

# 3. Save with optimization
builder.save('output.gif', num_colors=48, optimize_for_emoji=True)

Drawing Graphics

Working with User-Uploaded Images

If a user uploads an image, consider whether they want to:

• Use it directly (e.g., "animate this", "split this into frames")
• Use it as inspiration (e.g., "make something like this")

Load and work with images using PIL:

from PIL import Image

uploaded = Image.open('file.png')
# Use directly, or just as reference for colors/style

Drawing from Scratch

When drawing graphics from scratch, use PIL ImageDraw primitives:

from PIL import ImageDraw

draw = ImageDraw.Draw(frame)

# Circles/ovals
draw.ellipse([x1, y1, x2, y2], fill=(r, g, b), outline=(r, g, b), width=3)

# Stars, triangles, any polygon
points = [(x1, y1), (x2, y2), (x3, y3), ...]
draw.polygon(points, fill=(r, g, b), outline=(r, g, b), width=3)

# Lines
draw.line([(x1, y1), (x2, y2)], fill=(r, g, b), width=5)

# Rectangles
draw.rectangle([x1, y1, x2, y2], fill=(r, g, b), outline=(r, g, b), width=3)

Don't use: Emoji fonts (unreliable across platforms) or assume pre-packaged graphics exist in this skill.

Making Graphics Look Good

Graphics should look polished and creative, not basic. Here's how:

Use thicker lines - Always set width=2 or higher for outlines and lines. Thin lines (width=1) look choppy and amateurish.

Add visual depth:

• Use gradients for backgrounds (create_gradient_background)
• Layer multiple shapes for complexity (e.g., a star with a smaller star inside)

Make shapes more interesting:

• Don't just draw a plain circle - add highlights, rings, or patterns
• Stars can have glows (draw larger, semi-transparent versions behind)
• Combine multiple shapes (stars + sparkles, circles + rings)

Pay attention to colors:

• Use vibrant, complementary colors
• Add contrast (dark outlines on light shapes, light outlines on dark shapes)
• Consider the overall composition

For complex shapes (hearts, snowflakes, etc.):

• Use combinations of polygons and ellipses
• Calculate points carefully for symmetry
• Add details (a heart can have a highlight curve, snowflakes have intricate branches)

Be creative and detailed! A good Slack GIF should look polished, not like placeholder graphics.

Available Utilities

GIFBuilder (core.gif_builder)

Assembles frames and optimizes for Slack:

builder = GIFBuilder(width=128, height=128, fps=10)
builder.add_frame(frame)  # Add PIL Image
builder.add_frames(frames)  # Add list of frames
builder.save('out.gif', num_colors=48, optimize_for_emoji=True, remove_duplicates=True)

Validators (core.validators)

Check if GIF meets Slack requirements:

from core.validators import validate_gif, is_slack_ready

# Detailed validation
passes, info = validate_gif('my.gif', is_emoji=True, verbose=True)

# Quick check
if is_slack_ready('my.gif'):
    print("Ready!")

Easing Functions (core.easing)

Smooth motion instead of linear:

from core.easing import interpolate

# Progress from 0.0 to 1.0
t = i / (num_frames - 1)

# Apply easing
y = interpolate(start=0, end=400, t=t, easing='ease_out')

# Available: linear, ease_in, ease_out, ease_in_out,
#           bounce_out, elastic_out, back_out

Frame Helpers (core.frame_composer)

Convenience functions for common needs:

from core.frame_composer import (
    create_blank_frame,         # Solid color background
    create_gradient_background,  # Vertical gradient
    draw_circle,                # Helper for circles
    draw_text,                  # Simple text rendering
    draw_star                   # 5-pointed star
)

Animation Concepts

Shake/Vibrate

Offset object position with oscillation:

• Use math.sin() or math.cos() with frame index
• Add small random variations for natural feel
• Apply to x and/or y position

Pulse/Heartbeat

Scale object size rhythmically:

• Use math.sin(t * frequency * 2 * math.pi) for smooth pulse
• For heartbeat: two quick pulses then pause (adjust sine wave)
• Scale between 0.8 and 1.2 of base size

Bounce

Object falls and bounces:

• Use interpolate() with easing='bounce_out' for landing
• Use easing='ease_in' for falling (accelerating)
• Apply gravity by increasing y velocity each frame

Spin/Rotate

Rotate object around center:

• PIL: image.rotate(angle, resample=Image.BICUBIC)
• For wobble: use sine wave for angle instead of linear

Fade In/Out

Gradually appear or disappear:

• Create RGBA image, adjust alpha channel
• Or use Image.blend(image1, image2, alpha)
• Fade in: alpha from 0 to 1
• Fade out: alpha from 1 to 0

Slide

Move object from off-screen to position:

• Start position: outside frame bounds
• End position: target location
• Use interpolate() with easing='ease_out' for smooth stop
• For overshoot: use easing='back_out'

Zoom

Scale and position for zoom effect:

• Zoom in: scale from 0.1 to 2.0, crop center
• Zoom out: scale from 2.0 to 1.0
• Can add motion blur for drama (PIL filter)

Explode/Particle Burst

Create particles radiating outward:

• Generate particles with random angles and velocities
• Update each particle: x += vx, y += vy
• Add gravity: vy += gravity_constant
• Fade out particles over time (reduce alpha)

Optimization Strategies

Only when asked to make the file size smaller, implement a few of the following methods:

1. Fewer frames - Lower FPS (10 instead of 20) or shorter duration
2. Fewer colors - num_colors=48 instead of 128
3. Smaller dimensions - 128x128 instead of 480x480
4. Remove duplicates - remove_duplicates=True in save()
5. Emoji mode - optimize_for_emoji=True auto-optimizes

# Maximum optimization for emoji
builder.save(
    'emoji.gif',
    num_colors=48,
    optimize_for_emoji=True,
    remove_duplicates=True
)

Philosophy

This skill provides:

• Knowledge: Slack's requirements and animation concepts
• Utilities: GIFBuilder, validators, easing functions
• Flexibility: Create the animation logic using PIL primitives

It does NOT provide:

• Rigid animation templates or pre-made functions
• Emoji font rendering (unreliable across platforms)
• A library of pre-packaged graphics built into the skill

Note on user uploads: This skill doesn't include pre-built graphics, but if a user uploads an image, use PIL to load and work with it - interpret based on their request whether they want it used directly or just as inspiration.

Be creative! Combine concepts (bouncing + rotating, pulsing + sliding, etc.) and use PIL's full capabilities.

Dependencies

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.

Web 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

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

Browser Automation with browser-use CLI

The browser-use command provides fast, persistent browser automation. A background daemon keeps the browser open across commands, giving ~50ms latency per call.

Prerequisites

browser-use doctor    # Verify installation

For setup details, see https://github.com/browser-use/browser-use/blob/main/browser_use/skill_cli/README.md

Core Workflow

1. Navigate: browser-use open <url> — launches headless browser and opens page
2. Inspect: browser-use state — returns clickable elements with indices
3. Interact: use indices from state (browser-use click 5, browser-use input 3 "text")
4. Verify: browser-use state or browser-use screenshot to confirm
5. Repeat: browser stays open between commands

If a command fails, run browser-use close first to clear any broken session, then retry.

To use the user's existing Chrome (preserves logins/cookies): run browser-use connect first. To use a cloud browser instead: run browser-use cloud connect first. After either, commands work the same way.

If browser-use connect fails

When browser-use connect cannot find a running Chrome with remote debugging, prompt the user with two options:

1. Use their real Chrome browser — they need to enable remote debugging first:
   • Open chrome://inspect/#remote-debugging in Chrome, or relaunch Chrome with --remote-debugging-port=9222
   • Then retry browser-use connect
2. Use managed Chromium with their Chrome profile — no Chrome setup needed:
   • Run browser-use profile list to show available profiles
   • Ask which profile they want, then use browser-use --profile "ProfileName" open <url>
   • This launches a separate Chromium instance with their profile data (cookies, logins, extensions)

Let the user choose — don't assume one path over the other.

Browser Modes

browser-use open <url>                         # Default: headless Chromium (no setup needed)
browser-use --headed open <url>                # Visible window (for debugging)
browser-use connect                            # Connect to user's Chrome (preserves logins/cookies)
browser-use cloud connect                      # Cloud browser (zero-config, requires API key)
browser-use --profile "Default" open <url>     # Real Chrome with specific profile

After connect or cloud connect, all subsequent commands go to that browser — no extra flags needed.

Commands

# Navigation
browser-use open <url>                    # Navigate to URL
browser-use back                          # Go back in history
browser-use scroll down                   # Scroll down (--amount N for pixels)
browser-use scroll up                     # Scroll up
browser-use tab list                      # List all tabs
browser-use tab new [url]                 # Open a new tab (blank or with URL)
browser-use tab switch <index>            # Switch to tab by index
browser-use tab close <index> [index...]  # Close one or more tabs

# Page State — always run state first to get element indices
browser-use state                         # URL, title, clickable elements with indices
browser-use screenshot [path.png]         # Screenshot (base64 if no path, --full for full page)

# Interactions — use indices from state
browser-use click <index>                 # Click element by index
browser-use click <x> <y>                 # Click at pixel coordinates
browser-use type "text"                   # Type into focused element
browser-use input <index> "text"          # Click element, clear existing text, then type
browser-use input <index> ""              # Clear a field without typing new text
browser-use keys "Enter"                  # Send keyboard keys (also "Control+a", etc.)
browser-use select <index> "option"       # Select dropdown option
browser-use upload <index> <path>         # Upload file to file input
browser-use hover <index>                 # Hover over element
browser-use dblclick <index>              # Double-click element
browser-use rightclick <index>            # Right-click element

# Data Extraction
browser-use eval "js code"                # Execute JavaScript, return result
browser-use get title                     # Page title
browser-use get html [--selector "h1"]    # Page HTML (or scoped to selector)
browser-use get text <index>              # Element text content
browser-use get value <index>             # Input/textarea value
browser-use get attributes <index>        # Element attributes
browser-use get bbox <index>              # Bounding box (x, y, width, height)

# Wait
browser-use wait selector "css"           # Wait for element (--state visible|hidden|attached|detached, --timeout ms)
browser-use wait text "text"              # Wait for text to appear

# Cookies
browser-use cookies get [--url <url>]     # Get cookies (optionally filtered)
browser-use cookies set <name> <value>    # Set cookie (--domain, --secure, --http-only, --same-site, --expires)
browser-use cookies clear [--url <url>]   # Clear cookies
browser-use cookies export <file>         # Export to JSON
browser-use cookies import <file>         # Import from JSON

# Session
browser-use close                         # Close browser and stop daemon
browser-use sessions                      # List active sessions
browser-use close --all                   # Close all sessions

For advanced browser control (CDP, device emulation, tab activation), see references/cdp-python.md.

Cloud API

browser-use cloud connect                 # Provision cloud browser and connect (zero-config)
browser-use cloud login <api-key>         # Save API key (or set BROWSER_USE_API_KEY)
browser-use cloud logout                  # Remove API key
browser-use cloud v2 GET /browsers        # REST passthrough (v2 or v3)
browser-use cloud v2 POST /tasks '{"task":"...","url":"..."}'
browser-use cloud v2 poll <task-id>       # Poll task until done
browser-use cloud v2 --help               # Show API endpoints

cloud connect provisions a cloud browser with a persistent profile (auto-created on first use), connects via CDP, and prints a live URL. browser-use close disconnects AND stops the cloud browser. For custom browser settings (proxy, timeout, specific profile), use cloud v2 POST /browsers directly with the desired parameters.

Agent Self-Registration

Only use this if you don't already have an API key (check browser-use doctor to see if api_key is set). If already logged in, skip this entirely.

1. browser-use cloud signup — get a challenge
2. Solve the challenge
3. browser-use cloud signup --verify <challenge-id> <answer> — verify and save API key
4. browser-use cloud signup --claim — generate URL for a human to claim the account

Tunnels

browser-use tunnel <port>                 # Start Cloudflare tunnel (idempotent)
browser-use tunnel list                   # Show active tunnels
browser-use tunnel stop <port>            # Stop tunnel
browser-use tunnel stop --all             # Stop all tunnels

Profile Management

browser-use profile list                  # List detected browsers and profiles
browser-use profile sync --all            # Sync profiles to cloud
browser-use profile update                # Download/update profile-use binary

Command Chaining

Commands can be chained with &&. The browser persists via the daemon, so chaining is safe and efficient.

browser-use open https://example.com && browser-use state
browser-use input 5 "user@example.com" && browser-use input 6 "password" && browser-use click 7

Chain when you don't need intermediate output. Run separately when you need to parse state to discover indices first.

Common Workflows

Authenticated Browsing

When a task requires an authenticated site (Gmail, GitHub, internal tools), use Chrome profiles:

browser-use profile list                           # Check available profiles
# Ask the user which profile to use, then:
browser-use --profile "Default" open https://github.com  # Already logged in

Exposing Local Dev Servers

browser-use tunnel 3000                            # → https://abc.trycloudflare.com
browser-use open https://abc.trycloudflare.com     # Browse the tunnel

Multiple Browsers

For subagent workflows or running multiple browsers in parallel, use --session NAME. Each session gets its own browser. See references/multi-session.md.

Configuration

browser-use config list                            # Show all config values
browser-use config set cloud_connect_proxy jp      # Set a value
browser-use config get cloud_connect_proxy         # Get a value
browser-use config unset cloud_connect_timeout     # Remove a value
browser-use doctor                                 # Shows config + diagnostics
browser-use setup                                  # Interactive post-install setup

Config stored in ~/.browser-use/config.json.

Global Options

Tips

1. Always run state first to see available elements and their indices
2. Use --headed for debugging to see what the browser is doing
3. Sessions persist — browser stays open between commands
4. CLI aliases: bu, browser, and browseruse all work
5. If commands fail, run browser-use close first, then retry

Troubleshooting

• Browser won't start? browser-use close then browser-use --headed open <url>
• Element not found? browser-use scroll down then browser-use state
• Run diagnostics: browser-use doctor

Cleanup

browser-use close                         # Close browser session
browser-use tunnel stop --all             # Stop tunnels (if any)

Browser Automation for Sandboxed Agents

This skill is for agents running on sandboxed remote machines (cloud VMs, CI, coding agents) that need to control a headless browser.

Prerequisites

browser-use doctor    # Verify installation

For setup details, see https://github.com/browser-use/browser-use/blob/main/browser_use/skill_cli/README.md

Core Workflow

1. Navigate: browser-use open <url> — starts headless browser if needed
2. Inspect: browser-use state — returns clickable elements with indices
3. Interact: use indices from state (browser-use click 5, browser-use input 3 "text")
4. Verify: browser-use state or browser-use screenshot to confirm
5. Repeat: browser stays open between commands
6. Cleanup: browser-use close when done

Browser Modes

browser-use open <url>                                    # Default: headless Chromium
browser-use cloud connect                                 # Provision cloud browser and connect
browser-use --connect open <url>                          # Auto-discover running Chrome via CDP
browser-use --cdp-url ws://localhost:9222/... open <url>  # Connect via CDP URL

Commands

# Navigation
browser-use open <url>                    # Navigate to URL
browser-use back                          # Go back in history
browser-use scroll down                   # Scroll down (--amount N for pixels)
browser-use scroll up                     # Scroll up
browser-use tab list                      # List all tabs with lock status
browser-use tab new [url]                 # Open a new tab (blank or with URL)
browser-use tab switch <index>            # Switch to tab by index
browser-use tab close <index> [index...]  # Close one or more tabs

# Page State — always run state first to get element indices
browser-use state                         # URL, title, clickable elements with indices
browser-use screenshot [path.png]         # Screenshot (base64 if no path, --full for full page)

# Interactions — use indices from state
browser-use click <index>                 # Click element by index
browser-use click <x> <y>                 # Click at pixel coordinates
browser-use type "text"                   # Type into focused element
browser-use input <index> "text"          # Click element, then type
browser-use keys "Enter"                  # Send keyboard keys (also "Control+a", etc.)
browser-use select <index> "option"       # Select dropdown option
browser-use upload <index> <path>         # Upload file to file input
browser-use hover <index>                 # Hover over element
browser-use dblclick <index>              # Double-click element
browser-use rightclick <index>            # Right-click element

# Data Extraction
browser-use eval "js code"                # Execute JavaScript, return result
browser-use get title                     # Page title
browser-use get html [--selector "h1"]    # Page HTML (or scoped to selector)
browser-use get text <index>              # Element text content
browser-use get value <index>             # Input/textarea value
browser-use get attributes <index>        # Element attributes
browser-use get bbox <index>              # Bounding box (x, y, width, height)

# Wait
browser-use wait selector "css"           # Wait for element (--state visible|hidden|attached|detached, --timeout ms)
browser-use wait text "text"              # Wait for text to appear

# Cookies
browser-use cookies get [--url <url>]     # Get cookies (optionally filtered)
browser-use cookies set <name> <value>    # Set cookie (--domain, --secure, --http-only, --same-site, --expires)
browser-use cookies clear [--url <url>]   # Clear cookies
browser-use cookies export <file>         # Export to JSON
browser-use cookies import <file>         # Import from JSON

# Python — persistent session with browser access
browser-use python "code"                 # Execute Python (variables persist across calls)
browser-use python --file script.py       # Run file
browser-use python --vars                 # Show defined variables
browser-use python --reset                # Clear namespace

# Session
browser-use close                         # Close browser and stop daemon
browser-use sessions                      # List active sessions
browser-use close --all                   # Close all sessions

The Python browser object provides: browser.url, browser.title, browser.html, browser.goto(url), browser.back(), browser.click(index), browser.type(text), browser.input(index, text), browser.keys(keys), browser.upload(index, path), browser.screenshot(path), browser.scroll(direction, amount), browser.wait(seconds).

Tunnels

Expose local dev servers to the browser via Cloudflare tunnels.

browser-use tunnel <port>                 # Start tunnel (idempotent)
browser-use tunnel list                   # Show active tunnels
browser-use tunnel stop <port>            # Stop tunnel
browser-use tunnel stop --all             # Stop all tunnels

Command Chaining

Commands can be chained with &&. The browser persists via the daemon, so chaining is safe and efficient.

browser-use open https://example.com && browser-use state
browser-use input 5 "user@example.com" && browser-use input 6 "password" && browser-use click 7

Chain when you don't need intermediate output. Run separately when you need to parse state to discover indices first.

Common Workflows

Exposing Local Dev Servers

python -m http.server 3000 &                      # Start dev server
browser-use tunnel 3000                            # → https://abc.trycloudflare.com
browser-use open https://abc.trycloudflare.com     # Browse the tunnel

Tunnels are independent of browser sessions and persist across browser-use close.

Multi-Agent (--connect mode)

Multiple agents can share one browser via --connect. Each agent gets its own tab — other agents can't interfere.

Setup: Register once, then pass the index with every --connect command:

INDEX=$(browser-use register)                    # → prints "1"
browser-use --connect $INDEX open <url>          # Navigate in agent's own tab
browser-use --connect $INDEX state               # Get state from agent's tab
browser-use --connect $INDEX click <element>     # Click in agent's tab

• Tab locking: When an agent mutates a tab (click, type, navigate), that tab is locked to it. Other agents get an error if they try to mutate the same tab.
• Read-only access: state, screenshot, get, and wait commands work on any tab regardless of locks.
• Agent sessions expire after 5 minutes of inactivity. Run browser-use register again to get a new index.

Global Options

Tips

1. Always run state first to see available elements and their indices
2. Sessions persist — browser stays open between commands until you close it
3. Tunnels are independent — they persist across browser-use close
4. tunnel is idempotent — calling again for the same port returns the existing URL

Troubleshooting

• Browser won't start? browser-use close then retry. Run browser-use doctor to check.
• Element not found? browser-use scroll down then browser-use state
• Tunnel not working? which cloudflared to check, browser-use tunnel list to see active tunnels

Cleanup

browser-use close                         # Close browser session
browser-use tunnel stop --all             # Stop tunnels (if any)

Manim Video Production Pipeline

Creative Standard

This is educational cinema. Every frame teaches. Every animation reveals structure.

Before writing a single line of code, articulate the narrative arc. What misconception does this correct? What is the "aha moment"? What visual story takes the viewer from confusion to understanding? The user's prompt is a starting point — interpret it with pedagogical ambition.

Geometry before algebra. Show the shape first, the equation second. Visual memory encodes faster than symbolic memory. When the viewer sees the geometric pattern before the formula, the equation feels earned.

First-render excellence is non-negotiable. The output must be visually clear and aesthetically cohesive without revision rounds. If something looks cluttered, poorly timed, or like "AI-generated slides," it is wrong.

Opacity layering directs attention. Never show everything at full brightness. Primary elements at 1.0, contextual elements at 0.4, structural elements (axes, grids) at 0.15. The brain processes visual salience in layers.

Breathing room. Every animation needs self.wait() after it. The viewer needs time to absorb what just appeared. Never rush from one animation to the next. A 2-second pause after a key reveal is never wasted.

Cohesive visual language. All scenes share a color palette, consistent typography sizing, matching animation speeds. A technically correct video where every scene uses random different colors is an aesthetic failure.

Prerequisites

Run scripts/setup.sh to verify all dependencies. Requires: Python 3.10+, Manim Community Edition v0.20+ (pip install manim), LaTeX (texlive-full on Linux, mactex on macOS), and ffmpeg. Reference docs tested against Manim CE v0.20.1.

Modes

Stack

Single Python script per project. No browser, no Node.js, no GPU required.

Pipeline

PLAN --> CODE --> RENDER --> STITCH --> AUDIO (optional) --> REVIEW

1. PLAN — Write plan.md with narrative arc, scene list, visual elements, color palette, voiceover script
2. CODE — Write script.py with one class per scene, each independently renderable
3. RENDER — manim -ql script.py Scene1 Scene2 ... for draft, -qh for production
4. STITCH — ffmpeg concat of scene clips into final.mp4
5. AUDIO (optional) — Add voiceover and/or background music via ffmpeg. See references/rendering.md
6. REVIEW — Render preview stills, verify against plan, adjust

Project Structure

project-name/
  plan.md                # Narrative arc, scene breakdown
  script.py              # All scenes in one file
  concat.txt             # ffmpeg scene list
  final.mp4              # Stitched output
  media/                 # Auto-generated by Manim
    videos/script/480p15/

Creative Direction

Color Palettes

Animation Speed

Typography Scale

Fonts

Use monospace fonts for all text. Manim's Pango renderer produces broken kerning with proportional fonts at all sizes. See references/visual-design.md for full recommendations.

MONO = "Menlo"  # define once at top of file

Text("Fourier Series", font_size=48, font=MONO, weight=BOLD)  # titles
Text("n=1: sin(x)", font_size=20, font=MONO)                  # labels
MathTex(r"\nabla L")                                            # math (uses LaTeX)

Minimum font_size=18 for readability.

Per-Scene Variation

Never use identical config for all scenes. For each scene:

• Different dominant color from the palette
• Different layout — don't always center everything
• Different animation entry — vary between Write, FadeIn, GrowFromCenter, Create
• Different visual weight — some scenes dense, others sparse

Workflow

Step 1: Plan (plan.md)

Before any code, write plan.md. See references/scene-planning.md for the comprehensive template.

Step 2: Code (script.py)

One class per scene. Every scene is independently renderable.

from manim import *

BG = "#1C1C1C"
PRIMARY = "#58C4DD"
SECONDARY = "#83C167"
ACCENT = "#FFFF00"
MONO = "Menlo"

class Scene1_Introduction(Scene):
    def construct(self):
        self.camera.background_color = BG
        title = Text("Why Does This Work?", font_size=48, color=PRIMARY, weight=BOLD, font=MONO)
        self.add_subcaption("Why does this work?", duration=2)
        self.play(Write(title), run_time=1.5)
        self.wait(1.0)
        self.play(FadeOut(title), run_time=0.5)

Key patterns:

• Subtitles on every animation: self.add_subcaption("text", duration=N) or subcaption="text" on self.play()
• Shared color constants at file top for cross-scene consistency
• self.camera.background_color set in every scene
• Clean exits — FadeOut all mobjects at scene end: self.play(FadeOut(Group(*self.mobjects)))

Step 3: Render

manim -ql script.py Scene1_Introduction Scene2_CoreConcept  # draft
manim -qh script.py Scene1_Introduction Scene2_CoreConcept  # production

Step 4: Stitch

cat > concat.txt << 'EOF'
file 'media/videos/script/480p15/Scene1_Introduction.mp4'
file 'media/videos/script/480p15/Scene2_CoreConcept.mp4'
EOF
ffmpeg -y -f concat -safe 0 -i concat.txt -c copy final.mp4

Step 5: Review

manim -ql --format=png -s script.py Scene2_CoreConcept  # preview still

Critical Implementation Notes

Raw Strings for LaTeX

# WRONG: MathTex("\frac{1}{2}")
# RIGHT:
MathTex(r"\frac{1}{2}")

buff >= 0.5 for Edge Text

label.to_edge(DOWN, buff=0.5)  # never < 0.5

FadeOut Before Replacing Text

self.play(ReplacementTransform(note1, note2))  # not Write(note2) on top

Never Animate Non-Added Mobjects

self.play(Create(circle))  # must add first
self.play(circle.animate.set_color(RED))  # then animate

Performance Targets

Always iterate at -ql. Only render -qh for final output.

References

Creative Divergence (use only when user requests experimental/creative/unique output)

If the user asks for creative, experimental, or unconventional explanatory approaches, select a strategy and reason through it BEFORE designing the animation.

• SCAMPER — when the user wants a fresh take on a standard explanation
• Assumption Reversal — when the user wants to challenge how something is typically taught

SCAMPER Transformation

Take a standard mathematical/technical visualization and transform it:

• Substitute: replace the standard visual metaphor (number line → winding path, matrix → city grid)
• Combine: merge two explanation approaches (algebraic + geometric simultaneously)
• Reverse: derive backward — start from the result and deconstruct to axioms
• Modify: exaggerate a parameter to show why it matters (10x the learning rate, 1000x the sample size)
• Eliminate: remove all notation — explain purely through animation and spatial relationships

Assumption Reversal

1. List what's "standard" about how this topic is visualized (left-to-right, 2D, discrete steps, formal notation)
2. Pick the most fundamental assumption
3. Reverse it (right-to-left derivation, 3D embedding of a 2D concept, continuous morphing instead of steps, zero notation)
4. Explore what the reversal reveals that the standard approach hides

Video Use

Principle

1. LLM reasons from raw transcript + on-demand visuals. The only derived artifact that earns its keep is a packed phrase-level transcript (takes_packed.md). Everything else — filler tagging, retake detection, shot classification, emphasis scoring — you derive at decision time.
2. Audio is primary, visuals follow. Cut candidates come from speech boundaries and silence gaps. Drill into visuals only at decision points.
3. Ask → confirm → execute → iterate → persist. Never touch the cut until the user has confirmed the strategy in plain English.
4. Generalize. Do not assume what kind of video this is. Look at the material, ask the user, then edit.
5. Artistic freedom is the default. Every specific value, preset, font, color, duration, pitch structure, and technique in this document is a worked example from one proven video — not a mandate. Read them to understand what's possible and why each worked. Then make your own taste calls based on what the material actually is and what the user actually wants. The only things you MUST do are in the Hard Rules section below. Everything else is yours.
6. Invent freely. If the material calls for a technique not described here — split-screen, picture-in-picture, lower-third identity cards, reaction cuts, speed ramps, freeze frames, crossfades, match cuts, L-cuts, J-cuts, speed ramps over breath, whatever — build it. The helpers are ffmpeg and PIL. They can do anything the format supports. Do not wait for permission.
7. Verify your own output before showing it to the user. If you wouldn't ship it, don't present it.

Hard Rules (production correctness — non-negotiable)

These are the things where deviation produces silent failures or broken output. They are not taste, they are correctness. Memorize them.

1. Subtitles are applied LAST in the filter chain, after every overlay. Otherwise overlays hide captions. Silent failure.
2. Per-segment extract → lossless -c copy concat, not single-pass filtergraph. Otherwise you double-encode every segment when overlays are added.
3. 30ms audio fades at every segment boundary (afade=t=in:st=0:d=0.03,afade=t=out:st={dur-0.03}:d=0.03). Otherwise audible pops at every cut.
4. Overlays use setpts=PTS-STARTPTS+T/TB to shift the overlay's frame 0 to its window start. Otherwise you see the middle of the animation during the overlay window.
5. Master SRT uses output-timeline offsets: output_time = word.start - segment_start + segment_offset. Otherwise captions misalign after segment concat.
6. Never cut inside a word. Snap every cut edge to a word boundary from the Scribe transcript.
7. Pad every cut edge. Working window: 30–200ms. Scribe timestamps drift 50–100ms — padding absorbs the drift. Tighter for fast-paced, looser for cinematic.
8. Word-level verbatim ASR only. Never SRT/phrase mode (loses sub-second gap data). Never normalized fillers (loses editorial signal).
9. Cache transcripts per source. Never re-transcribe unless the source file itself changed.
10. Parallel sub-agents for multiple animations. Never sequential. Spawn N at once via the Agent tool; total wall time ≈ slowest one.
11. Strategy confirmation before execution. Never touch the cut until the user has approved the plain-English plan.
12. All session outputs in <videos_dir>/edit/. Never write inside the video-use/ project directory.

Everything else in this document is a worked example. Deviate whenever the material calls for it.

Directory layout

The skill lives in video-use/. User footage lives wherever they put it. All session outputs go into <videos_dir>/edit/.

<videos_dir>/
├── <source files, untouched>
└── edit/
    ├── project.md               ← memory; appended every session
    ├── takes_packed.md          ← phrase-level transcripts, the LLM's primary reading view
    ├── edl.json                 ← cut decisions
    ├── transcripts/<name>.json  ← cached raw Scribe JSON
    ├── animations/slot_<id>/    ← per-animation source + render + reasoning
    ├── clips_graded/            ← per-segment extracts with grade + fades
    ├── master.srt               ← output-timeline subtitles
    ├── downloads/               ← yt-dlp outputs
    ├── verify/                  ← debug frames / timeline PNGs
    ├── preview.mp4
    └── final.mp4

Setup

First-time install lives in install.md (clone, deps, ffmpeg, skill registration, API key). Don't re-run it every session; on cold start just verify:

• ELEVENLABS_API_KEY resolves — either in the environment or in .env at the video-use repo root. If missing, ask the user to paste one and write it to .env (never to the user's <videos_dir>).
• ffmpeg + ffprobe on PATH.
• Python deps installed (uv sync or pip install -e . inside the repo).
• Node.js + npm available if the session needs HyperFrames or Remotion slots. HyperFrames currently requires Node.js 22+.
• yt-dlp, HyperFrames, Remotion, Manim installed only on first use.
• First-use animation setup happens inside the slot directory, never at the video-use repo root. HyperFrames can be invoked with npx --yes hyperframes ...; Remotion can be scaffolded with npx create-video@latest or installed as a project-local dependency before using its remotion render command.
• This skill vendors skills/manim-video/. Read its SKILL.md when building a Manim slot.

Helpers (helpers/transcribe.py, helpers/render.py, etc.) live alongside this SKILL.md. Resolve their paths relative to the directory containing this file — the skill is typically symlinked at ~/.claude/skills/video-use/ or ~/.codex/skills/video-use/.

Helpers

• transcribe.py <video> — single-file Scribe call. --num-speakers N optional. Cached.
• transcribe_batch.py <videos_dir> — 4-worker parallel transcription. Use for multi-take.
• pack_transcripts.py --edit-dir <dir> — transcripts/*.json → takes_packed.md (phrase-level, break on silence ≥ 0.5s).
• timeline_view.py <video> <start> <end> — filmstrip + waveform PNG. On-demand visual drill-down. Not a scan tool — use it at decision points, not constantly.
• render.py <edl.json> -o <out> — per-segment extract → concat → overlays (PTS-shifted) → subtitles LAST. --preview for 720p fast. --build-subtitles to generate master.srt inline.
• grade.py <in> -o <out> — ffmpeg filter chain grade. Presets + --filter '<raw>' for custom.

For animations, create <edit>/animations/slot_<id>/ with Bash and spawn a sub-agent via the Agent tool.

The process

1. Inventory. ffprobe every source. transcribe_batch.py on the directory. pack_transcripts.py to produce takes_packed.md. Sample one or two timeline_views for a visual first impression.

2. Pre-scan for problems. One pass over takes_packed.md to note verbal slips, obvious mis-speaks, or phrasings to avoid. Plain list, feed into the editor brief.

3. Converse. Describe what you see in plain English. Ask questions shaped by the material. Collect: content type, target length/aspect, aesthetic/brand direction, pacing feel, must-preserve moments, must-cut moments, animation and grade preferences, subtitle needs. Do not use a fixed checklist — the right questions are different every time.

4. Propose strategy. 4–8 sentences: shape, take choices, cut direction, animation plan, grade direction, subtitle style, length estimate. Wait for confirmation.

5. Execute. Produce edl.json via the editor sub-agent brief. Drill into timeline_view at ambiguous moments. Build animations in parallel sub-agents. Apply grade per-segment. Compose via render.py.

6. Preview. render.py --preview.

7. Self-eval (before showing the user). Run timeline_view on the rendered output (not the sources) at every cut boundary (±1.5s window). Check each image for:

   • Visual discontinuity / flash / jump at the cut
   • Waveform spike at the boundary (audio pop that slipped past the 30ms fade)
   • Subtitle hidden behind an overlay (Rule 1 violation)
   • Overlay misaligned or showing wrong frames (Rule 4 violation)

   Also sample: first 2s, last 2s, and 2–3 mid-points — check grade consistency, subtitle readability, overall coherence. Run ffprobe on the output to verify duration matches the EDL expectation.

   If anything fails: fix → re-render → re-eval. Cap at 3 self-eval passes — if issues remain after 3, flag them to the user rather than looping forever. Only present the preview once the self-eval passes.

8. Iterate + persist. Natural-language feedback, re-plan, re-render. Never re-transcribe. Final render on confirmation. Append to project.md.

Cut craft (techniques)

• Audio-first. Candidate cuts from word boundaries and silence gaps.
• Preserve peaks. Laughs, punchlines, emphasis beats. Extend past punchlines to include reactions — the laugh IS the beat.
• Speaker handoffs benefit from air between utterances. Common values: 400–600ms. Less for fast-paced, more for cinematic. Taste call.
• Audio events as signals. (laughs), (sighs), (applause) mark beats. Extend past them.
• Silence gaps are cut candidates. Silences ≥400ms are usually the cleanest. 150–400ms phrase boundaries are usable with a visual check. <150ms is unsafe (mid-phrase).
• Example cut padding (the launch video shipped with this): 50ms before the first kept word, 80ms after the last. Tighter for montage energy, looser for documentary. Stay in the 30–200ms working window (Hard Rule 7).
• Never reason audio and video independently. Every cut must work on both tracks.

The packed transcript (primary reading view)

pack_transcripts.py reads all transcripts/*.json and produces one markdown file where each take is a list of phrase-level lines, each prefixed with its [start-end] time range. Phrases break on any silence ≥ 0.5s OR speaker change. This is the artifact the editor sub-agent reads to pick cuts — it gives word-boundary precision from text alone at 1/10 the tokens of raw JSON.

Example line:

## C0103  (duration: 43.0s, 8 phrases)
  [002.52-005.36] S0 Ninety percent of what a web agent does is completely wasted.
  [006.08-006.74] S0 We fixed this.

Editor sub-agent brief (for multi-take selection)

When the task is "pick the best take of each beat across many clips," spawn a dedicated sub-agent with a brief shaped like this. The structure is load-bearing; the pitch-shape example is not.

You are editing a <type> video. Pick the best take of each beat and 
assemble them chronologically by beat, not by source clip order.

INPUTS:
  - takes_packed.md (time-annotated phrase-level transcripts of all takes)
  - Product/narrative context: <2 sentences from the user>
  - Speaker(s): <name, role, delivery style note>
  - Expected structure: <pick an archetype or invent one>
  - Verbal slips to avoid: <list from the pre-scan pass>
  - Target runtime: <seconds>

Common structural archetypes (pick, adapt, or invent):
  - Tech launch / demo:   HOOK → PROBLEM → SOLUTION → BENEFIT → EXAMPLE → CTA
  - Tutorial:             INTRO → SETUP → STEPS → GOTCHAS → RECAP
  - Interview:            (QUESTION → ANSWER → FOLLOWUP) repeat
  - Travel / event:       ARRIVAL → HIGHLIGHTS → QUIET MOMENTS → DEPARTURE
  - Documentary:          THESIS → EVIDENCE → COUNTERPOINT → CONCLUSION
  - Music / performance:  INTRO → VERSE → CHORUS → BRIDGE → OUTRO
  - Or invent your own.

RULES:
  - Start/end times must fall on word boundaries from the transcript.
  - Pad cut boundaries (working window 30–200ms).
  - Prefer silences ≥ 400ms as cut targets.
  - Unavoidable slips are kept if no better take exists. Note them in "reason".
  - If over budget, revise: drop a beat or trim tails. Report total and self-correct.

OUTPUT (JSON array, no prose):
  [{"source": "C0103", "start": 2.42, "end": 6.85, "beat": "HOOK",
    "quote": "...", "reason": "..."}, ...]

Return the final EDL and a one-line total runtime check.

Color grade (when requested)

Your job is to reason about the image, not apply a preset. Look at a frame (via timeline_view), decide what's wrong, adjust one thing, look again.

Mental model is ASC CDL. Per channel: out = (in * slope + offset) ** power, then global saturation. slope → highlights, offset → shadows, power → midtones.

Example filter chains (grade.py has --list-presets; use them as starting points or mix your own):

• warm_cinematic — retro/technical, subtle teal/orange split, desaturated. Shipped in a real launch video. Safe for talking heads.
• neutral_punch — minimal corrective: contrast bump + gentle S-curve. No hue shifts.
• none — straight copy. Default when the user hasn't asked.

For anything else — portraiture, nature, product, music video, documentary — invent your own chain. grade.py --filter '<raw ffmpeg>' accepts any filter string.

Hard rules: apply per-segment during extraction (not post-concat, which re-encodes twice). Never go aggressive without testing skin tones.

Subtitles (when requested)

Subtitles have three dimensions worth reasoning about: chunking (1/2/3/sentence per line), case (UPPER/Title/Natural), and placement (margin from bottom). The right combo depends on content.

Worked styles — pick, adapt, or invent:

bold-overlay — short-form tech launch, fast-paced social. 2-word chunks, UPPERCASE, break on punctuation, Helvetica 18 Bold, white-on-outline, MarginV=35. render.py ships with this as SUB_FORCE_STYLE.

FontName=Helvetica,FontSize=18,Bold=1,
PrimaryColour=&H00FFFFFF,OutlineColour=&H00000000,BackColour=&H00000000,
BorderStyle=1,Outline=2,Shadow=0,
Alignment=2,MarginV=35

natural-sentence (if you invent this mode) — narrative, documentary, education. 4–7 word chunks, sentence case, break on natural pauses, MarginV=60–80, larger font for readability, slightly wider max-width. No shipped force_style — design one if you need it.

Invent a third style if neither fits. Hard rules: subtitles LAST (Rule 1), output-timeline offsets (Rule 5).

Animations (when requested)

Animations match the content and the brand. Get the palette, font, and visual language from the conversation — never assume a default. If the user hasn't told you, propose a palette in the strategy phase and wait for confirmation before building anything.

Tool options:

Pick the engine per animation slot. Do not default to Remotion just because the animation is web-adjacent.

• HyperFrames — Browser-native HTML/CSS/GSAP video compositions: product UI motion, website-to-video or mockup-to-video captures, kinetic typography, landing-page/storyboard promos, data-driven UI states, transparent WebM overlays, and clips that need deterministic frame capture plus HyperFrames lint/validate/render checks. Best when the animation should be authored and verified like a web composition instead of a React component tree.
• Remotion — React/CSS compositions with component state, reusable React primitives, or an existing Remotion brand system. Best when the user specifically asks for React/Remotion or when React composition is the simpler authoring model.
• Manim — formal diagrams, state machines, equation derivations, graph morphs. Read skills/manim-video/SKILL.md and its references for depth.
• PIL + PNG sequence + ffmpeg — simple overlay cards: counters, typewriter text, single bar reveals, progressive draws. Fast to iterate, any aesthetic you want. The launch video used this.

For HyperFrames slots, scaffold the slot inside edit/animations/slot_<id>/ with npx --yes hyperframes init . --example blank --non-interactive --skip-skills, build the HTML composition there, run the HyperFrames checks that fit the slot (lint, validate, and a draft render when practical), then produce the final overlay video with npx --yes hyperframes render . -o render.mp4 or --format webm -o render.webm when alpha is required. Point the EDL overlay file at the actual rendered path.

For Remotion slots, keep the Remotion project isolated inside the same slot directory, scaffold with npx create-video@latest or install Remotion locally there, render the composition to render.mp4 with the project-local remotion render command, and verify duration and dimensions with ffprobe.

None is mandatory. Invent hybrids if useful (e.g., PIL background with a HyperFrames or Remotion layer on top).

Duration rules of thumb, context-dependent:

• Sync-to-narration explanations. A viewer needs to parse the content at 1×. Rough floor 3s, typical 5–7s for simple cards, 8–14s for complex diagrams. The launch video shipped at 5–7s per simple card.
• Beat-synced accents (music video, fast montage). 0.5–2s is fine — they're visual accents, not information. The "readable at 1×" rule becomes "recognizable at 1×", not "fully parseable."
• Hold the final frame ≥ 1s before the cut (universal).
• Over voiceover: total duration ≥ narration_length + 1s (universal).
• Never parallel-reveal independent elements — the eye can't track two new things at once. One thing, pause, next thing.

Animation payoff timing (rule for sync-to-narration): get the payoff word's timestamp. Start the overlay reveal_duration seconds earlier so the landing frame coincides with the spoken payoff word. Without this sync the animation feels disconnected.

Easing (universal — never linear, it looks robotic):

def ease_out_cubic(t):    return 1 - (1 - t) ** 3
def ease_in_out_cubic(t):
    if t < 0.5: return 4 * t ** 3
    return 1 - (-2 * t + 2) ** 3 / 2

ease_out_cubic for single reveals (slow landing). ease_in_out_cubic for continuous draws.

Typing text anchor trick: center on the FULL string's width, not the partial-string width — otherwise text slides left during reveal.

Example palette (the launch video — one aesthetic among infinite):

• Background (10, 10, 10) near-black
• Accent #FF5A00 / (255, 90, 0) orange
• Labels (110, 110, 110) dim gray
• Font: Menlo Bold at /System/Library/Fonts/Menlo.ttc (index 1)
• ≤ 2 accent colors, ~40% empty space, minimal chrome
• Result: terminal / retro tech feel

This is one style. If the brand is warm and serif, use that. If it's colorful and playful, use that. If the user handed you a style guide, follow it. If they didn't, propose one and confirm.

Parallel sub-agent brief — each animation is one sub-agent spawned via the Agent tool. Each prompt is self-contained (sub-agents have no parent context). Include:

1. One-sentence goal: "Build ONE animation: [spec]. Nothing else."
2. Absolute output path (<edit>/animations/slot_<id>/render.mp4)
3. Exact technical spec: resolution, fps, codec, pix_fmt, CRF, duration
4. Style palette as concrete values (RGB tuples, hex, or reference to a design system)
5. Font path with index
6. Frame-by-frame timeline (what happens when, with easing)
7. Anti-list ("no chrome, no extras, no titles unless specified")
8. Code pattern reference (copy helpers inline, don't import across slots)
9. Deliverable checklist (script, render, verify duration via ffprobe, report)
10. "Do not ask questions. If anything is ambiguous, pick the most obvious interpretation and proceed."

One sub-agent = one file (unique filenames, parallel agents don't overwrite each other).

Output spec

Match the source unless the user asked for something specific. Common targets: 1920×1080@24 cinematic, 1920×1080@30 screen content, 1080×1920@30 vertical social, 3840×2160@24 4K cinema, 1080×1080@30 square. render.py defaults the scale to 1080p from any source; pass --filter or edit the extract command for other targets. Worth asking the user which delivery format matters.

EDL format

{
  "version": 1,
  "sources": {"C0103": "/abs/path/C0103.MP4", "C0108": "/abs/path/C0108.MP4"},
  "ranges": [
    {"source": "C0103", "start": 2.42, "end": 6.85,
     "beat": "HOOK", "quote": "...", "reason": "Cleanest delivery, stops before slip at 38.46."},
    {"source": "C0108", "start": 14.30, "end": 28.90,
     "beat": "SOLUTION", "quote": "...", "reason": "Only take without the false start."}
  ],
  "grade": "warm_cinematic",
  "overlays": [
    {"file": "edit/animations/slot_1/render.mp4", "start_in_output": 0.0, "duration": 5.0}
  ],
  "subtitles": "edit/master.srt",
  "total_duration_s": 87.4
}

grade is a preset name or raw ffmpeg filter. overlays are rendered animation clips. subtitles is optional and applied LAST.

Memory — project.md

Append one section per session at <edit>/project.md:

## Session N — YYYY-MM-DD

**Strategy:** one paragraph describing the approach
**Decisions:** take choices, cuts, grades, animations + why
**Reasoning log:** one-line rationale for non-obvious decisions
**Outstanding:** deferred items

On startup, read project.md if it exists and summarize the last session in one sentence before asking whether to continue.

Anti-patterns

Things that consistently fail regardless of style:

• Hierarchical pre-computed codec formats with USABILITY / tone tags / shot layers. Over-engineering. Derive from the transcript at decision time.
• Hand-tuned moment-scoring functions. The LLM picks better than any heuristic you'll write.
• Whisper SRT / phrase-level output. Loses sub-second gap data. Always word-level verbatim.
• Running Whisper locally on CPU. Slow and it normalizes fillers. Use hosted Scribe.
• Burning subtitles into base before compositing overlays. Overlays hide them. (Hard Rule 1.)
• Single-pass filtergraph when you have overlays. Double re-encodes. Use per-segment extract → concat.
• Linear animation easing. Looks robotic. Always cubic.
• Hard audio cuts at segment boundaries. Audible pops. (Hard Rule 3.)
• Typing text centered on the partial string. Text slides left as it grows.
• Sequential sub-agents for multiple animations. Always parallel.
• Editing before confirming the strategy. Never.
• Re-transcribing cached sources. Immutable outputs of immutable inputs.
• Assuming what kind of video it is. Look first, ask second, edit last.

Cloudflare Agents SDK

Your knowledge of the Agents SDK may be outdated. Prefer retrieval over pre-training for any Agents SDK task.

Retrieval Sources

Cloudflare docs: https://developers.cloudflare.com/agents/

Capabilities

The Agents SDK provides:

• Persistent state — SQLite-backed, auto-synced to clients via setState
• Callable RPC — @callable() methods invoked over WebSocket
• Scheduling — One-time, recurring (scheduleEvery), and cron tasks
• Workflows — Durable multi-step background processing via AgentWorkflow
• Durable execution — runFiber() / stash() for work that survives DO eviction
• Queue — Built-in FIFO queue with retries via queue()
• Retries — this.retry() with exponential backoff and jitter
• MCP integration — Connect to MCP servers or build your own with McpAgent
• Email handling — Receive and reply to emails with secure routing
• Streaming chat — AIChatAgent with resumable streams, message persistence, tools
• Server-driven messages — saveMessages, waitUntilStable for proactive agent turns
• React hooks — useAgent, useAgentChat for client apps
• Observability — diagnostics_channel events for state, RPC, schedule, lifecycle
• Push notifications — Web Push + VAPID delivery from agents
• Webhooks — Receive and verify external webhooks
• Voice (experimental) — STT/TTS via @cloudflare/voice
• Browser tools (experimental) — CDP-powered browsing via agents/browser
• Think (experimental) — Higher-level chat agent via @cloudflare/think

FIRST: Verify Installation

npm ls agents  # Should show agents package

If not installed:

npm install agents

For chat agents:

npm install agents @cloudflare/ai-chat ai @ai-sdk/react

Wrangler Configuration

{
  "compatibility_flags": ["nodejs_compat"],
  "durable_objects": {
    "bindings": [{ "name": "MyAgent", "class_name": "MyAgent" }]
  },
  "migrations": [{ "tag": "v1", "new_sqlite_classes": ["MyAgent"] }]
}

Gotchas:

• Do NOT enable experimentalDecorators in tsconfig (breaks @callable)
• Never edit old migrations — always add new tags
• Each agent class needs its own DO binding + migration entry
• Add "ai": { "binding": "AI" } for Workers AI

Agent Class

import { Agent, routeAgentRequest, callable } from "agents";

type State = { count: number };

export class Counter extends Agent<Env, State> {
  initialState = { count: 0 };

  validateStateChange(nextState: State, source: Connection | "server") {
    if (nextState.count < 0) throw new Error("Count cannot be negative");
  }

  onStateUpdate(state: State, source: Connection | "server") {
    console.log("State updated:", state);
  }

  @callable()
  increment() {
    this.setState({ count: this.state.count + 1 });
    return this.state.count;
  }
}

export default {
  fetch: (req, env) => routeAgentRequest(req, env) ?? new Response("Not found", { status: 404 })
};

Routing

Requests route to /agents/{agent-name}/{instance-name}:

Client: useAgent({ agent: "Counter", name: "user-123" })

Custom routing: use getAgentByName(env.MyAgent, "instance-id") then agent.fetch(request).

Core APIs

React Client

import { useAgent } from "agents/react";

function App() {
  const [state, setLocalState] = useState({ count: 0 });

  const agent = useAgent({
    agent: "Counter",
    name: "my-instance",
    onStateUpdate: (newState) => setLocalState(newState),
    onIdentity: (name, agentType) => console.log(`Connected to ${name}`)
  });

  return (
    <button onClick={() => agent.setState({ count: state.count + 1 })}>
      Count: {state.count}
    </button>
  );
}

References

Core

• references/state-scheduling.md — State persistence, scheduling, SQL
• references/callable.md — RPC methods, streaming, timeouts
• references/routing.md — URL patterns, custom routing, getAgentByName
• references/configuration.md — Wrangler config, bindings, Vite setup

Chat & Streaming

• references/streaming-chat.md — AIChatAgent, resumable streams, tools
• references/client-sdk.md — useAgent, useAgentChat, AgentClient
• references/server-driven-messages.md — Trigger patterns, saveMessages
• references/human-in-the-loop.md — Approval flows, needsApproval

Background Processing

• references/workflows.md — Durable Workflows integration
• references/durable-execution.md — runFiber, stash, surviving eviction
• references/queue-retries.md — Built-in queue, retry with backoff

Integrations

• references/mcp.md — MCP client and server, transports, securing
• references/email.md — Email routing and handling
• references/webhooks-push.md — Webhooks, push notifications
• references/observability.md — Diagnostics-channel events

Experimental

• references/think.md — @cloudflare/think higher-level chat agent
• references/voice.md — @cloudflare/voice STT/TTS
• references/codemode.md — Code Mode for tool orchestration
• references/browse-the-web.md — CDP browser tools

Cloudflare Platform Skill

Consolidated skill for building on the Cloudflare platform. Use decision trees below to find the right product, then load detailed references.

Your knowledge of Cloudflare APIs, types, limits, and pricing may be outdated. Prefer retrieval over pre-training — the references in this skill are starting points, not source of truth.

Retrieval Sources

Fetch the latest information before citing specific numbers, API signatures, or configuration options. Do not rely on baked-in knowledge or these reference files alone.

When a reference file and the docs disagree, trust the docs. This is especially important for: numeric limits, pricing tiers, type signatures, and configuration options.

Quick Decision Trees

"I need feature flags"

Need feature flags?
└─ Feature toggles, targeting rules, percentage rollouts → flagship/
   ├─ Evaluate in Workers → Flagship binding (env.FLAGS)
   ├─ Evaluate in Node.js / browser → OpenFeature SDK (@cloudflare/flagship)
   └─ Manage flags via API → Flagship REST API

"I need to run code"

Need to run code?
├─ Serverless functions at the edge → workers/
├─ Full-stack web app with Git deploys → pages/
├─ Stateful coordination/real-time → durable-objects/
├─ Long-running multi-step jobs → workflows/
├─ Run containers → containers/
├─ Multi-tenant (customers deploy code) → workers-for-platforms/
├─ Scheduled tasks (cron) → cron-triggers/
├─ Lightweight edge logic (modify HTTP) → snippets/
├─ Process Worker execution events (logs/observability) → tail-workers/
└─ Optimize latency to backend infrastructure → smart-placement/

"I need to store data"

Need storage?
├─ Key-value (config, sessions, cache) → kv/
├─ Relational SQL → d1/ (SQLite) or hyperdrive/ (existing Postgres/MySQL)
├─ Object/file storage (S3-compatible) → r2/
├─ Versioned file trees (repos, build outputs, checkpoints) → artifacts/
├─ Message queue (async processing) → queues/
├─ Vector embeddings (AI/semantic search) → vectorize/
├─ Strongly-consistent per-entity state → durable-objects/ (DO storage)
├─ Secrets management → secrets-store/
├─ Streaming ETL to R2 → pipelines/
└─ Persistent cache (long-term retention) → cache-reserve/

"I need AI/ML"

Need AI?
├─ Run inference (LLMs, embeddings, images) → workers-ai/
├─ Vector database for RAG/search → vectorize/
├─ Build stateful AI agents → agents-sdk/
├─ Gateway for any AI provider (caching, routing) → ai-gateway/
└─ AI-powered search widget → ai-search/

"I need networking/connectivity"

Need networking?
├─ Expose local service to internet → tunnel/
├─ TCP/UDP proxy (non-HTTP) → spectrum/
├─ WebRTC TURN server → turn/
├─ Private network connectivity → network-interconnect/
├─ Optimize routing → argo-smart-routing/
├─ Optimize latency to backend (not user) → smart-placement/
└─ Real-time video/audio → realtimekit/ or realtime-sfu/

"I need security"

Need security?
├─ Web Application Firewall → waf/
├─ DDoS protection → ddos/
├─ Bot detection/management → bot-management/
├─ API protection → api-shield/
├─ CAPTCHA alternative → turnstile/
└─ Credential leak detection → waf/ (managed ruleset)

"I need media/content"

Need media?
├─ Image optimization/transformation → images/
├─ Video streaming/encoding → stream/
├─ Browser automation/screenshots → browser-rendering/
└─ Third-party script management → zaraz/

"I need analytics/metrics data"

Need analytics?
├─ Query across all Cloudflare products (HTTP, Workers, DNS, etc.) → graphql-api/
├─ Custom high-cardinality metrics from Workers → analytics-engine/
├─ Client-side (RUM) performance data → web-analytics/
├─ Workers Logs and real-time debugging → observability/
└─ Raw logs (Logpush to external tools) → Cloudflare docs

"I need infrastructure-as-code"

Need IaC? → pulumi/ (Pulumi), terraform/ (Terraform), or api/ (REST API)

Product Index

Feature Flags

Compute & Runtime

Storage & Data

AI & Machine Learning

Networking & Connectivity

Security

Media & Content

Real-Time Communication

Developer Tools

Infrastructure as Code

Other Services

Durable Objects

Build stateful, coordinated applications on Cloudflare's edge using Durable Objects.

Retrieval Sources

Your knowledge of Durable Objects APIs and configuration may be outdated. Prefer retrieval over pre-training for any Durable Objects task.

Fetch the relevant doc page when implementing features.

When to Use

• Creating new Durable Object classes for stateful coordination
• Implementing RPC methods, alarms, or WebSocket handlers
• Reviewing existing DO code for best practices
• Configuring wrangler.jsonc/toml for DO bindings and migrations
• Writing tests with @cloudflare/vitest-pool-workers
• Designing sharding strategies and parent-child relationships

Reference Documentation

• ./references/rules.md - Core rules, storage, concurrency, RPC, alarms
• ./references/testing.md - Vitest setup, unit/integration tests, alarm testing
• ./references/workers.md - Workers handlers, types, wrangler config, observability

Search: blockConcurrencyWhile, idFromName, getByName, setAlarm, sql.exec

Core Principles

Use Durable Objects For

Do NOT Use For

• Stateless request handling (use plain Workers)
• Maximum global distribution needs
• High fan-out independent requests

Quick Reference

Wrangler Configuration

// wrangler.jsonc
{
  "durable_objects": {
    "bindings": [{ "name": "MY_DO", "class_name": "MyDurableObject" }]
  },
  "migrations": [{ "tag": "v1", "new_sqlite_classes": ["MyDurableObject"] }]
}

Basic Durable Object Pattern

import { DurableObject } from "cloudflare:workers";

export interface Env {
  MY_DO: DurableObjectNamespace<MyDurableObject>;
}

export class MyDurableObject extends DurableObject<Env> {
  constructor(ctx: DurableObjectState, env: Env) {
    super(ctx, env);
    ctx.blockConcurrencyWhile(async () => {
      this.ctx.storage.sql.exec(`
        CREATE TABLE IF NOT EXISTS items (
          id INTEGER PRIMARY KEY AUTOINCREMENT,
          data TEXT NOT NULL
        )
      `);
    });
  }

  async addItem(data: string): Promise<number> {
    const result = this.ctx.storage.sql.exec<{ id: number }>(
      "INSERT INTO items (data) VALUES (?) RETURNING id",
      data
    );
    return result.one().id;
  }
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const stub = env.MY_DO.getByName("my-instance");
    const id = await stub.addItem("hello");
    return Response.json({ id });
  },
};

Critical Rules

1. Model around coordination atoms - One DO per chat room/game/user, not one global DO
2. Use getByName() for deterministic routing - Same input = same DO instance
3. Use SQLite storage - Configure new_sqlite_classes in migrations
4. Initialize in constructor - Use blockConcurrencyWhile() for schema setup only
5. Use RPC methods - Not fetch() handler (compatibility date >= 2024-04-03)
6. Persist first, cache second - Always write to storage before updating in-memory state
7. One alarm per DO - setAlarm() replaces any existing alarm

Anti-Patterns (NEVER)

• Single global DO handling all requests (bottleneck)
• Using blockConcurrencyWhile() on every request (kills throughput)
• Storing critical state only in memory (lost on eviction/crash)
• Using await between related storage writes (breaks atomicity)
• Holding blockConcurrencyWhile() across fetch() or external I/O

Stub Creation

// Deterministic - preferred for most cases
const stub = env.MY_DO.getByName("room-123");

// From existing ID string
const id = env.MY_DO.idFromString(storedIdString);
const stub = env.MY_DO.get(id);

// New unique ID - store mapping externally
const id = env.MY_DO.newUniqueId();
const stub = env.MY_DO.get(id);

Storage Operations

// SQL (synchronous, recommended)
this.ctx.storage.sql.exec("INSERT INTO t (c) VALUES (?)", value);
const rows = this.ctx.storage.sql.exec<Row>("SELECT * FROM t").toArray();

// KV (async)
await this.ctx.storage.put("key", value);
const val = await this.ctx.storage.get<Type>("key");

Alarms

// Schedule (replaces existing)
await this.ctx.storage.setAlarm(Date.now() + 60_000);

// Handler
async alarm(): Promise<void> {
  // Process scheduled work
  // Optionally reschedule: await this.ctx.storage.setAlarm(...)
}

// Cancel
await this.ctx.storage.deleteAlarm();

Testing Quick Start

import { env } from "cloudflare:test";
import { describe, it, expect } from "vitest";

describe("MyDO", () => {
  it("should work", async () => {
    const stub = env.MY_DO.getByName("test");
    const result = await stub.addItem("test");
    expect(result).toBe(1);
  });
});

Cloudflare Sandbox SDK

Build secure, isolated code execution environments on Cloudflare Workers.

FIRST: Verify Installation

npm install @cloudflare/sandbox
docker info  # Must succeed - Docker required for local dev

Retrieval Sources

Your knowledge of the Sandbox SDK may be outdated. Prefer retrieval over pre-training for any Sandbox SDK task.

When implementing features, fetch the relevant doc page or example first.

Required Configuration

wrangler.jsonc (exact - do not modify structure):

{
  "containers": [{
    "class_name": "Sandbox",
    "image": "./Dockerfile",
    "instance_type": "lite",
    "max_instances": 1
  }],
  "durable_objects": {
    "bindings": [{ "class_name": "Sandbox", "name": "Sandbox" }]
  },
  "migrations": [{ "new_sqlite_classes": ["Sandbox"], "tag": "v1" }]
}

Worker entry - must re-export Sandbox class:

import { getSandbox } from '@cloudflare/sandbox';
export { Sandbox } from '@cloudflare/sandbox';  // Required export

Quick Reference

Core Patterns

Execute Commands

const sandbox = getSandbox(env.Sandbox, 'user-123');
const result = await sandbox.exec('python --version');
// result: { stdout, stderr, exitCode, success }

Code Interpreter (Recommended for AI)

Use runCode() for executing LLM-generated code with rich outputs:

const ctx = await sandbox.createCodeContext({ language: 'python' });

await sandbox.runCode('import pandas as pd; data = [1,2,3]', { context: ctx });
const result = await sandbox.runCode('sum(data)', { context: ctx });
// result.results[0].text = "6"

Languages: python, javascript, typescript

State persists within context. Create explicit contexts for production.

File Operations

await sandbox.mkdir('/workspace/project', { recursive: true });
await sandbox.writeFile('/workspace/project/main.py', code);
const file = await sandbox.readFile('/workspace/project/main.py');
const files = await sandbox.listFiles('/workspace/project');

When to Use What

Extending the Dockerfile

Base image (docker.io/cloudflare/sandbox:0.7.0) includes Python 3.11, Node.js 20, and common tools.

Add dependencies by extending the Dockerfile:

FROM docker.io/cloudflare/sandbox:0.7.0

# Python packages
RUN pip install requests beautifulsoup4

# Node packages (global)
RUN npm install -g typescript

# System packages
RUN apt-get update && apt-get install -y ffmpeg && rm -rf /var/lib/apt/lists/*

EXPOSE 8080  # Required for local dev port exposure

Keep images lean - affects cold start time.

Preview URLs (Port Exposure)

Expose HTTP services running in sandboxes:

const { url } = await sandbox.exposePort(8080);
// Returns preview URL for the service

Production requirement: Preview URLs need a custom domain with wildcard DNS (*.yourdomain.com). The .workers.dev domain does not support preview URL subdomains.

See: https://developers.cloudflare.com/sandbox/guides/expose-services/

OpenAI Agents SDK Integration

The SDK provides helpers for OpenAI Agents at @cloudflare/sandbox/openai:

import { Shell, Editor } from '@cloudflare/sandbox/openai';

See examples/openai-agents for complete integration pattern.

Sandbox Lifecycle

• getSandbox() returns immediately - container starts lazily on first operation
• Containers sleep after 10 minutes of inactivity (configurable via sleepAfter)
• Use destroy() to immediately free resources
• Same sandboxId always returns same sandbox instance

Anti-Patterns

• Don't use internal clients (CommandClient, FileClient) - use sandbox.* methods
• Don't skip the Sandbox export - Worker won't deploy without export { Sandbox }
• Don't hardcode sandbox IDs for multi-user - use user/session identifiers
• Don't forget cleanup - call destroy() for temporary sandboxes

Detailed References

• references/api-quick-ref.md - Full API with options and return types
• references/examples.md - Example index with use cases

Web Performance Audit

Your knowledge of web performance metrics, thresholds, and tooling APIs may be outdated. Prefer retrieval over pre-training when citing specific numbers or recommendations.

Retrieval Sources

FIRST: Verify MCP Tools Available

Run this before starting. Try calling navigate_page or performance_start_trace. If unavailable, STOP—the chrome-devtools MCP server isn't configured.

Ask the user to add this to their MCP config:

"chrome-devtools": {
  "type": "local",
  "command": ["npx", "-y", "chrome-devtools-mcp@latest"]
}

Key Guidelines

• Be assertive: Verify claims by checking network requests, DOM, or codebase—then state findings definitively.
• Verify before recommending: Confirm something is unused before suggesting removal.
• Quantify impact: Use estimated savings from insights. Don't prioritize changes with 0ms impact.
• Skip non-issues: If render-blocking resources have 0ms estimated impact, note but don't recommend action.
• Be specific: Say "compress hero.png (450KB) to WebP" not "optimize images".
• Prioritize ruthlessly: A site with 200ms LCP and 0 CLS is already excellent—say so.

Quick Reference

Workflow

Copy this checklist to track progress:

Audit Progress:
- [ ] Phase 1: Performance trace (navigate + record)
- [ ] Phase 2: Core Web Vitals analysis (includes CLS culprits)
- [ ] Phase 3: Network analysis
- [ ] Phase 4: Accessibility snapshot
- [ ] Phase 5: Codebase analysis (skip if third-party site)

Phase 1: Performance Trace

1. Navigate to the target URL:

   navigate_page(url: "<target-url>")
   

2. Start a performance trace with reload to capture cold-load metrics:

   performance_start_trace(autoStop: true, reload: true)
   

3. Wait for trace completion, then retrieve results.

Troubleshooting:

• If trace returns empty or fails, verify the page loaded correctly with navigate_page first
• If insight names don't match, inspect the trace response to list available insights

Phase 2: Core Web Vitals Analysis

Use performance_analyze_insight to extract key metrics.

Note: Insight names may vary across Chrome DevTools versions. If an insight name doesn't work, check the insightSetId from the trace response to discover available insights.

Common insight names:

Example:

performance_analyze_insight(insightSetId: "<id-from-trace>", insightName: "LCPBreakdown")

Key thresholds (good/needs-improvement/poor):

• TTFB: < 800ms / < 1.8s / > 1.8s
• FCP: < 1.8s / < 3s / > 3s
• LCP: < 2.5s / < 4s / > 4s
• INP: < 200ms / < 500ms / > 500ms
• TBT: < 200ms / < 600ms / > 600ms
• CLS: < 0.1 / < 0.25 / > 0.25
• Speed Index: < 3.4s / < 5.8s / > 5.8s

Phase 3: Network Analysis

List all network requests to identify optimization opportunities:

list_network_requests(resourceTypes: ["Script", "Stylesheet", "Document", "Font", "Image"])

Look for:

1. Render-blocking resources: JS/CSS in <head> without async/defer/media attributes
2. Network chains: Resources discovered late because they depend on other resources loading first (e.g., CSS imports, JS-loaded fonts)
3. Missing preloads: Critical resources (fonts, hero images, key scripts) not preloaded
4. Caching issues: Missing or weak Cache-Control, ETag, or Last-Modified headers
5. Large payloads: Uncompressed or oversized JS/CSS bundles
6. Unused preconnects: If flagged, verify by checking if ANY requests went to that origin. If zero requests, it's definitively unused—recommend removal. If requests exist but loaded late, the preconnect may still be valuable.

For detailed request info:

get_network_request(reqid: <id>)

Phase 4: Accessibility Snapshot

Take an accessibility tree snapshot:

take_snapshot(verbose: true)

Flag high-level gaps:

• Missing or duplicate ARIA IDs
• Elements with poor contrast ratios (check against WCAG AA: 4.5:1 for normal text, 3:1 for large text)
• Focus traps or missing focus indicators
• Interactive elements without accessible names

Phase 5: Codebase Analysis

Skip if auditing a third-party site without codebase access.

Analyze the codebase to understand where improvements can be made.

Detect Framework & Bundler

Search for configuration files to identify the stack:

Also check package.json for framework dependencies and build scripts.

Tree-Shaking & Dead Code

• Webpack: Check for mode: 'production', sideEffects in package.json, usedExports optimization
• Vite/Rollup: Tree-shaking enabled by default; check for treeshake options
• Look for: Barrel files (index.js re-exports), large utility libraries imported wholesale (lodash, moment)

Unused JS/CSS

• Check for CSS-in-JS vs. static CSS extraction
• Look for PurgeCSS/UnCSS configuration (Tailwind's content config)
• Identify dynamic imports vs. eager loading

Polyfills

• Check for @babel/preset-env targets and useBuiltIns setting
• Look for core-js imports (often oversized)
• Check browserslist config for overly broad targeting

Compression & Minification

• Check for terser, esbuild, or swc minification
• Look for gzip/brotli compression in build output or server config
• Check for source maps in production builds (should be external or disabled)

Output Format

Present findings as:

1. Core Web Vitals Summary - Table with metric, value, and rating (good/needs-improvement/poor)
2. Top Issues - Prioritized list of problems with estimated impact (high/medium/low)
3. Recommendations - Specific, actionable fixes with code snippets or config changes
4. Codebase Findings - Framework/bundler detected, optimization opportunities (omit if no codebase access)

Your knowledge of Cloudflare Workers APIs, types, and configuration may be outdated. Prefer retrieval over pre-training for any Workers code task — writing or reviewing.

Retrieval Sources

Fetch the latest versions before writing or reviewing Workers code. Do not rely on baked-in knowledge for API signatures, config fields, or binding shapes.

FIRST: Fetch Latest References

Before reviewing or writing Workers code, retrieve the current best practices page and relevant type definitions. If the project's node_modules has an older version, prefer the latest published version.

# Fetch latest workers types
mkdir -p /tmp/workers-types-latest && \
  npm pack @cloudflare/workers-types --pack-destination /tmp/workers-types-latest && \
  tar -xzf /tmp/workers-types-latest/cloudflare-workers-types-*.tgz -C /tmp/workers-types-latest
# Types at /tmp/workers-types-latest/package/index.d.ts

Reference Documentation

• references/rules.md — all best practice rules with code examples and anti-patterns
• references/review.md — type validation, config validation, binding access patterns, review process

Rules Quick Reference

Configuration

Request & Response Handling

Architecture

Observability

Code Patterns

Security

Anti-Patterns to Flag

Review Workflow

1. Retrieve — fetch latest best practices page, workers types, and wrangler schema
2. Read full files — not just diffs; context matters for binding access patterns
3. Check types — binding access, handler signatures, no any, no unsafe casts (see references/review.md)
4. Check config — compatibility_date, nodejs_compat, observability, secrets, binding-code consistency
5. Check patterns — streaming, floating promises, global state, serialization boundaries
6. Check security — crypto usage, secret handling, timing-safe comparisons, error handling
7. Validate with tools — npx tsc --noEmit, lint for no-floating-promises
8. Reference rules — see references/rules.md for each rule's correct pattern

Scope

This skill covers Workers-specific best practices and code review. For related topics:

• Durable Objects: load the durable-objects skill
• Workflows: see Rules of Workflows
• Wrangler CLI commands: load the wrangler skill

Principles

• Be certain. Retrieve before flagging. If unsure about an API, config field, or pattern, fetch the docs first.
• Provide evidence. Reference line numbers, tool output, or docs links.
• Focus on what developers will copy. Workers code in examples and docs gets pasted into production.
• Correctness over completeness. A concise example that works beats a comprehensive one with errors.

Wrangler CLI

Your knowledge of Wrangler CLI flags, config fields, and subcommands may be outdated. Prefer retrieval over pre-training for any Wrangler task.

Retrieval Sources

Fetch the latest information before writing or reviewing Wrangler commands and config. Do not rely on baked-in knowledge for CLI flags, config fields, or binding shapes.

FIRST: Check if Wrangler is installed, and if not, install it

Check if Wrangler is installed by running:

wrangler --version  # Requires v4.x+

If Wrangler is not installed, you should install it by running:

npm install -D wrangler@latest

Wherever possible, you should use Wrangler instead of manually constructing API requests.

Key Guidelines

• Use wrangler.jsonc: Prefer JSON config over TOML. Newer features are JSON-only.
• Set compatibility_date: Use a recent date (within 30 days). Check https://developers.cloudflare.com/workers/configuration/compatibility-dates/
• Generate types after config changes: Run wrangler types to update TypeScript bindings.
• Local dev defaults to local storage: Bindings use local simulation unless remote: true.
• Profile Worker startup: Run wrangler check startup to measure startup time and detect scripts that exceed the startup time limit.
• Use environments for staging/prod: Define env.staging and env.production in config.

Quick Start: New Worker

# Initialize new project
npx wrangler init my-worker

# Or with a framework
npx create-cloudflare@latest my-app

Quick Reference: Core Commands

Configuration (wrangler.jsonc)

Minimal Config

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_date": "2026-01-01"
}

Full Config with Bindings

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_date": "2026-01-01",
  "compatibility_flags": ["nodejs_compat"],

  // Environment variables
  "vars": {
    "ENVIRONMENT": "production"
  },

  // KV Namespace
  "kv_namespaces": [
    { "binding": "KV", "id": "<KV_NAMESPACE_ID>" }
  ],

  // R2 Bucket
  "r2_buckets": [
    { "binding": "BUCKET", "bucket_name": "my-bucket" }
  ],

  // D1 Database
  "d1_databases": [
    { "binding": "DB", "database_name": "my-db", "database_id": "<DB_ID>" }
  ],

  // Workers AI (always remote)
  "ai": { "binding": "AI" },

  // Vectorize
  "vectorize": [
    { "binding": "VECTOR_INDEX", "index_name": "my-index" }
  ],

  // Hyperdrive
  "hyperdrive": [
    { "binding": "HYPERDRIVE", "id": "<HYPERDRIVE_ID>" }
  ],

  // Durable Objects
  "durable_objects": {
    "bindings": [
      { "name": "COUNTER", "class_name": "Counter" }
    ]
  },

  // Cron triggers
  "triggers": {
    "crons": ["0 * * * *"]
  },

  // Environments
  "env": {
    "staging": {
      "name": "my-worker-staging",
      "vars": { "ENVIRONMENT": "staging" }
    }
  }
}

Generate Types from Config

# Generate worker-configuration.d.ts
wrangler types

# Custom output path
wrangler types ./src/env.d.ts

# Check types are up to date (CI)
wrangler types --check

Local Development

Start Dev Server

# Local mode (default) - uses local storage simulation
wrangler dev

# With specific environment
wrangler dev --env staging

# Force local-only (disable remote bindings)
wrangler dev --local

# Remote mode - runs on Cloudflare edge (legacy)
wrangler dev --remote

# Custom port
wrangler dev --port 8787

# Live reload for HTML changes
wrangler dev --live-reload

# Test scheduled/cron handlers
wrangler dev --test-scheduled
# Then visit: http://localhost:8787/__scheduled

Remote Bindings for Local Dev

Use remote: true in binding config to connect to real resources while running locally:

{
  "r2_buckets": [
    { "binding": "BUCKET", "bucket_name": "my-bucket", "remote": true }
  ],
  "ai": { "binding": "AI", "remote": true },
  "vectorize": [
    { "binding": "INDEX", "index_name": "my-index", "remote": true }
  ]
}

Recommended remote bindings: AI (required), Vectorize, Browser Rendering, mTLS, Images.

Local Secrets

Create .dev.vars for local development secrets:

API_KEY=local-dev-key
DATABASE_URL=postgres://localhost:5432/dev

Deployment

Deploy Worker

# Deploy to production
wrangler deploy

# Deploy specific environment
wrangler deploy --env staging

# Dry run (validate without deploying)
wrangler deploy --dry-run

# Keep dashboard-set variables
wrangler deploy --keep-vars

# Minify code
wrangler deploy --minify

Manage Secrets

Security: Never pass secret values as command arguments or pipe them via echo. Use the interactive prompt (preferred), pipe from a file, or use secret bulk. Never output, log, or hardcode secret values in commands.

# Set secret — interactive prompt (preferred, wrangler will ask for the value securely)
wrangler secret put API_KEY

# Set secret from a file (useful for PEM keys, CI environments)
wrangler secret put PRIVATE_KEY < path/to/private-key.pem

# List secrets
wrangler secret list

# Delete secret
wrangler secret delete API_KEY

# Bulk secrets from JSON file (do not commit this file to version control)
wrangler secret bulk secrets.json

Versions and Rollback

# List recent versions
wrangler versions list

# View specific version
wrangler versions view <VERSION_ID>

# Rollback to previous version
wrangler rollback

# Rollback to specific version
wrangler rollback <VERSION_ID>

KV (Key-Value Store)

Manage Namespaces

# Create namespace
wrangler kv namespace create MY_KV

# List namespaces
wrangler kv namespace list

# Delete namespace
wrangler kv namespace delete --namespace-id <ID>

Manage Keys

# Put value
wrangler kv key put --namespace-id <ID> "key" "value"

# Put with expiration (seconds)
wrangler kv key put --namespace-id <ID> "key" "value" --expiration-ttl 3600

# Get value
wrangler kv key get --namespace-id <ID> "key"

# List keys
wrangler kv key list --namespace-id <ID>

# Delete key
wrangler kv key delete --namespace-id <ID> "key"

# Bulk put from JSON
wrangler kv bulk put --namespace-id <ID> data.json

Config Binding

{
  "kv_namespaces": [
    { "binding": "CACHE", "id": "<NAMESPACE_ID>" }
  ]
}

R2 (Object Storage)

Manage Buckets

# Create bucket
wrangler r2 bucket create my-bucket

# Create with location hint
wrangler r2 bucket create my-bucket --location wnam

# List buckets
wrangler r2 bucket list

# Get bucket info
wrangler r2 bucket info my-bucket

# Delete bucket
wrangler r2 bucket delete my-bucket

Manage Objects

# Upload object
wrangler r2 object put my-bucket/path/file.txt --file ./local-file.txt

# Download object
wrangler r2 object get my-bucket/path/file.txt

# Delete object
wrangler r2 object delete my-bucket/path/file.txt

Config Binding

{
  "r2_buckets": [
    { "binding": "ASSETS", "bucket_name": "my-bucket" }
  ]
}

D1 (SQL Database)

Manage Databases

# Create database
wrangler d1 create my-database

# Create with location
wrangler d1 create my-database --location wnam

# List databases
wrangler d1 list

# Get database info
wrangler d1 info my-database

# Delete database
wrangler d1 delete my-database

Execute SQL

# Execute SQL command (remote)
wrangler d1 execute my-database --remote --command "SELECT * FROM users"

# Execute SQL file (remote)
wrangler d1 execute my-database --remote --file ./schema.sql

# Execute locally
wrangler d1 execute my-database --local --command "SELECT * FROM users"

Migrations

# Create migration
wrangler d1 migrations create my-database create_users_table

# List pending migrations
wrangler d1 migrations list my-database --local

# Apply migrations locally
wrangler d1 migrations apply my-database --local

# Apply migrations to remote
wrangler d1 migrations apply my-database --remote

Export/Backup

# Export schema and data
wrangler d1 export my-database --remote --output backup.sql

# Export schema only
wrangler d1 export my-database --remote --output schema.sql --no-data

Config Binding

{
  "d1_databases": [
    {
      "binding": "DB",
      "database_name": "my-database",
      "database_id": "<DATABASE_ID>",
      "migrations_dir": "./migrations"
    }
  ]
}

Vectorize (Vector Database)

Manage Indexes

# Create index with dimensions
wrangler vectorize create my-index --dimensions 768 --metric cosine

# Create with preset (auto-configures dimensions/metric)
wrangler vectorize create my-index --preset @cf/baai/bge-base-en-v1.5

# List indexes
wrangler vectorize list

# Get index info
wrangler vectorize get my-index

# Delete index
wrangler vectorize delete my-index

Manage Vectors

# Insert vectors from NDJSON file
wrangler vectorize insert my-index --file vectors.ndjson

# Query vectors
wrangler vectorize query my-index --vector "[0.1, 0.2, ...]" --top-k 10

Config Binding

{
  "vectorize": [
    { "binding": "SEARCH_INDEX", "index_name": "my-index" }
  ]
}

Hyperdrive (Database Accelerator)

Manage Configs

# Create config
wrangler hyperdrive create my-hyperdrive \
  --origin-host db.example.com \
  --origin-port 5432 \
  --database my-database \
  --origin-user db-user \
  --origin-password "$DB_PASSWORD"

# Or using a connection string from an environment variable
wrangler hyperdrive create my-hyperdrive \
  --connection-string "$HYPERDRIVE_CONNECTION_STRING"

# List configs
wrangler hyperdrive list

# Get config details
wrangler hyperdrive get <HYPERDRIVE_ID>

# Update config
wrangler hyperdrive update <HYPERDRIVE_ID> \
  --origin-password "$DB_PASSWORD"

# Delete config
wrangler hyperdrive delete <HYPERDRIVE_ID>

Config Binding

{
  "compatibility_flags": ["nodejs_compat"],
  "hyperdrive": [
    { "binding": "HYPERDRIVE", "id": "<HYPERDRIVE_ID>" }
  ]
}

Workers AI

List Models

# List available models
wrangler ai models

# List finetunes
wrangler ai finetune list

Config Binding

{
  "ai": { "binding": "AI" }
}

Note: Workers AI always runs remotely and incurs usage charges even in local dev.

Queues

Manage Queues

# Create queue
wrangler queues create my-queue

# List queues
wrangler queues list

# Delete queue
wrangler queues delete my-queue

# Add consumer to queue
wrangler queues consumer add my-queue my-worker

# Remove consumer
wrangler queues consumer remove my-queue my-worker

Config Binding

{
  "queues": {
    "producers": [
      { "binding": "MY_QUEUE", "queue": "my-queue" }
    ],
    "consumers": [
      {
        "queue": "my-queue",
        "max_batch_size": 10,
        "max_batch_timeout": 30
      }
    ]
  }
}

Containers

Build and Push Images

# Build container image
wrangler containers build -t my-app:latest .

# Build and push in one command
wrangler containers build -t my-app:latest . --push

# Push existing image to Cloudflare registry
wrangler containers push my-app:latest

Manage Containers

# List containers
wrangler containers list

# Get container info
wrangler containers info <CONTAINER_ID>

# Delete container
wrangler containers delete <CONTAINER_ID>

Manage Images

# List images in registry
wrangler containers images list

# Delete image
wrangler containers images delete my-app:latest

Manage External Registries

Security: Never hardcode registry credentials in commands. Use environment variables.

# List configured registries
wrangler containers registries list

# Configure external registry (e.g., ECR)
wrangler containers registries configure <DOMAIN> \
  --aws-access-key-id "$AWS_ACCESS_KEY_ID"

# Configure DockerHub
wrangler containers registries configure <DOMAIN> \
  --dockerhub-username "$DOCKERHUB_USERNAME"

# Delete registry configuration
wrangler containers registries delete <DOMAIN>

Workflows

Manage Workflows

# List workflows
wrangler workflows list

# Describe workflow
wrangler workflows describe my-workflow

# Trigger workflow instance
wrangler workflows trigger my-workflow

# Trigger with parameters
wrangler workflows trigger my-workflow --params '{"key": "value"}'

# Delete workflow
wrangler workflows delete my-workflow

Manage Workflow Instances

# List instances
wrangler workflows instances list my-workflow

# Describe instance
wrangler workflows instances describe my-workflow <INSTANCE_ID>

# Terminate instance
wrangler workflows instances terminate my-workflow <INSTANCE_ID>

Config Binding

{
  "workflows": [
    {
      "binding": "MY_WORKFLOW",
      "name": "my-workflow",
      "class_name": "MyWorkflow"
    }
  ]
}

Pipelines

Manage Pipelines

# Create pipeline
wrangler pipelines create my-pipeline --r2 my-bucket

# List pipelines
wrangler pipelines list

# Show pipeline details
wrangler pipelines show my-pipeline

# Update pipeline
wrangler pipelines update my-pipeline --batch-max-mb 100

# Delete pipeline
wrangler pipelines delete my-pipeline

Config Binding

{
  "pipelines": [
    { "binding": "MY_PIPELINE", "pipeline": "my-pipeline" }
  ]
}

Secrets Store

Manage Stores

# Create store
wrangler secrets-store store create my-store

# List stores
wrangler secrets-store store list

# Delete store
wrangler secrets-store store delete <STORE_ID>

Manage Secrets in Store

# Add secret to store
wrangler secrets-store secret put <STORE_ID> my-secret

# List secrets in store
wrangler secrets-store secret list <STORE_ID>

# Get secret
wrangler secrets-store secret get <STORE_ID> my-secret

# Delete secret from store
wrangler secrets-store secret delete <STORE_ID> my-secret

Config Binding

{
  "secrets_store_secrets": [
    {
      "binding": "MY_SECRET",
      "store_id": "<STORE_ID>",
      "secret_name": "my-secret"
    }
  ]
}

Pages (Frontend Deployment)

# Create Pages project
wrangler pages project create my-site

# Deploy directory to Pages
wrangler pages deploy ./dist

# Deploy with specific branch
wrangler pages deploy ./dist --branch main

# List deployments
wrangler pages deployment list --project-name my-site

Observability

Tail Logs

# Stream live logs
wrangler tail

# Tail specific Worker
wrangler tail my-worker

# Filter by status
wrangler tail --status error

# Filter by search term
wrangler tail --search "error"

# JSON output
wrangler tail --format json

Config Logging

{
  "observability": {
    "enabled": true,
    "head_sampling_rate": 1
  }
}

Testing

Local Testing with Vitest

npm install -D @cloudflare/vitest-pool-workers vitest

vitest.config.ts:

import { defineWorkersConfig } from "@cloudflare/vitest-pool-workers/config";

export default defineWorkersConfig({
  test: {
    poolOptions: {
      workers: {
        wrangler: { configPath: "./wrangler.jsonc" },
      },
    },
  },
});

Test Scheduled Events

# Enable in dev
wrangler dev --test-scheduled

# Trigger via HTTP
curl http://localhost:8787/__scheduled

Troubleshooting

Common Issues

Debug Commands

# Check auth status
wrangler whoami

# Profile Worker startup time
wrangler check startup

# View config schema
wrangler docs configuration

Best Practices

1. Version control wrangler.jsonc: Treat as source of truth for Worker config.
2. Use automatic provisioning: Omit resource IDs for auto-creation on deploy.
3. Run wrangler types in CI: Add to build step to catch binding mismatches.
4. Use environments: Separate staging/production with env.staging, env.production.
5. Set compatibility_date: Update quarterly to get new runtime features.
6. Use .dev.vars for local secrets: Never commit secrets to config.
7. Test locally first: wrangler dev with local bindings before deploying.
8. Use --dry-run before major deploys: Validate changes without deployment.
9. Never embed secrets in commands: Use interactive prompts (wrangler secret put), file-based input (wrangler secret bulk), or secure CI environment variables. Never echo, log, or pass secret values as CLI arguments.

CLI for agents

Human-oriented CLIs often block agents: interactive prompts, huge upfront docs, and help text without copy-pasteable examples. Prefer patterns that work headlessly and compose in pipelines.

Non-interactive first

• Every input should be expressible as a flag or flag value. Do not require arrow keys, menus, or timed prompts.
• If flags are missing, then fall back to interactive mode—not the other way around.

Bad: mycli deploy → ? Which environment? (use arrow keys)
Good: mycli deploy --env staging

Discoverability without dumping context

• Agents discover subcommands incrementally: mycli, then mycli deploy --help. Do not print the entire manual on every run.
• Let each subcommand own its documentation so unused commands stay out of context.

--help that works

• Every subcommand has --help.
• Every --help includes Examples with real invocations. Examples do more than prose for pattern-matching.

Options:
  --env     Target environment (staging, production)
  --tag     Image tag (default: latest)
  --force   Skip confirmation

Examples:
  mycli deploy --env staging
  mycli deploy --env production --tag v1.2.3
  mycli deploy --env staging --force

stdin, flags, and pipelines

• Accept stdin where it makes sense (e.g. cat config.json | mycli config import --stdin).
• Avoid odd positional ordering and avoid falling back to interactive prompts for missing values.
• Support chaining: mycli deploy --env staging --tag $(mycli build --output tag-only).

Fail fast with actionable errors

• On missing required flags: exit immediately with a clear message and a correct example invocation, not a hang.

Error: No image tag specified.
  mycli deploy --env staging --tag <image-tag>
  Available tags: mycli build list --output tags

Idempotency

• Agents retry often. The same successful command run twice should be safe (no-op or explicit "already done"), not duplicate side effects.

Destructive actions

• Add --dry-run (or equivalent) so agents can preview plans before committing.
• Offer --yes / --force to skip confirmations while keeping the safe default for humans.

Predictable structure

• Use a consistent pattern everywhere, e.g. resource + verb: if mycli service list exists, mycli deploy list and mycli config list should follow the same shape.

Success output

• On success, return machine-useful data: IDs, URLs, durations. Plain text is fine; avoid relying on decorative output alone.

deployed v1.2.3 to staging
url: https://staging.myapp.com
deploy_id: dep_abc123
duration: 34s

When reviewing an existing CLI

• Check: non-interactive path, layered help, examples on --help, stdin/pipeline story, error messages with invocations, idempotency, dry-run, confirmation bypass flags, consistent command structure, structured success output.

Continual Learning

Keep AGENTS.md current by delegating the memory update flow to one subagent.

Trigger

Use when the user asks to mine prior chats, maintain AGENTS.md, or run the continual-learning loop.

Workflow

1. Call agents-memory-updater.
2. Return the updater result.

Guardrails

• Keep the parent skill orchestration-only.
• Do not mine transcripts or edit files in the parent flow.
• Do not bypass the subagent.

Create plugin scaffold

Trigger

You need to create a new Cursor plugin from scratch and make it ready for local use or marketplace submission.

Required Inputs

• Plugin name (lowercase kebab-case)
• Plugin purpose and target users
• Component set to include (rules, skills, agents, commands, hooks, mcpServers)
• Repository style (single-plugin or multi-plugin marketplace)

Output Location

By default, create the plugin inside the user's local plugin directory:

~/.cursor/plugins/local/<plugin-name>/

This path makes the plugin immediately available to Cursor without any install step. If the user explicitly asks to create the plugin elsewhere (e.g. inside an existing repo or a specific directory), respect that choice instead.

Workflow

1. Validate plugin name format: lowercase kebab-case, starts and ends with an alphanumeric character.
2. Determine the target directory:
   • Default: ~/.cursor/plugins/local/<plugin-name>/
   • Override: use the path the user specifies, if any.
   • Create the directory (and parents) if it does not exist.
3. Create base files inside the target directory:
   • .cursor-plugin/plugin.json
   • README.md
   • LICENSE
   • optional CHANGELOG.md
4. Populate plugin.json:
   • Required: name
   • Recommended: version, description, author, license, keywords
   • Add explicit component paths only when non-default discovery is needed.
5. Create component files with valid frontmatter:
   • Rules: .mdc with description, alwaysApply, optional globs
   • Skills: skills/<skill-name>/SKILL.md with name, description
   • Agents: agents/*.md with name, description
   • Commands: commands/*.(md|txt) with name, description
6. If repository uses .cursor-plugin/marketplace.json, add plugin entry:
   • name
   • source
   • optional metadata (description, keywords, category, tags)
7. Ensure all manifest paths are relative, valid, and do not use absolute paths or parent traversal.

Guardrails

• Keep the plugin focused on one use case.
• Prefer concise, actionable skill and rule text over long prose.
• Do not reference files that do not exist.
• Use folder discovery defaults unless custom paths are required.
• Always save to ~/.cursor/plugins/local/<plugin-name>/ unless the user provides a different path.

Output

• Created file tree for the plugin (with full path to the output directory)
• Final plugin.json
• Marketplace entry (if applicable)
• Short validation report of required fields and component metadata
• Confirmation that the plugin is saved under ~/.cursor/plugins/local/ and ready for use

Review plugin submission

Trigger

A plugin is implemented and needs a final quality check before submission or release.

Workflow

1. Verify manifest validity:
   • .cursor-plugin/plugin.json exists
   • name is valid lowercase kebab-case
   • metadata fields are coherent (description, version, author, license)
2. Verify component discoverability:
   • Skills in skills/*/SKILL.md
   • Rules in rules/ as .mdc or markdown variants
   • Agents in agents/ markdown files
   • Commands in commands/ markdown or text files
   • Hooks in hooks/hooks.json
   • MCP config in mcp.json (or mcpServers override)
3. Verify component metadata:
   • Skills include name and description frontmatter
   • Rules include valid frontmatter and clear guidance
   • Agents and commands include name and description
4. Verify repository integration:
   • For marketplace repos, plugin entry exists in .cursor-plugin/marketplace.json
   • source resolves to plugin directory and names are unique
5. Verify documentation quality:
   • README.md states purpose, installation, and component coverage
   • optional logo path is valid and repository-hosted

Checklist

• Manifest exists and parses as valid JSON
• All declared paths exist and are relative
• No broken file references
• No missing frontmatter on skills/rules/agents/commands
• Plugin scope is clear and focused
• Marketplace registration complete (if multi-plugin repo)

Output

• Pass/fail report by section
• Prioritized fix list
• Final submission recommendation

Check compiler errors

Trigger

Compile or type-check failures are blocking local validation or CI.

Workflow

1. Run the repo's compile and type-check commands.
2. Summarize errors by file and type.
3. Fix the highest-confidence issues first.
4. Re-run checks until clean or blocked.

Output

• Current compile and type-check status
• Error summary grouped by file and category
• Fixes applied and remaining blockers

Control CLI

Use a repeatable local harness to exercise an interactive CLI instead of poking at it manually. First reuse the repo's own test/demo harness if it exists; otherwise assemble a temporary harness from standard local tools.

What It Is Used For

• Reproducing CLI/TUI bugs with deterministic input.
• Verifying keyboard flows, prompts, interrupts, resize behavior, and terminal layout.
• Capturing before/after transcripts for bug fixes.
• Profiling startup time, slow operations, hangs, or memory growth.
• Recording a short terminal demo when output is easier to show than explain.

Harness Loop

1. Identify the command under test and the smallest reproducible workspace.
2. Discover existing local harnesses: package scripts, e2e tests, demo recorders, expect scripts, or PTY helpers.
3. If no harness exists, launch the CLI in an isolated terminal session with deterministic env vars.
4. Capture the current screen before interacting.
5. Send one action at a time: text, Enter, arrows, Escape, Ctrl-C, resize.
6. Wait for a concrete screen pattern or prompt before the next action.
7. Save the transcript and any profile artifacts.
8. Kill the session cleanly.

Harness Options

• Repo-native harness: prefer checked-in scripts because they know the app's startup, env, and prompts.
• tmux: managed sessions, capture-pane, send-keys, attach/detach.
• PTY probe: use a short Python, Node, or Expect script when tmux is unavailable.
• Runtime inspector: use Node or Bun inspector for CPU profiles, heap snapshots, and live evaluation.
• Terminal recorder: use repo-local demo tools or asciinema-compatible tools when the user asks for a demo.

Minimal tmux Harness

SESSION="cli-harness-$(date +%s)"
tmux new-session -d -s "$SESSION" -- <command-under-test>
tmux capture-pane -pt "$SESSION"
tmux send-keys -t "$SESSION" "help" Enter
tmux capture-pane -pt "$SESSION"
tmux kill-session -t "$SESSION"

For Node CLIs:

NODE_OPTIONS="--inspect=127.0.0.1:0" tmux new-session -d -s "$SESSION" -- <node-cli-command>

Read the terminal output to find the inspector URL, then use Chrome DevTools-compatible tooling if profiling is needed.

Minimal PTY Harness

Use a PTY script when you need deterministic waits in a repo that does not have tmux or a demo harness. Keep it temporary unless the user asks to add a reusable test.

import os
import pty
import select
import subprocess
import time

master_fd, slave_fd = pty.openpty()
proc = subprocess.Popen(
    ["<command>", "<arg>"],
    stdin=slave_fd,
    stdout=slave_fd,
    stderr=slave_fd,
    close_fds=True,
)
os.close(slave_fd)

deadline = time.time() + 30
buffer = b""
while time.time() < deadline:
    ready, _, _ = select.select([master_fd], [], [], 0.25)
    if not ready:
        continue
    chunk = os.read(master_fd, 4096)
    buffer += chunk
    if b"<ready text>" in buffer:
        os.write(master_fd, b"help\n")
        break

print(buffer.decode(errors="replace"))
proc.terminate()
os.close(master_fd)

If the CLI needs richer terminal control, use pty.fork() or an existing PTY library.

Profiling Recipes

• Startup regression: capture baseline and treatment startup timings under the same machine, env, and command.
• Slow operation: start a CPU profile, perform the operation, stop the profile, and compare top self-time functions.
• Memory leak: force GC if available, take a heap snapshot, perform the operation repeatedly, force GC again, and take another snapshot.
• Hang: capture the screen, active handles/resources, and a stack/CPU sample before interrupting.

Guardrails

• Prefer deterministic waits over sleeps. If you must sleep, explain why.
• Do not send credentials or destructive commands into a controlled session.
• Keep the harness in /tmp unless the repo already has a testing/demo harness.
• Do not hard-code paths from another repository. Adapt commands to the current repo's scripts and runtime.
• Clean up tmux sessions, temp dirs, inspector processes, and demo artifacts unless the user asks to keep them.

Control UI

Use local browser automation to verify UI behavior with evidence. First reuse the repo's own Playwright, browser, or Electron harness if it exists; otherwise assemble a temporary local harness around the app's dev server or Chromium debug port.

What It Is Used For

• Reproducing UI bugs that depend on real browser focus, keyboard input, scrolling, resizing, or rendering.
• Verifying visual or accessibility changes with screenshots and snapshots.
• Checking local web, IDE, or Electron behavior before shipping.
• Capturing console logs, network logs, CPU profiles, traces, or heap snapshots.
• Creating before/after evidence for verify-this.

Setup Pattern

1. Start the app locally using the repo's documented dev command.
2. Discover existing local harnesses: Playwright tests, Cypress specs, Storybook, browser scripts, Electron launch scripts, or snapshot tools.
3. For a web app, connect to the local URL with the existing browser tooling.
4. For Electron/Chromium, enable a remote debugging port when supported.
5. Select the correct page by stable app markers, not by tab order alone.
6. Prefer accessibility roles, labels, and stable data-* selectors over coordinates.

Generic Web Harness

Use the repo's installed browser tooling when possible. If the repo already has Playwright, a minimal one-off probe looks like:

import { chromium } from "playwright";

const browser = await chromium.launch();
const page = await browser.newPage({ viewport: { width: 1280, height: 800 } });
await page.goto("http://127.0.0.1:<port>");
await page.getByRole("button", { name: /submit/i }).click();
await page.screenshot({ path: "/tmp/ui-harness-after.png", fullPage: true });
await browser.close();

Do not add Playwright as a project dependency just for this probe unless the user asks. Prefer existing dev dependencies or external browser tools already available in the environment.

Generic CDP Harness

For Electron or a Chromium app launched with --remote-debugging-port=<port>, connect over CDP:

import { chromium } from "playwright";

const browser = await chromium.connectOverCDP("http://127.0.0.1:<debug-port>");
const pages = browser.contexts().flatMap((context) => context.pages());
let page;
for (const candidate of pages) {
  if (await candidate.locator("<app-root-selector>").count()) {
    page = candidate;
    break;
  }
}

if (!page) {
  console.log(await Promise.all(pages.map(async (p) => ({
    title: await p.title(),
    url: p.url(),
  }))));
  throw new Error("No matching app page found");
}

await page.screenshot({ path: "/tmp/ui-harness-cdp.png", fullPage: true });
await browser.close();

Replace <app-root-selector> with a stable marker from the current repo, such as a root app node, landmark, or product-specific data-* attribute.

Interaction Loop

1. Capture a page snapshot or screenshot before acting.
2. Choose a target from the latest page structure.
3. Perform exactly one structural action: click, type, keypress, drag, scroll, navigate, or resize.
4. Capture a fresh snapshot/screenshot.
5. Verify the expected state change.
6. Save artifacts for before/after comparisons when the user asked for proof.

CDP Capabilities

Use raw CDP only when higher-level browser APIs are insufficient:

• Performance: CPU profiles, traces, paint flashing, FPS meter, layout shift inspection.
• Memory: heap snapshots and forced GC for leak investigations.
• Network: request blocking, throttling, cache disablement, request/response logs.
• Rendering: viewport changes, color scheme emulation, reduced motion, accessibility checks.
• Debugging: console streaming, exception capture, DOM snapshots.

Page Selection

When multiple app windows/tabs share a debug port:

• Prefer a positive marker for the surface under test, such as an app root selector.
• Use a negative marker to avoid the wrong surface when necessary.
• If no page matches, list available page titles and URLs instead of guessing.

Guardrails

• Do not rely on stale element references after navigation or structural changes.
• Avoid coordinate clicks unless a fresh screenshot was captured immediately before the click.
• Keep test data local and disposable.
• Do not store screenshots or heap snapshots from privacy-sensitive workspaces unless the user explicitly agrees.
• Do not hard-code selectors, ports, or script paths from another repository. Discover the current repo's local app markers.
• Clean up dev servers, debug sessions, and temp profiles when done.

Remove AI code slop

Check the diff against main and remove AI-generated slop introduced in the branch.

Focus Areas

• Extra comments that are unnecessary or inconsistent with local style
• Defensive checks or try/catch blocks that are abnormal for trusted code paths
• Casts to any used only to bypass type issues
• Deeply nested code that should be simplified with early returns
• Other patterns inconsistent with the file and surrounding codebase

Guardrails

• Keep behavior unchanged unless fixing a clear bug.
• Prefer minimal, focused edits over broad rewrites.
• Keep the final summary concise (1-3 sentences).

Fix CI

Trigger

Branch or PR CI is failing and needs a fast, iterative path to green checks.

Workflow

1. Resolve the active PR and inspect gh pr checks --json name,bucket,state,workflow,link.
2. Inspect failed jobs and extract the first actionable error. Use GitHub Actions logs when available; otherwise use the check link to identify the failing command or service.
3. Apply the smallest safe fix.
4. Push, re-check the PR check set, and repeat until green.

Guardrails

• Fix one actionable failure at a time.
• Prefer minimal, low-risk changes before broader refactors.
• Keep gh pr checks as the source of truth for overall PR CI state.

Output

• Primary failing job and root error
• Fixes applied in iteration order
• Current CI status and next action

Fix merge conflicts

Trigger

Branch has unresolved merge conflicts and needs a reliable path to a buildable state.

Workflow

1. Detect all conflicting files from git status and conflict markers.
2. Resolve each conflict with minimal, correctness-first edits.
3. Prefer preserving both sides when safe. Otherwise, choose the variant that compiles and keeps public behavior stable.
4. Regenerate lockfiles with package manager tools instead of hand-editing.
5. Run compile, lint, and relevant tests.
6. Stage resolved files and summarize key decisions.

Guardrails

• Keep changes minimal and readable.
• Do not leave conflict markers in any file.
• Avoid broad refactors while resolving conflicts.
• Do not push or tag during conflict resolution.

Output

• Files resolved
• Notable resolution choices
• Build/test outcome

Get PR comments

Trigger

Need a concise, actionable summary of feedback on the active pull request.

Workflow

1. Resolve the active PR for the current branch.
2. Fetch review comments and discussion comments.
3. Group feedback by severity and actionability.
4. Return a concise action list.

Output

• Grouped feedback summary
• Action list ordered by priority
• Open questions that still need clarification

Loop on CI

Trigger

Need to watch a branch or pull request and iterate on CI failures until all required checks are green.

Use gh pr checks as the source of truth. It includes all PR-attached checks, while gh run list only covers GitHub Actions.

Workflow

1. Resolve the PR for the current branch.
2. Inspect current PR checks before waiting.
3. If checks already failed, diagnose those failures first.
4. If checks are pending, watch with gh pr checks --watch --fail-fast.
5. After each push, re-check the full PR check set and repeat until green.

Commands

# Resolve the active PR
gh pr view --json number,url,headRefName

# Inspect all attached checks
gh pr checks --json name,bucket,state,workflow,link

# Watch pending checks and fail fast
gh pr checks --watch --fail-fast

# GitHub Actions logs, when the failing check links to a GHA run
gh run view <run-id> --log-failed

Guardrails

• Keep each fix scoped to a single failure cause when possible.
• Do not bypass hooks (--no-verify) to force progress.
• If the failure is clearly unrelated to the PR and appears fixed on main, merge latest main instead of bloating the PR with unrelated fixes.
• If failures are flaky, retry once and report flake evidence.
• Re-run gh pr checks --json name,bucket,state,workflow,link after every push; the check set can change.

Output

• Current CI status
• Failure summary and fixes applied
• PR URL once checks are green

Make PR Easy to Review

Prepare a PR so a reviewer can quickly understand the intent, important files, and risk. The default goal is reviewability without behavior changes.

Workflow

1. Resolve the target PR from the user-provided URL or current branch.
2. Inspect commits, diff size, changed paths, generated files, and PR description.
3. Identify reviewability issues: noisy commits, stale description, unrelated changes, mixed mechanical and logic changes, missing tests, or unclear reviewer entry points.
4. Propose a plan before rewriting history or force-pushing.
5. Apply safe improvements, then verify the tree or diff still matches the intended code.

History Cleanup

Only rewrite history when the user asks for it or agrees to the plan. Before rewriting:

gh pr view <PR> --json title,headRefName,baseRefName,state,commits
git fetch origin <headRefName> <baseRefName>
ORIGINAL_TREE=$(git rev-parse origin/<headRefName>^{tree})

Good commit groupings usually follow dependency order:

1. Schema/storage or generated API definitions.
2. Core logic.
3. Wiring and integration.
4. UI or surface behavior.
5. Tests.

After rewriting, verify content identity:

echo "Original tree: $ORIGINAL_TREE"
echo "Current tree:  $(git rev-parse HEAD^{tree})"
git diff origin/<headRefName> --stat

Do not push if the tree changed unintentionally.

Reviewer Guidance

When code behavior should stay untouched, prefer PR description and review notes:

• Add a TL;DR that matches the actual diff.
• Separate core files from generated or mechanical files.
• Call out risky behavior changes, migration order, rollout plan, and test coverage.
• Link issue trackers, dashboards, or design docs when they explain intent.

Guardrails

• Never hide meaningful behavior changes inside "cleanup".
• Do not bypass hooks unless the user explicitly asks.
• If the PR is too large to make reviewable with notes, recommend splitting instead of polishing around the problem.

New branch and PR

Trigger

Starting work that should be shipped through a clean branch and pull request workflow.

Workflow

1. Ensure the working tree is clean or explicitly handled.
2. Create a descriptive branch from the latest main.
3. Complete implementation and tests.
4. Commit focused changes and push.
5. Create a concise PR with summary and test notes.

Guardrails

• Keep branch scope focused on one change set.
• Include verification notes before requesting review.

Output

• New branch name
• PR summary and test notes
• PR URL

PR Review Canvas

Generate an interactive HTML review of a GitHub PR that reads like a peer walking you through what matters.

Workflow

1. Fetch PR data

Run these gh api calls in parallel:

gh api repos/{owner}/{repo}/pulls/{number} --jq '{title, body, user: .user.login, state, additions, deletions, changed_files, base: .base.ref, head: .head.ref}'
gh api repos/{owner}/{repo}/pulls/{number}/files --paginate --jq '.[] | {filename, status, additions, deletions, patch}'
gh api repos/{owner}/{repo}/pulls/{number}/comments --jq '.[] | {user: .user.login, body, path, line}'

2. Analyze the PR and write the body HTML

Read the diffs, understand the PR, and write the <body> content directly as HTML. You have full creative freedom -- the goal is to explain the PR clearly to a reviewer. Use whatever structure best fits the PR.

Typical structure (adapt as needed):

• Header with title, PR number, author, stats
• Summary box explaining what the PR does in plain English
• Core file sections with annotations and diffs
• Mechanical/boilerplate files collapsed by default
• Review checklist at the bottom

But you can also add:

• Pseudocode summaries for verbose code -- show the algorithm in plain English or short pseudocode, with the real diff collapsed below (use a .bp-section card labeled "Show full implementation"). Great when 150 lines of retry/backoff/error-handling code is really just "fetch with exponential backoff and circuit breaker."
• Diagrams (inline SVG, mermaid via CDN, ASCII art in <pre>)
• Flowcharts showing before/after control flow
• Tables comparing old vs new behavior
• Callout boxes for warnings, questions, or gotchas
• Interactive widgets if they help
• Anything else that makes the review clearer

Pseudocode pattern example:

<div class="file-card">
  <div class="file-hdr" onclick="toggle(this)">
    <span class="fname">retryClient.ts</span>
    <div class="fstats"><span class="pill add">+173</span><span class="pill del">&minus;11</span><span class="chev open">&#9654;</span></div>
  </div>
  <div class="file-body open">
    <div class="file-note">
      <strong>What this does in plain English:</strong>
      <pre style="margin-top:8px;color:var(--text);font-size:12px;line-height:1.6;">
fetch(url):
  if circuit breaker is open → fail fast
  retry up to N times:
    try fetch with timeout
    on success → close circuit breaker, return
    on retryable error → wait (exponential backoff + jitter)
    on non-retryable error → throw
  circuit breaker records failure</pre>
    </div>
    <div class="bp-section" style="margin:0;border:0;border-radius:0;">
      <div class="bp-hdr" onclick="toggleBP(this)">
        <span>Show full implementation (+173 lines)</span><span class="chev">&#9654;</span>
      </div>
      <div class="bp-body"><div data-diff="retryClient"></div></div>
    </div>
  </div>
</div>

3. Available CSS classes and JS utilities

Read styles.css and renderer.js from this skill directory. These give you a prebuilt dark-themed toolkit. Inject them into template.html verbatim.

CSS classes you can use:

JS functions available:

Rendering diffs -- use data-diff attributes with auto-discovery. Put <div data-diff="KEY"></div> placeholders in your body HTML wherever you want a diff rendered. The renderer finds them automatically after DOM load and fills them from the <script id="pr-diffs-json" type="application/json"> element in template.html.

CRITICAL: Patch strings can contain </script> in addition to newlines, backslashes, and quotes. Even json.dumps(...) is not enough if you paste raw output into executable <script> because HTML parsing can terminate the tag early. Never manually embed patch strings in JS/JSON. Instead, use this safe approach:

1. During the fetch step, save patches to a JSON file using jq (which handles escaping correctly):

gh api repos/{owner}/{repo}/pulls/{number}/files --paginate \
  --jq '[.[] | {key: (.filename | gsub("[^a-zA-Z0-9]"; "_")), value: (.patch // "")}] | from_entries' \
  > /tmp/pr-patches-{number}.json

2. During assembly, use Python to safely inject the JSON into template.html:

python3 <<'PY'
import json
from pathlib import Path

patches = json.loads(Path('/tmp/pr-patches-{number}.json').read_text())
html = Path('/tmp/pr-review-{number}-body.html').read_text()
css = Path('styles.css').read_text()
js = Path('renderer.js').read_text()
tmpl = Path('template.html').read_text()

# Prevent literal </script> from terminating HTML script tags early.
safe_json = json.dumps(patches).replace('<', '\\u003c').replace('>', '\\u003e').replace('&', '\\u0026')

out = (
  tmpl.replace('/* INJECT_CSS */', css)
      .replace('/* INJECT_JS */', js)
      .replace('<!-- INJECT_BODY -->', html)
      .replace('{"__PR_DIFFS_PLACEHOLDER__":true}', safe_json)
)

Path('/tmp/pr-review-{number}.html').write_text(out)
PY

This guarantees valid JSON and script-safe HTML embedding. The agent writes body HTML to a temp file, then Python assembles everything safely.

The diff data keys should match the data-diff attribute values in the HTML:

<div data-diff="path_to_file_ts"></div>

Since renderer.js loads in <head>, you can also call renderDiff(target, lines) directly from inline <script> tags if needed for custom use cases. The function accepts a DOM element, ID string, or CSS selector as target, and a string or array as lines.

You're not limited to these. Add your own inline <style> blocks, <script> blocks, SVGs, diagrams, or anything else. The prebuilt pieces save time but don't constrain you.

4. Assemble and serve

1. Write your body HTML (everything that goes inside <body>) to /tmp/pr-review-{number}-body.html

2. Save patches to /tmp/pr-patches-{number}.json using the jq command from step 3 above

3. Run the Python assembly script from step 3 above (reads styles.css, renderer.js, template.html from this skill directory, injects body + patches safely, writes final HTML)

4. Start a local server on a fixed port:

   cd /tmp && python3 -m http.server 8432 --bind 127.0.0.1
   

   Run this backgrounded, then navigate the in-app browser to http://127.0.0.1:8432/pr-review-{number}.html.

   Why a fixed port and cd /tmp: Background shells have no TTY, so Python buffers its startup message ("Serving HTTP on...") indefinitely — using port 0 means you can never read which port was chosen. And --directory /tmp works but cd /tmp is more robust across Python versions. If port 8432 is taken, try 8433, 8434, etc.

Diff features (handled automatically by renderer.js)

• Filters out import-only lines
• Collapses whitespace-only changes into context lines
• Detects moved code blocks (3+ consecutive lines deleted in one place and added identically elsewhere) -- renders in blue/purple instead of red/green
• Near-matches (moved + small edit) get a different purple tint

Style notes

• Dark theme: #1a1a1a background, Inter body font, IBM Plex Mono for code
• Use var(--warning) for orange, var(--success) for green, var(--danger) for red, var(--accent) for blue
• Sticky file headers (position: sticky; top: 0) and notes (top: 35px) pin while scrolling
• Core files expanded by default (.file-body.open), mechanical files collapsed

Review and ship

Trigger

Reviewing changes before shipping. Close key issues, verify behavior, and open or update a PR.

Workflow

1. Gather context: diff against base branch, uncommitted changes, recent commits, changed files, and user intent from recent relevant chats if useful.
2. Run targeted tests for changed behavior. If no focused tests exist, decide whether to add them or document the gap.
3. Review for correctness, regressions, security, and intent fit. Use parallel subagents for larger diffs.
4. Fix critical issues before finalizing and re-run affected tests.
5. Commit selective files with a concise message.
6. Push branch and open or update a PR.

Suggested Checks

git fetch origin main
git diff origin/main...HEAD
git status
gh pr checks --json name,bucket,state,workflow,link

Guardrails

• Prioritize correctness, security, and regressions over style-only comments.
• Keep commits focused and avoid unrelated file changes.
• If pre-commit checks fail, fix the issues rather than bypassing hooks.
• Use gh pr checks instead of GitHub Actions-only commands when judging PR readiness.

Output

• Findings summary (critical, warning, note)
• Tests run and outcomes
• PR URL

Run smoke tests

Trigger

Need end-to-end smoke verification before or after changes.

Workflow

1. Build prerequisites for the target app.
2. Run the relevant smoke suite or a focused test file.
3. If failing, inspect traces/logs and isolate the root cause.
4. Apply a minimal fix and rerun until stable.

Example Commands

# Run full smoke suite
npm run smoketest

# Run a specific smoke test file
npm run smoketest -- path/to/test.spec.ts

# Faster iteration when build artifacts are ready
npm run smoketest-no-compile -- path/to/test.spec.ts

Guardrails

• Prefer deterministic waits and assertions over brittle timeouts.
• Re-run passing fixes to reduce flaky false positives.
• Quarantine tests only when explicitly requested and documented.

Output

• Test results summary
• Root cause and fix
• Remaining flake risk (if any)

Thermo-Nuclear Code Quality Review

Use this skill for an unusually strict review focused on implementation quality, maintainability, abstraction quality, and codebase health.

Above all, this skill should push the reviewer to be ambitious about code structure. Do not merely identify local cleanup opportunities. Actively search for "code judo" moves: restructurings that preserve behavior while making the implementation dramatically simpler, smaller, more direct, and more elegant.

Core Prompt

Start from this baseline:

Perform a deep code quality audit of the current branch's changes. Rethink how to structure / implement the changes to meaningfully improve code quality without impacting behavior. Work to improve abstractions, modularity, reduce Spaghetti code, improve succinctness and legibility. Be ambitious, if there is a clear path to improving the implementation that involves restructuring some of the codebase, go for it. Be extremely thorough and rigorous. Measure twice, cut once.

Non-Negotiable Additional Standards

Apply the baseline prompt above, plus these explicit review rules:

0. Be ambitious about structural simplification.

   • Do not stop at "this could be a bit cleaner."
   • Look for opportunities to reframe the change so that whole branches, helpers, modes, conditionals, or layers disappear entirely.
   • Prefer the solution that makes the code feel inevitable in hindsight.
   • Assume there is often a "code judo" move available: a re-organization that uses the existing architecture more effectively and makes the change dramatically simpler and more elegant.
   • If you see a path to delete complexity rather than rearrange it, push hard for that path.

1. Do not let a PR push a file from under 1k lines to over 1k lines without a very strong reason.

   • Treat this as a strong code-quality smell by default.
   • Prefer extracting helpers, subcomponents, modules, or local abstractions instead of letting a file sprawl past 1000 lines.
   • If the diff crosses that threshold, explicitly ask whether the code should be decomposed first.
   • Only waive this if there is a compelling structural reason and the resulting file is still clearly organized.

2. Do not allow random spaghetti growth in existing code.

   • Be highly suspicious of new ad-hoc conditionals, scattered special cases, or one-off branches inserted into unrelated flows.
   • If a change adds "weird if statements in random places", treat that as a design problem, not a stylistic nit.
   • Prefer pushing the logic into a dedicated abstraction, helper, state machine, policy object, or separate module instead of tangling an existing path.
   • Call out changes that make the surrounding code harder to reason about, even if they technically work.

3. Bias toward cleaning the design, not just accepting working code.

   • If behavior can stay the same while the structure becomes meaningfully cleaner, push for the cleaner version.
   • Do not rubber-stamp "it works" implementations that leave the codebase messier.
   • Strongly prefer simplifications that remove moving pieces altogether over refactors that merely spread the same complexity around.

4. Prefer direct, boring, maintainable code over hacky or magical code.

   • Treat brittle, ad-hoc, or "magic" behavior as a code-quality problem.
   • Be skeptical of generic mechanisms that hide simple data-shape assumptions.
   • Flag thin abstractions, identity wrappers, or pass-through helpers that add indirection without buying clarity.

5. Push hard on type and boundary cleanliness when they affect maintainability.

   • Question unnecessary optionality, unknown, any, or cast-heavy code when a clearer type boundary could exist.
   • Prefer explicit typed models or shared contracts over loosely-shaped ad-hoc objects.
   • If a branch relies on silent fallback to paper over an unclear invariant, ask whether the boundary should be made explicit instead.

6. Keep logic in the canonical layer and reuse existing helpers.

   • Call out feature logic leaking into shared paths or implementation details leaking through APIs.
   • Prefer existing canonical utilities/helpers over bespoke one-offs.
   • Push code toward the right package, service, or module instead of normalizing architectural drift.

7. Treat unnecessary sequential orchestration and non-atomic updates as design smells when the cleaner structure is obvious.

   • If independent work is serialized for no good reason, ask whether the flow should run in parallel instead.
   • If related updates can leave state half-applied, push for a more atomic structure.
   • Do not over-index on micro-optimizations, but do flag avoidable orchestration complexity that makes the implementation more brittle.

Primary Review Questions

For every meaningful change, ask:

• Is there a "code judo" move that would make this dramatically simpler?
• Can this change be reframed so fewer concepts, branches, or helper layers are needed?
• Does this improve or worsen the local architecture?
• Did the diff add branching complexity where a better abstraction should exist?
• Did a previously cohesive module become more coupled, more stateful, or harder to scan?
• Is this logic living in the right file and layer?
• Did this change enlarge a file or component past a healthy size boundary?
• Are there repeated conditionals that signal a missing model or missing helper?
• Is the implementation direct and legible, or does it rely on special cases and incidental control flow?
• Is this abstraction actually earning its keep, or is it just a wrapper?
• Did the diff introduce casts, optionality, or ad-hoc object shapes that obscure the real invariant?
• Is this logic living in the canonical layer, or did the diff leak details across a boundary?
• Is this orchestration more sequential or less atomic than it needs to be?

What to Flag Aggressively

Escalate findings when you see:

• A complicated implementation where a cleaner reframing could delete whole categories of complexity.
• Refactors that move code around but fail to reduce the number of concepts a reader must hold in their head.
• A file crossing 1000 lines due to the PR, especially if the new code could be split out.
• New conditionals bolted onto unrelated code paths.
• One-off booleans, nullable modes, or flags that complicate existing control flow.
• Feature-specific logic leaking into general-purpose modules.
• Generic "magic" handling that hides simple structure and makes the code harder to reason about.
• Thin wrappers or identity abstractions that add indirection without simplifying anything.
• Unnecessary casts, any, unknown, or optional params that muddy the real contract.
• Copy-pasted logic instead of extracted helpers.
• Narrow edge-case handling implemented in the middle of an already busy function.
• Refactors that technically pass tests but make the code less modular or less readable.
• "Temporary" branching that is likely to become permanent debt.
• Bespoke helpers where the codebase already has a canonical utility for the job.
• Logic added in the wrong layer/package when it should live somewhere more central.
• Sequential async flow where obviously independent work could stay simpler and clearer with parallel execution.
• Partial-update logic that leaves state less atomic than necessary.

Preferred Remedies

When you identify a code-quality problem, prefer suggestions like:

• Delete a whole layer of indirection rather than polishing it.
• Reframe the state model so conditionals disappear instead of getting centralized.
• Change the ownership boundary so the feature becomes a natural extension of an existing abstraction.
• Turn special-case logic into a simpler default flow with fewer exceptions.
• Extract a helper or pure function.
• Split a large file into smaller focused modules.
• Move feature-specific logic behind a dedicated abstraction.
• Replace condition chains with a typed model or explicit dispatcher.
• Separate orchestration from business logic.
• Collapse duplicate branches into a single clearer flow.
• Delete wrappers that do not meaningfully clarify the API.
• Reuse the existing canonical helper instead of introducing a near-duplicate.
• Make type boundaries more explicit so the control flow gets simpler.
• Move the logic to the package/module/layer that already owns the concept.
• Parallelize independent work when that also simplifies the orchestration.
• Restructure related updates into a more atomic flow when partial state would be harder to reason about.

Do not be satisfied with "maybe rename this" feedback when the real issue is structural. Do not be satisfied with a merely cleaner version of the same messy idea if there is a plausible path to a much simpler idea.

Review Tone

Be direct, serious, and demanding about quality. Do not be rude, but do not soften major maintainability issues into mild suggestions. If the code is making the codebase messier, say so clearly. If the implementation missed an opportunity for a dramatic simplification, say that clearly too.

Good phrases:

• this pushes the file past 1k lines. can we decompose this first?
• this adds another special-case branch into an already busy flow. can we move this behind its own abstraction?
• this works, but it makes the surrounding code more spaghetti. let's keep the behavior and restructure the implementation.
• this feels like feature logic leaking into a shared path. can we isolate it?
• this abstraction seems unnecessary. can we just keep the direct flow?
• why does this need a cast / optional here? can we make the boundary more explicit instead?
• this looks like a bespoke helper for something we already have elsewhere. can we reuse the canonical one?
• i think there's a code-judo move here that makes this much simpler. can we reframe this so these branches disappear?
• this refactor moves complexity around, but doesn't really delete it. is there a way to make the model itself simpler?

Output Expectations

Prioritize findings in this order:

1. Structural code-quality regressions
2. Missed opportunities for dramatic simplification / code-judo restructuring
3. Spaghetti / branching complexity increases
4. Boundary / abstraction / type-contract problems that make the code harder to reason about
5. File-size and decomposition concerns
6. Modularity and abstraction issues
7. Legibility and maintainability concerns

Do not flood the review with low-value nits if there are larger structural issues. Prefer a smaller number of high-conviction comments over a long list of cosmetic notes.

Approval Bar

Do not approve merely because behavior seems correct. The bar for approval is:

• no clear structural regression
• no obvious missed opportunity to make the implementation dramatically simpler when such a path is visible
• no unjustified file-size explosion
• no obvious spaghetti-growth from special-case branching
• no obviously hacky or magical abstraction that makes the code harder to reason about
• no unnecessary wrapper/cast/optionality churn obscuring the real design
• no clear architecture-boundary leak or avoidable canonical-helper duplication
• no missed opportunity for an obvious decomposition that would materially improve maintainability

Treat these as presumptive blockers unless the author can justify them clearly:

• the PR preserves a lot of incidental complexity when there is a plausible code-judo move that would delete it
• the PR pushes a file from below 1000 lines to above 1000 lines
• the PR adds ad-hoc branching that makes an existing flow more tangled
• the PR solves a local problem by scattering feature checks across shared code
• the PR adds an unnecessary abstraction, wrapper, or cast-heavy contract that makes the design more indirect
• the PR duplicates an existing helper or puts logic in the wrong layer when there is a clear canonical home

If those conditions are not met, leave explicit, actionable feedback and push for a cleaner decomposition.

Verify This

Verification is not a recap. It proves or disproves a specific claim with repeatable evidence.

When To Use

• The user asks "verify this", "prove it works", "did this fix it", or "show me the evidence".
• A bug fix needs a before/after repro.
• A UI, CLI, API, performance, or memory claim needs measurement.
• A test passes but the user-visible behavior still needs confirmation.

Do not use this for vague claims like "the code is cleaner". Ask for a measurable claim first.

Workflow

1. Restate the claim in falsifiable form: condition, metric, and threshold.
2. Pick the smallest local surface that can disprove it.
3. Capture a baseline from the old state: merge base, parent commit, failing branch, or current broken repro.
4. Capture treatment from the changed state with the same command, data, warmup, and environment.
5. Compare raw artifacts: numbers, screenshots, terminal transcripts, HTTP responses, profiles, heap snapshots, or test output.
6. Return exactly one verdict: VERIFIED, NOT VERIFIED, or INCONCLUSIVE.

Local Surfaces

• Code behavior: focused unit/integration tests or a minimal repro script.
• CLI/TUI behavior: control-cli, terminal transcript, or demo recording.
• UI behavior: control-ui, screenshots, accessibility snapshots, or browser traces.
• API behavior: local HTTP/RPC request and response diff.
• Performance: same-machine baseline/treatment timings or CPU profiles.
• Memory: heap snapshots before and after the suspected operation.

Artifact Layout

When safe to write artifacts:

/tmp/verify-this/<claim-slug>/
├── claim.md
├── timeline.md
├── baseline/
├── treatment/
├── diff/
└── verdict.md

If artifacts may contain sensitive code, prompts, screenshots, HTTP bodies, or heap data, keep only the minimal inline evidence unless the user agrees to disk storage.

Verdict Rules

• VERIFIED: baseline and treatment differ in the predicted direction, by the claimed threshold, with no obvious confound.
• NOT VERIFIED: the behavior is unchanged, moves the wrong way, or misses the threshold.
• INCONCLUSIVE: no valid baseline, noisy signal, failed measurement, or an environment difference invalidates the comparison.

Output

Use this shape:

VERIFIED | NOT VERIFIED | INCONCLUSIVE
Claim: <falsifiable claim>

Evidence:
<metric/artifact>: baseline=<...>, treatment=<...>, delta=<...>, threshold=<...>

Reasoning:
<one tight paragraph naming the evidence and any confounds>

Do not soften a negative result. A clear NOT VERIFIED is useful.

Weekly review

Trigger

Need a weekly recap of shipped work for status updates, retros, or planning.

Workflow

1. Determine the current git user email from repo config.
2. Collect authored commits from the last 7-10 days on the primary branch context.
3. Exclude merge commits.
4. Group meaningful changes into 2-5 concise bullets.
5. Add a short classification paragraph covering:
   • likely bug fixes
   • likely tech debt work
   • likely net-new functionality

Guardrails

• Keep the recap short and executive-readable.
• Base claims only on commit history and diffs.
• If git email is missing, ask the user to set it before proceeding.

Output

• 2-5 bullet weekly summary
• Brief classification paragraph (bugfix / tech debt / net-new)

What did I get done

Trigger

Need a short, high-signal summary of work completed in a specific time range (for example: yesterday, last 3 days, or last week).

Workflow

1. Resolve the requested time window into concrete dates.
2. Read commits authored by the current git user email within that range.
3. Exclude merge commits and uncommitted changes.
4. Synthesize the most important shipped changes into a concise status update.
5. Include the actual date range used in the final summary.

Guardrails

• Be extremely concise and information-dense.
• Prioritize substantial behavior or architecture changes.
• Omit cosmetic-only changes (formatting, imports, minor renames).
• Do not infer intent or motivation. Describe changes functionally.

Output

• One short summary suitable for a status update
• Real date range
• Optional 2-5 bullets for major changes only

Workflow From Chats

Infer durable working preferences from recent chats. Do not summarize chats; extract reusable workflow guidance.

Scope

• Default to the last 7 days unless the user asks for a different window.
• Read parent transcripts and relevant subagent transcripts. Use subagent content as evidence, but cite only parent conversations.
• Do not expose local transcript paths, secrets, customer data, private chat content, or credentials.

Workflow

1. State the target workflow or preference surface in one paragraph.
2. Build an internal transcript inventory: title/topic, parent conversation ID, approximate date, completion state, relevant subagents, and why it may contain preference evidence.
3. Scan for explicit preferences, corrections, and workflow markers such as "I prefer", "always", "never", "not what I asked", "stop", "review", "PR", "CI", "logs", and "skill".
4. Extract preference atoms: trigger, workflow step, decision rule, quality bar, stop condition, evidence, and confidence.
5. Rate confidence as strong, medium, weak, or contradicted.
6. Cluster by workflow shape rather than transcript: shipping, review, simplification, debugging, capture, communication, delegation, or validation.
7. Choose the artifact: new skill, skill edit, rule, workflow doc, or no artifact.
8. Draft only the reusable guidance. Filter anecdotes that will not help future tasks.

Confidence

• Strong: explicit user preference, workflow-changing correction, repeated parent-chat pattern, or direct request to encode behavior.
• Medium: accepted workflow, repeated tool/model/validation preference, or subagent consensus that the parent used successfully.
• Weak: agent-chosen behavior with no user feedback, one ambiguous transcript, or a likely task-specific correction.
• Contradicted: evidence points in incompatible directions; ask the user before writing files.

Artifact Choice

• Skill: recurring multi-step workflow with clear triggers.
• Rule: general behavior that should apply broadly.
• Workflow doc: useful context that is not reliably triggerable.
• No artifact: situational, stale, or low-confidence observation.

Output

Return a concise synthesis first:

• Target workflow.
• Evidence corpus with parent conversation citations only.
• Preference profile.
• Adopt, consider, dismissed.
• Proposed artifacts.
• Open questions only if they block writing.

Docs Canvas

Build a canvas that presents documentation — architecture notes, API references, design docs, runbooks, or codebase walkthroughs — as an interactive, navigable surface rather than as a flat markdown file.

Status: placeholder. The skill structure is in place so the canvas welcome page can surface this plugin via the marketplace query, but the full skill body still needs to be written. Treat the steps below as a starting outline and refine as the docs canvas pattern matures.

Prerequisites

Read ~/.cursor/skills-cursor/canvas/SKILL.md first. It contains the generation policy, design guidance, slop rules, self-check, and file-path conventions you must follow. The full component and hook surface is declared in ~/.cursor/skills-cursor/canvas/sdk/index.d.ts and its sibling .d.ts files — read them to discover exact exports and prop shapes rather than guessing.

Gather the source material

Accept any of: a directory of markdown files, a single doc URL, an inline outline, or a question to answer from the codebase. Collect headings, code blocks, diagrams, and any cross-references between documents.

Plan the canvas layout

Decide the top-level structure before writing any components. A docs canvas usually has:

1. Overview — A short summary card with the purpose of the doc, scope, and audience.
2. Table of contents — Navigable list of sections, ideally pinned or sticky so the reader can jump around.
3. Body sections — One section per logical unit (architecture, API, examples, gotchas). Each section can mix prose, code blocks, diagrams, and callouts.
4. References — Links to related docs, source files, RFCs, and external material.

Render with canvas primitives

Prefer built-in canvas components over raw HTML:

• Use cards/sections to group related content visually.
• Use code blocks with syntax highlighting for snippets.
• Use diagrams (DAG layout, mermaid) for architecture.
• Use callouts for "Important", "Warning", "Note", "Deprecated".
• Use tables for API parameter lists and option matrices.

Tone and content

Write reader-facing prose. Lead with the answer or the headline, then explain. Keep examples small and runnable. Cite source files with code references so readers can jump in.

Be creative

The sections above are a floor, not a ceiling. The goal is the fastest possible path for the reader to understand the topic — so look at the source material in front of you and ask what representation would actually help. A diagram, a sequence chart, a side-by-side comparison, a decision tree, a glossary, a curated FAQ, a single large worked example — whatever fits.

Orchestrate

An explicit /orchestrate <goal> fans out a large task across parallel Cursor cloud agents. Workers don't talk to each other; they talk up through structured handoffs. The spawn, wait, and handoff loop lives in scripts/cli.ts. The planner writes plan.json, the script executes it, and the planner reads handoffs to decide what comes next. Long-running agent loops drift; a script with a JSON state file keeps its footing.

Required reading: the cursor-sdk skill (cursor/plugins/cursor-sdk). Spawning, auth, and the error taxonomy live there. Don't reimplement what that skill already documents.

Setup

• CURSOR_API_KEY must be a personal/user key. Create it from Cursor Dashboard > Integrations, then read cursor-sdk Auth before using it.
• SLACK_BOT_TOKEN is optional. When set, pass --slack-channel <id> to kickoff or the first run --root, or set SLACK_CHANNEL_ID. The script stores the channel in plan.slackChannel, posts the kickoff thread there, mirrors task status, and reads Andon reactions. When the token is unset, the script logs once and runs without Slack visibility; correctness does not change.

Core principles

These rules make the tree self-converging without global coordination.

1. Planners own scopes and publish tasks. They do no coding. Writing plan.json, reading handoffs, and deciding what's next are planner work. Editing files, running git merge, and fixing conflicts inline are not. If a planner feels the urge to code, it publishes a task for a worker instead.
2. Planners don't know who picks up their tasks. The script routes each task to a cloud agent. The planner's mental model stays at the task level.
3. Workers are isolated. One task, one clone of the repo, no channel to any other agent. One handoff when done.
4. Subplanners are recursive planners. A planner publishes a "subplan this slice" task; the subplanner fully owns that slice and hands back an aggregated handoff.
5. Continuous motion via handoffs. A planner that thought it was done can receive a late handoff and replan. No "finished" state until the planner decides to stop publishing.
6. Propagation, not synchronization. No cross-talk between siblings. No shared state between levels. Each level sees only its children's handoffs.

Node types

Role

Two roles, one skill. Read your role's reference file and skip the other.

Dispatcher. You're in a local IDE session and the user typed /orchestrate <goal>. Your job is to kick off a cloud root planner and return its URL. See references/dispatcher.md. One-shot; you are not the planner.

Planner (root or sub). You were spawned with a structured prompt that opens with "You are the root planner for:" or "You are a subplanner for:". Or the user chose to run the planning loop locally. You own a scope, publish tasks, read handoffs, decide what's next. See references/planner.md.

disable-model-invocation: true means this skill loads only on explicit invocation.

PR Review Canvas

Build a canvas that presents a PR diff reorganized for reviewer comprehension — not in file-tree order.

Prerequisites

Read ~/.cursor/skills-cursor/canvas/SKILL.md first. It contains the generation policy, design guidance, slop rules, self-check, and file-path conventions you must follow. The full component and hook surface is declared in ~/.cursor/skills-cursor/canvas/sdk/index.d.ts and its sibling .d.ts files — read them to discover exact exports and prop shapes rather than guessing.

Gather the diff

Expect a GitHub PR link (a full URL like https://github.com/<owner>/<repo>/pull/<n>, or an equivalent gh-resolvable reference). Use gh pr diff <pr> to collect every file's path, additions, deletions, and hunks.

If the user didn't provide a PR link, stop and ask. Do not guess at the current branch, infer from recent history, or fall back to a local git diff. Ask the user which diff they want to review — a specific PR URL or number — and wait for their reply before continuing.

Group changes for comprehension

Do not present files in alphabetical or tree order. Reorganize into sections ordered by reviewer value:

1. Core logic — New behavior, algorithm changes, state transitions, API surface changes. Show full diffs with surrounding context.
2. Wiring & integration — Route registration, dependency injection, config plumbing that connects the core logic. Condensed — enough to confirm correctness.
3. Boilerplate & mechanical — Import reordering, renames, generated code, formatting, type re-exports. Summarize as a list of file names and stats. No inline diffs unless specifically relevant.

Lead with core logic. The reviewer's attention is freshest at the top.

Distill complex logic into pseudocode

When a core change involves dense or intricate logic — deeply nested conditions, state machines, retry/backoff flows, multi-step transformations — add a short pseudocode summary next to the diff. The pseudocode should strip away language syntax, error handling, and boilerplate to expose the essential algorithm or control flow in a few lines. This lets the reviewer confirm intent before reading the real code.

Only do this when the actual diff is hard to scan. Straightforward changes don't need a pseudocode mirror.

Trace tricky logic on a concrete example

Pseudocode shows the shape of the change; an example trace shows it executing. When a hunk changes behavior in a way that's hard to predict from reading it — reordered effects, new short-circuits, altered edge cases — pick a concrete input and walk it through both the old and new code paths side-by-side, highlighting the step where they diverge and what the observable outcome is. Keep the input small and realistic.

Use this for genuinely surprising behavior changes, not every core hunk.

Call attention to tricky things

When a hunk contains something surprising, risky, or easy to miss, visually separate it from the surrounding diff and pair it with a short tag (e.g. "Subtle", "Breaking", "Race condition", "Perf") and a one-sentence explanation so the reviewer sees the concern and the code together.

Reserve these callouts for genuinely tricky items — overuse destroys signal.

Tone and content

Write reviewer-facing commentary, not a changelog. Focus on:

• Why something changed, not just what changed.
• Interactions between files — e.g. "The new validator in core.ts is invoked by the route added in routes.ts."
• Anything the diff alone doesn't make obvious.

Keep commentary terse. One or two sentences per note.

Be creative

The sections above are a floor, not a ceiling. The goal is the fastest possible path for the reviewer to understand this specific change — so look at the diff in front of you and ask what representation would actually help. A tiny state diagram, a before/after call graph, a table of input→output pairs, a timeline of commits, a confidence annotation per file, a single large callout with everything else collapsed — whatever fits the change.

The canvas SDK has charts, tables, diff views, DAG layout, cards, stats, interactive state, and more. Reach for whichever components best serve the change at hand. A review of a refactor looks different from a review of a bug fix looks different from a review of a new feature — let the canvas reflect that.

Architect

Design before implementing. Sketch types, function signatures, class shapes, and module boundaries with not implemented bodies and pseudocode. Synthesize across multiple model perspectives, then fill in code against the chosen sketch. If implementation proves the sketch wrong, throw it out and redesign.

Start

Open a todolist with one entry per phase before starting. Autonomous mode without checkpoints needs the list to show phase position and keep phases from silently disappearing.

1. Ground
2. Sketch
3. Agree
4. Implement
5. Scrap

Phase A: Ground the problem

Build a real mental model of every system the new code touches. Run the how skill over the relevant subsystems. Critique mode if existing structure is the constraint or the design must push back on it.

Naming a file isn't grounding. Produce the traced model how prescribes. If the design redefines ownership or layering, also run the why skill on the existing shape so the rationale becomes a constraint, not a guess.

Skip Phase A only when the work is genuinely greenfield with no surrounding system to integrate.

Phase B: Sketch

Run the arena skill with the design-sketch task and the Phase A grounding artifacts. Pass references/runner-prompt.md as each runner's prompt. Each candidate produces a design package shaped per references/rationale-template.md: the caller's usage written first, then the type sketch, function signatures, module map, and prose rationale derived from it.

Use these runner slugs: claude-opus-4-8-thinking-xhigh, gpt-5.3-codex-high-fast, gpt-5.5-high-fast, and composer-2.5-fast.