SylphAI-Inc avatar

swe-cli-skills

man pages for machines — Senior engineer CLI expertise across 23 CLIs. Covers workflows, safety guardrails, gotchas, and anti-patterns for cloud, IaC, containers, databases, dev tools & platforms.

GitHub stars
112

Install

/plugin install swe-cli-skills@adal-agent-skills

Run it inside Claude Code after adding the marketplace with /plugin marketplace add SylphAI-Inc/skills.

Contents

Discovered from source

Skills 8

Guide: Visual-First Web Cloning Recipe v2

When building a high-fidelity landing page clone, the biggest trap is relying purely on DOM trees and CSS dumps. Modern website builders (Framer, Webflow) generate deeply nested "div soup" and obfuscated CSS to create visual effects.

The Golden Rule: Trust your "eyes" (screenshots) first, but when an effect looks too complex to be pure CSS, use Deep DOM Interrogation to steal the exact asset — never guess the math.

Tool note: This guide uses AdaL browser-use agent tools (navigate, javascript_tool, computer, resize_window, tabs_context, bash). If you're not on AdaL, the same JS payloads work with Chrome DevTools MCP (evaluate_script), Playwright (page.evaluate), or any browser automation tool — just swap the invocation wrapper.

The 80/20 Cloning Philosophy

Divide your workflow into two phases so you don't get bogged down pixel-pushing too early:

  1. The 80% Sprint (Speed & Structure): Get the page laid out rapidly. Fetch the semantic HTML, scaffold the React component tree (Navbar, Hero, Features), and apply basic Tailwind for layout (Flex/Grid) and spacing. Accept approximations — solid colors instead of gradients, standard shadows, static backgrounds. Move fast.
  2. The 20% Polish (Pixel Perfection & Physics): Once the structure is on screen, shift to meticulous engineering. Use "Sniper CSS" to extract exact multi-stop gradients, rip WebGL canvas backgrounds to .webm, map massive multi-layer box-shadows, and implement Framer Motion spring physics.

The 4-Phase Workflow

Phase 1: Visual Discovery

Goal: Understand what you're cloning before touching code.

Step 0: Screenshot Matrix (3 Viewports)

Always capture the target at multiple sizes before coding. Do not optimize only for the first screenshot.

ViewportPurposeRequired?
1440×1400Primary desktop comparison targetAlways
1920×1200 or largerDetects false fixed-left layouts and max-width issuesAlways
390×844 or 430×932Mobile hero layout and nav behaviorAlways unless user says desktop-only
navigate("https://target-site.com/")
tabs_context                                   // confirm tab_id
resize_window(tab_id=1, width=1440, height=1400)
javascript_tool(tab_id=1, action="javascript_exec", text="window.scrollTo(0, 0); 'ok';")
computer(tab_id=1, action="wait", duration=2)  // let animations settle
computer(tab_id=1, action="screenshot")        // desktop hero

resize_window(tab_id=1, width=1920, height=1200)
computer(tab_id=1, action="wait", duration=2)
computer(tab_id=1, action="screenshot")        // large desktop

resize_window(tab_id=1, width=390, height=1400)
computer(tab_id=1, action="wait", duration=2)
computer(tab_id=1, action="screenshot")        // mobile
Step 1: The "Eye Test" (Visual Grounding)

Before looking at a single line of code, visually ground yourself in the reference site.

Read your screenshots and actively identify the Vibe:

  • Backgrounds: Is it flat? A subtle radial gradient? Sweeping SVG waves? Floating blurred orbs? Star/particle field?
  • Buttons: Are they flat? Glassmorphic (backdrop-blur)? Glowing auras? Multi-layer shadows?
  • Typography: Which specific words are highlighted? Gradient text clips? Tight negative letter-spacing?
  • Badges/pills: Compound components (pill-in-a-pill)?
Step 2: Macro Structure Capture (Semantic HTML)

Pull a text/structure snapshot — grab the section landmarks and real copy in one shot:

javascript_tool(tab_id=1, action="javascript_exec", text="
(() => JSON.stringify({
  h1: document.querySelector('h1')?.innerText,
  navLinks: Array.from(document.querySelectorAll('nav a')).map(a => a.innerText.trim()).filter(Boolean),
  buttons: Array.from(document.querySelectorAll('a, button')).map(b => b.innerText.trim()).filter(Boolean).slice(0, 12),
  sections: Array.from(document.querySelectorAll('section')).length
}, null, 2))()
")

Do NOT blindly copy the DOM. Distill the complicated nested builder divs into clean, semantic React (<nav>, <section>, <h1>, <button>). A 12-deep Framer <div> chain becomes one <button>. Note: Framer often duplicates button text ("Book a callBook a call") — dedupe it.

Step 3: Micro Extraction (Sniper CSS)

Extract exact pixel-perfect design tokens. Never dump the full getComputedStyle object — it returns 500+ properties, overwhelms your context window, and creates hallucination. Use the targeted scripts in the Sniper CSS Script Library below.

Step 4: Animation Detection

Landing page animations come from many sources. Don't assume canvas = animation. Run this comprehensive scanner to detect what's powering the motion:

javascript_tool(tab_id=1, action="javascript_exec", text="
(() => {
  const results = { animations: [], tech: {}, elements: {} };

  // A. CSS Animations & Transitions
  const allEls = document.querySelectorAll('*');
  const cssAnimated = [];
  allEls.forEach(el => {
    const s = getComputedStyle(el);
    if (s.animationName && s.animationName !== 'none') {
      cssAnimated.push({ tag: el.tagName, class: el.className?.toString().slice(0, 60), animation: s.animationName, duration: s.animationDuration });
    }
  });
  results.animations.push({ type: 'css', count: cssAnimated.length, samples: cssAnimated.slice(0, 5) });

  // B. Canvas elements
  results.elements.canvas = Array.from(document.querySelectorAll('canvas')).map(c => ({
    width: c.width, height: c.height,
    ariaLabel: c.getAttribute('aria-label'),
    parentDataAttrs: Object.fromEntries([...(c.closest('[data-us-project],[data-scene-id]')?.attributes || [])].filter(a => a.name.startsWith('data-')).map(a => [a.name, a.value]))
  }));

  // C. Video elements
  results.elements.video = Array.from(document.querySelectorAll('video')).map(v => ({ src: v.src || v.querySelector('source')?.src || 'none', autoplay: v.autoplay, loop: v.loop, muted: v.muted }));

  // D. SVG animations
  results.elements.svgAnimations = document.querySelectorAll('svg animate, svg animateTransform, svg animateMotion').length;

  // E. Lottie / Rive / Spline
  results.elements.lottie = document.querySelectorAll('lottie-player, dotlottie-player, [class*="lottie"]').length;
  results.elements.rive = document.querySelectorAll('canvas[class*="rive"], [data-rive-src]').length;
  results.elements.spline = document.querySelectorAll('canvas[data-engine="spline"]').length;

  // F. iframes
  results.elements.iframes = Array.from(document.querySelectorAll('iframe')).map(f => ({ src: f.src?.slice(0, 150) }));

  // G. JS animation library globals
  results.tech.gsap = typeof window.gsap !== 'undefined';
  results.tech.threeJS = typeof window.THREE !== 'undefined';
  results.tech.lottie = typeof window.lottie !== 'undefined';
  results.tech.rive = typeof window.rive !== 'undefined';
  results.tech.anime = typeof window.anime !== 'undefined';
  results.tech.unicornStudio = typeof window.UnicornStudio !== 'undefined';
  results.tech.pixiJS = typeof window.PIXI !== 'undefined';
  results.tech.p5 = typeof window.p5 !== 'undefined';

  // H. Animation library scripts
  const scriptUrls = performance.getEntriesByType('resource').filter(r => r.name.match(/\.(js|mjs)$/i)).map(r => r.name).filter(s => !s.includes('google') && !s.includes('analytics') && !s.includes('gtm'));
  const sigs = ['gsap','three','lottie','rive','anime','framer-motion','popmotion','unicorn','spline','pixi','p5','mo.js','velocity','scroll-trigger','locomotive'];
  results.tech.animationScripts = scriptUrls.filter(url => sigs.some(sig => url.toLowerCase().includes(sig)));

  // I. Framer appear animations
  const framerAppear = document.querySelectorAll('[data-framer-appear-id]');
  results.tech.framerAppearElements = framerAppear.length;
  if (framerAppear.length > 0) {
    results.tech.framerAppearSample = Array.from(framerAppear).slice(0, 3).map(el => ({ id: el.getAttribute('data-framer-appear-id'), style: { opacity: el.style.opacity, transform: el.style.transform } }));
  }

  return JSON.stringify(results, null, 2);
})()
")

Decision tree — interpret results:

What you foundAnimation TechHow to replicate
unicornStudio: true + canvas with data-us-projectUnicorn Studio (WebGL)Embed: load their runtime JS + init with same project ID
threeJS: true + canvasThree.js (3D WebGL)Capture as looping video, or re-implement if simple
lottie: true or elements.lottie > 0Lottie (After Effects → JSON)Find the .json file, use lottie-react
gsap: trueGSAP (scroll/timeline)Re-implement with GSAP or translate to Framer Motion
elements.rive > 0Rive (interactive vector)Find .riv file, use @rive-app/react-canvas
elements.spline > 0Spline (3D web scenes)Embed via iframe or @splinetool/react-spline
elements.video with autoplay+loopPre-rendered video backgroundDownload the MP4/WebM and embed
elements.svgAnimations > 0SVG SMIL animationCopy the SVG markup including <animate> elements
framerAppearElements > 0 + CSS transitionsFramer entrance animationsExtract delays/durations, rebuild with Framer Motion
CSS animations only, no librariesPure CSSExtract @keyframes and animation properties
Nothing detected but things moveScroll-driven CSS or IntersectionObserverCheck for scroll-timeline, animation-timeline, or custom JS observers
Step 4b: GIF Recording & Analysis (Understand Effects)

The scanner tells you what tech powers the animation, but not what it looks like in motion. Animations are invisible to static CSS extraction. Use the browser-use agent's gif_creator tool to capture entrance animations, hover effects, and continuous motion as animated GIFs, then analyze the frames.

How gif_creator works: It records screenshots automatically on every computer action (click, scroll, screenshot, wait) and navigate call while recording is active. Max 50 frames per recording. Export produces an animated GIF with optional overlays (click indicators, action labels, progress bar, watermark). Use download: true to save to disk, or coordinate: [x, y] to drag-drop onto a page.

Record the entrance animation:

// 1. Start recording — clears any previous frames
gif_creator(tab_id=1, action="start_recording")

// 2. Navigate to trigger entrance animations (this captures the first frame)
navigate(tab_id=1, url="https://target-site.com/")

// 3. Capture frames at intervals to record the animation progression
//    Each screenshot call captures a frame automatically
computer(tab_id=1, action="wait", duration=0.3)
computer(tab_id=1, action="screenshot")   // frame: early entrance
computer(tab_id=1, action="wait", duration=0.5)
computer(tab_id=1, action="screenshot")   // frame: mid-animation
computer(tab_id=1, action="wait", duration=0.5)
computer(tab_id=1, action="screenshot")   // frame: near-settled
computer(tab_id=1, action="wait", duration=1.0)
computer(tab_id=1, action="screenshot")   // frame: settled
computer(tab_id=1, action="wait", duration=1.5)
computer(tab_id=1, action="screenshot")   // frame: final resting state

// 4. Stop recording (keeps frames for export)
gif_creator(tab_id=1, action="stop_recording")

// 5. Export as GIF — download to disk for analysis
gif_creator(
  tab_id=1,
  action="export",
  download=true,
  filename="entrance-animation.gif",
  options={showClickIndicators: false, showActionLabels: false, showProgressBar: true, quality: 5}
)

Analyze the GIF — the exported GIF is saved to the browser screenshot directory (default: /tmp/adal_browser/). Read it with your image tool and identify:

  • Which elements appear/disappear across frames
  • Animation type per element (fade, slide-up, scale, blur-to-sharp)
  • Approximate timing and stagger order (frame timestamps are embedded)
  • Continuous vs one-shot animations (does the glow keep rotating after everything settles?)

Record hover/interaction effects:

// 1. Start recording
gif_creator(tab_id=1, action="start_recording")

// 2. Capture resting state
computer(tab_id=1, action="screenshot")

// 3. Hover over the button to trigger the hover animation
computer(tab_id=1, action="hover", coordinate=[500, 400])
computer(tab_id=1, action="wait", duration=0.5)
computer(tab_id=1, action="screenshot")   // frame: hover state

// 4. Move away to capture the transition back
computer(tab_id=1, action="hover", coordinate=[10, 10])
computer(tab_id=1, action="wait", duration=0.3)
computer(tab_id=1, action="screenshot")   // frame: resting state restored

// 5. Stop and export
gif_creator(tab_id=1, action="stop_recording")
gif_creator(
  tab_id=1,
  action="export",
  download=true,
  filename="hover-effect.gif",
  options={showClickIndicators: true, showActionLabels: true, quality: 5}
)

Record scroll-triggered animations:

gif_creator(tab_id=1, action="start_recording")
computer(tab_id=1, action="screenshot")                          // frame: top of page
computer(tab_id=1, action="scroll", coordinate=[720, 400], scroll_direction="down", scroll_amount=3)
computer(tab_id=1, action="wait", duration=1.0)
computer(tab_id=1, action="screenshot")                          // frame: mid-scroll reveal
computer(tab_id=1, action="scroll", coordinate=[720, 400], scroll_direction="down", scroll_amount=3)
computer(tab_id=1, action="wait", duration=1.0)
computer(tab_id=1, action="screenshot")                          // frame: further down
gif_creator(tab_id=1, action="stop_recording")
gif_creator(tab_id=1, action="export", download=true, filename="scroll-animations.gif", options={quality: 5})

Common Framer hero animation patterns (discovered from real clone sessions):

ElementAnimationTimingFramer Motion
Glow/orbAppears first, continuous morph/rotation0s (always visible)CSS @keyframes or animate={{ rotate: 360 }} with repeat: Infinity
NavbarSlide down + fade in~0.1-0.3sinitial={{ y: -20, opacity: 0 }} animate={{ y: 0, opacity: 1 }}
Badge ("New")Fade + scale in~0.3-0.5sinitial={{ opacity: 0, scale: 0.9 }} animate={{ opacity: 1, scale: 1 }}
H1 headingFade in + slide up~0.4-0.6sinitial={{ y: 30, opacity: 0 }} animate={{ y: 0, opacity: 1 }}
DescriptionFade in + slide up~0.5-0.7sSame pattern, staggered
CTA buttonsFade in + slide up~0.6-0.8sSame pattern, staggered
Stars/particlesFade in~0.2-0.5sinitial={{ opacity: 0 }} animate={{ opacity: 0.5 }}

Key insight: Most Framer hero animations use a simple staggered fade-up pattern. The glow/orb is the only continuously animated element. The GIF recording confirms the exact stagger order and timing.

GIF tips:

  • Max 50 frames per recording — plan your capture sequence to stay under the limit
  • Use quality: 5 for higher-quality GIFs during analysis (lower number = better quality)
  • Disable overlays (showClickIndicators: false, showActionLabels: false) for clean visual analysis
  • Enable overlays (showClickIndicators: true) when recording for documentation or sharing
  • Use gif_creator(tab_id=1, action="clear") to discard frames if you need to re-record
Step 5: Asset Extraction (SVGs, Logos, Videos)
  • Inline SVG: Extract outerHTML via javascript_tool, then save with bash
  • Data-URI background logos: Trust/logo carousels frequently render as CSS background-image data-URIs on <div>s — not <img> tags. Use Script 7 to find them, decode and save with bash
  • Background videos: Capture as .webm/.mp4 via canvas recorder (Script 10), store in src/assets/media/
  • Fonts: Search @font-face rules and performance.getEntriesByType('resource') for .woff2 URLs. Self-host in assets/fonts/
Step 6: Deep DOM Interrogation

When an effect (like a smooth background or a swirling button) is too complex, do not guess the math. Framer and Webflow hide these in layered divs, pseudo-elements, or literal <video>/<canvas> tags.

Render Engine Identification — find the full-screen background node to determine if it's a video, canvas, or CSS:

javascript_tool(tab_id=1, action="javascript_exec", text="
(() => {
  const backgrounds = [];
  document.querySelectorAll('*').forEach(el => {
    const style = window.getComputedStyle(el);
    const rect = el.getBoundingClientRect();
    if ((style.position === 'fixed' || style.position === 'absolute') &&
        (parseInt(style.zIndex) <= 0 || style.zIndex === 'auto') &&
        rect.width >= window.innerWidth * 0.8 &&
        rect.height >= window.innerHeight * 0.5 &&
        el.tagName !== 'BODY' && el.tagName !== 'HTML') {
       backgrounds.push({ tag: el.tagName, html: el.outerHTML.substring(0, 300) });
    }
  });
  return JSON.stringify(backgrounds, null, 2);
})()
")

The DOM never lies. You might discover the "complex animation" is actually:

  1. A Video: A <video src="...mp4"> tag. Solution: Extract the URL and drop it in.
  2. A WebGL Canvas: A <canvas> tag. Solution: Record as video (Script 10) or re-implement with React Three Fiber.
  3. A Noise Overlay: A repeating film-grain image at 5-10% opacity layered over the effect to prevent color banding.

Phase 2: Write the Clone Plan

Before writing a single line of code, create docs/clone_plan.md:

# Clone Plan: [Site Name]

## Target
- URL: https://...
- Scope: Hero section only (or full page)
- Viewports: 1440×1400, 1920×1200+, mobile 390×844

## Tech Stack Discovery
- Framework: [Framer / Webflow / Custom]
- Animation: [Unicorn Studio / Three.js / Lottie / CSS / etc.]
- Fonts: [Font names + source URLs]

## Design Tokens
- Colors: [list with hex values]
- Typography: [h1, body, nav specs]
- Layout: [container width, heights, gaps]

## Assets to Extract
- [ ] Logo SVG
- [ ] Font files (self-host)
- [ ] Canvas/animation (embed or capture)
- [ ] Background images/videos

## Animation Strategy
- Hero entrance: [describe stagger sequence]
- Canvas/WebGL: [embed vs re-implement]
- Hover effects: [describe]

## Implementation Plan
1. Scaffold Vite + React + Tailwind
2. Build Navbar component
3. Build Hero component
4. Integrate animation
5. Polish + compare

Phase 3: Build

  1. Scaffold — npm create vite@latest . -- --template react, install Tailwind, set base for GitHub Pages
  2. Folder Structure:
    src/
      components/
        layout/    # Navbar.tsx, Footer.tsx
        sections/  # Hero.tsx, Features.tsx
        ui/        # Button.tsx, Badge.tsx, GlassCard.tsx
      assets/
        media/     # extracted videos, noise overlays, icons, SVG logos
        fonts/     # self-hosted .woff2 files
      styles/
        globals.css  # font-face, CSS variables
    
  3. Build Components — Navbar, Hero, with extracted design tokens. Map every value to Tailwind arbitrary values: text-[70px], tracking-[-2.2px], max-w-[900px]
  4. Integrate Animation — Embed or re-implement based on Phase 1 findings
  5. Add Framer Motion — Staggered entrance animations, hover effects, scroll triggers
  6. Center Layout — Always use max-w-[Xpx] mx-auto for large-screen centering

Framer Motion stagger pattern (covers 90% of hero animations):

import { motion } from 'framer-motion';

const container = {
  hidden: {},
  visible: { transition: { staggerChildren: 0.12, delayChildren: 0.1 } }
};

const fadeUp = {
  hidden: { opacity: 0, y: 30 },
  visible: { opacity: 1, y: 0, transition: { duration: 0.6, ease: [0.25, 0.46, 0.45, 0.94] } }
};

<motion.div variants={container} initial="hidden" animate="visible">
  <motion.div variants={fadeUp}><Badge /></motion.div>
  <motion.div variants={fadeUp}><h1>...</h1></motion.div>
  <motion.div variants={fadeUp}><p>...</p></motion.div>
  <motion.div variants={fadeUp}><Buttons /></motion.div>
</motion.div>

Phase 4: Compare & Polish

Side-by-Side Comparison
  1. Open the original site and your clone in separate tabs:

    // Tab 1: Original
    navigate("https://target.framer.ai/")
    resize_window(tab_id=1, width=1440, height=1400)
    computer(tab_id=1, action="wait", duration=2)
    computer(tab_id=1, action="screenshot")
    
    // Tab 2: Your clone
    navigate("http://localhost:5173")  // opens new tab
    resize_window(tab_id=2, width=1440, height=1400)
    computer(tab_id=2, action="wait", duration=2)
    computer(tab_id=2, action="screenshot")
    
  2. Compare all required viewports — desktop 1440×1400, large desktop 1920×1200+, and mobile 390×844

  3. Stitch for 1:1 comparison — Use Python to stitch screenshots side-by-side:

    python3 -c "
    from PIL import Image
    i1 = Image.open('/absolute/path/ref.png')
    i2 = Image.open('/absolute/path/local.png')
    h = min(i1.height, i2.height)
    i1 = i1.resize((int(i1.width * h / i1.height), h))
    i2 = i2.resize((int(i2.width * h / i2.height), h))
    dst = Image.new('RGB', (i1.width + i2.width, h))
    dst.paste(i1, (0, 0))
    dst.paste(i2, (i1.width, 0))
    dst.save('/absolute/path/combined.png')
    "
    

    Read the stitched image to spot remaining visual discrepancies.

  4. The Build→Screenshot→Fix Loop:

    • Screenshot clone + original → identify deltas with pixel positions ("Button is 116px wide, should be 90px", not "button is too wide")
    • Fix all deltas in one pass
    • Re-screenshot → repeat 2-3 rounds until matching
  5. Run the Quality Checklist (below) before declaring done


The 10 Gotchas

Real traps discovered cloning Framer/Webflow sites. Memorize these.

#GotchaSymptomSolution
1Framer nests text deeplynav a reports default browser styles: rgb(0,0,238), 12pxThe real style is on a nested <p>/<span>. Walk the DOM tree with TreeWalker (Script 1F).
2Layered gradient orbs, not radial blurBackground aura looks like a soft radial glowIt's two overlapping gradient divs with multi-stop linear gradients at specific angles, wrapped in a parent with opacity + blur(). Extract each orb separately (Script 5).
3Logos are data-URI backgroundsdocument.querySelectorAll('img') returns nothing for the trust carouselLogos are inline data:image/svg+xml URIs set as CSS background-image on <div>s. Query backgroundImage (Script 7).
4Multi-layer box-shadowsYour single shadow looks flat vs. the original's depthButtons can have 6 layers of rgba shadows. Extract the full boxShadow string verbatim (Script 2).
5Compound badge ('New' pill)Badge looks like one elementIt's an outer pill containing an inner colored pill + text. Build as nested components (Script 8).
6Star/particle backgroundsFaint texture behind hero you can't placeFull-width container at low opacity behind hero content. Rip as image/.webm or recreate with randomly-positioned absolute <div> dots.
7Negative letter-spacing everywhereType looks "looser" than originalFramer sites use negative tracking site-wide (e.g., h1 -2.2px, body -0.28px). Extract and apply per element with tracking-[-2.2px].
8Double text in Framer buttonsDOM shows "Book a callBook a call"Framer renders button text twice for a hover slide/swap animation. Render it once; optionally implement the hover text-swap with Framer Motion.
9getComputedStyle overloadContext window flooded, hallucinated valuesSnipe only needed properties. Never JSON.stringify(getComputedStyle(el)).
10Fluid wrapping ≠ originalHeadline wraps on a different wordExtract the container width and force it: max-w-[900px] (Script 4).

Browser-Use Agent Rules

#Rule
B1Screenshots are viewport-only — resize_window the height (e.g., 1400px) to fit a full section before screenshotting
B2javascript_tool returns strings — always wrap in an IIFE and JSON.stringify() your result. Returning a raw object gives [object Object]
B3Framer deep nesting — for any text style, use the TreeWalker pattern (Script 1F). Never trust the outer element's computed style
B4Wait after scroll/resize — always computer(tab_id, action="wait", duration=2) so animations/lazy content settle
B5Always pass tab_id — specify tab_id on every computer / javascript_tool / resize_window call

Sniper CSS Script Library

Copy-paste payloads for the AdaL browser-use agent. Each is an IIFE returning JSON.stringify(...). Pass as the text argument to javascript_tool(tab_id=1, action="javascript_exec", text="...").

Script 1: Typography Tokens

(() => {
  const el = document.querySelector('h1');
  const s = window.getComputedStyle(el);
  return JSON.stringify({ fontFamily: s.fontFamily, color: s.color, fontSize: s.fontSize, fontWeight: s.fontWeight, letterSpacing: s.letterSpacing, lineHeight: s.lineHeight }, null, 2);
})()

Script 1F: Framer-Aware Typography (TreeWalker to Deepest Text Node)

Why: nav a and many Framer headings report default browser styles. The real style is on a deeply nested <p>/<span>.

(() => {
  const root = document.querySelector('h1'); // change selector as needed
  if (!root) return "Not found";
  const target = (root.textContent || '').trim();
  let el = root;
  while (true) {
    const child = Array.from(el.children).find(c => (c.textContent || '').trim() === target);
    if (!child) break;
    el = child;
  }
  const s = window.getComputedStyle(el);
  return JSON.stringify({ matchedTag: el.tagName, fontFamily: s.fontFamily, color: s.color, fontSize: s.fontSize, fontWeight: s.fontWeight, letterSpacing: s.letterSpacing, lineHeight: s.lineHeight }, null, 2);
})()

Script 2: Bounding Box, Overflow & Full Box-Shadow

(() => {
  const btn = Array.from(document.querySelectorAll('a, button')).find(l => (l.textContent||'').includes('Get Started')) || document.querySelector('a, button');
  if (!btn) return "Not found";
  const r = btn.getBoundingClientRect();
  const s = window.getComputedStyle(btn);
  return JSON.stringify({ width: r.width, height: r.height, display: s.display, padding: s.padding, borderRadius: s.borderRadius, overflow: s.overflow, background: s.background, boxShadow: s.boxShadow }, null, 2);
})()

Script 3: Glassmorphism & Backgrounds

(() => {
  const el = document.querySelector('nav');
  const s = window.getComputedStyle(el);
  return JSON.stringify({ background: s.background, backdropFilter: s.backdropFilter || s.webkitBackdropFilter, border: s.border, borderRadius: s.borderRadius, height: el.getBoundingClientRect().height, padding: s.padding }, null, 2);
})()

Script 4: Forced Line-Breaks (Container Width)

Why: a clone looks fake if text wraps differently. Extract the exact width and lock it.

(() => {
  const el = document.querySelector('h1');
  const r = el.getBoundingClientRect();
  return JSON.stringify({ containerMaxWidth: r.width }, null, 2);
})()

Script 5: Abstract Glows & Layered Orbs

Why: auras are usually hard-shaped, multi-stop linear gradients with precise rotation + a tight blur — not a radial blob.

(() => {
  const hero = document.querySelector('section') || document.body;
  const orbs = Array.from(hero.querySelectorAll('div')).filter(d => {
    const s = getComputedStyle(d);
    return s.position === 'absolute' && s.backgroundImage.includes('gradient');
  }).slice(0, 6);
  return JSON.stringify(orbs.map(d => {
    const s = getComputedStyle(d); const r = d.getBoundingClientRect();
    return { size: Math.round(r.width)+'x'+Math.round(r.height), background: s.backgroundImage, transform: s.transform, filter: s.filter, opacity: s.opacity, mixBlendMode: s.mixBlendMode };
  }), null, 2);
})()

Script 6: Named Framer Layer (by data-framer-name)

(() => {
  const el = document.querySelector('[data-framer-name="Big Circle"]');
  if (!el) return "Not found";
  const s = window.getComputedStyle(el);
  return JSON.stringify({ background: s.backgroundImage, transform: s.transform, filter: s.filter, opacity: s.opacity }, null, 2);
})()

Script 7: Data-URI Logo Extraction (Trust Carousels)

Why: logos are CSS background-image data-URIs on <div>s, invisible to img queries.

(() => {
  const nodes = Array.from(document.querySelectorAll('div')).filter(d => getComputedStyle(d).backgroundImage.startsWith('url("data:image'));
  return JSON.stringify(nodes.slice(0, 20).map((d, i) => {
    const bg = getComputedStyle(d).backgroundImage;
    return { index: i, size: Math.round(d.getBoundingClientRect().width)+'x'+Math.round(d.getBoundingClientRect().height), uriPreview: bg.slice(0, 80) + '...', fullLength: bg.length };
  }), null, 2);
})()

To save: read the full backgroundImage, strip url(" / "), URL-decode the data:image/svg+xml,... payload, and write it to src/assets/media/logo-N.svg via bash.

Script 8: Compound Component Audit (Badge / Pill-in-Pill)

(() => {
  const inner = Array.from(document.querySelectorAll('div, span')).find(e => (e.textContent||'').trim() === 'New');
  if (!inner) return "Not found";
  const outer = inner.parentElement;
  const dump = el => { const s = getComputedStyle(el); return { background: s.background, borderRadius: s.borderRadius, padding: s.padding, color: s.color }; };
  return JSON.stringify({ outer: dump(outer), inner: dump(inner) }, null, 2);
})()

Script 9: Pseudo-Element Extraction

(() => {
  const el = document.querySelector('selector'); // change as needed
  if (!el) return "Not found";
  const s = window.getComputedStyle(el, '::before');
  return JSON.stringify({ content: s.content, background: s.background, width: s.width, height: s.height, transform: s.transform, filter: s.filter, opacity: s.opacity }, null, 2);
})()

Script 10: Canvas Recorder (Last Resort for WebGL)

When a WebGL Canvas shader is too obfuscated to intercept, record the GPU output directly and use it as a looping background video:

(() => {
  return new Promise((resolve) => {
    const canvas = document.querySelector('canvas');
    if (!canvas) return resolve("No canvas found.");
    const stream = canvas.captureStream(30);
    const recorder = new MediaRecorder(stream, { mimeType: 'video/webm' });
    const chunks = [];
    recorder.ondataavailable = e => { if (e.data.size > 0) chunks.push(e.data); };
    recorder.onstop = () => {
      const blob = new Blob(chunks, { type: 'video/webm' });
      const url = URL.createObjectURL(blob);
      const a = document.createElement('a');
      a.href = url; a.download = 'framer_perfect_loop.webm';
      document.body.appendChild(a); a.click(); document.body.removeChild(a);
      resolve("Recorded 8s and downloaded: framer_perfect_loop.webm");
    };
    recorder.start();
    setTimeout(() => recorder.stop(), 8000);
  });
})()

Design Token Extraction Template

Document every extracted value in this format. Fill it in during discovery, reference it during build.

Colors

TokenHexRGB
Page background#000000rgb(0,0,0)
Primary accent#814AC8rgb(129,74,200)
White text#FFFFFFrgb(255,255,255)
Description gray#CCCCCCrgb(204,204,204)

Typography

ElementSizeWeightLine-heightLetter-spacingNotes
H170px60077px-2.2pxmax-width ~900px
Body / nav14px50016.8px-0.28px
Description18px50027px-0.36px

Font family: Figtree, "Figtree Placeholder", sans-serif (load real Figtree; ignore the Placeholder shim).

Spacing & Components

ComponentValue
Navbar height~65px
Navbar padding10px 40px
Button border-radius6px
Button padding9px 13px
Badge outerborder-radius 20px, padding 2px 10px 2px 2px
Badge innerborder-radius 12px, padding 4px 8px

Tailwind Mapping (copy-paste pattern)

<h1 className="text-[70px] font-semibold leading-[77px] tracking-[-2.2px] max-w-[900px] text-white">
<span className="text-[14px] font-medium leading-[16.8px] tracking-[-0.28px]">
<button className="rounded-[6px] px-[13px] py-[9px] bg-[#814AC8] text-white">

Quality Checklist

Verify your clone before declaring done. Compare side-by-side with the reference at 1440px and 390px.

Layout & Structure

  • Semantic HTML (nav, section, h1, button) — no copied div-soup
  • Section order and spacing match
  • Layout centers on large screens (max-w-[Xpx] mx-auto)
  • Responsive breakpoints behave like the original

Typography

  • Correct font family loaded (not a fallback)
  • Font sizes, weights, line-heights match extracted tokens
  • Negative letter-spacing applied per element
  • Headline wraps on the same word (forced max-w-[…])

Color & Surfaces

  • Background color exact
  • Translucent surfaces use the exact rgba(...)
  • Text colors match

Effects

  • Gradient orbs reproduced as separate layered divs (size, angle, blur, opacity)
  • Multi-layer box-shadows copied verbatim
  • Glassmorphism (backdrop-filter) present where used
  • Star/particle/noise background layer present at correct opacity

Components

  • Compound badge built as nested pills
  • Buttons render text once (no Framer double-text)
  • Hover micro-interactions implemented

Assets

  • Trust/logo carousel extracted from data-URIs
  • Inline SVGs saved as components
  • WebGL/canvas backgrounds ripped to .webm and looping

Animation

  • Entrance animation plays on load (stagger)
  • Canvas/WebGL animation runs (if applicable)
  • Hover effects work (buttons, nav links)

Final

  • Side-by-side screenshot diff shows 90%+ fidelity at 1440×1400
  • Large desktop (1920×1200+) confirms centered layout
  • Mobile screenshot passes or is explicitly out of scope
  • No console errors; fonts/assets load without flashes

Speedrun Prompt

Copy-paste this to a browser-use agent to clone any hero section fast:

Clone the hero section of [TARGET_URL].

1. Navigate to the target. Resize to 1440x1400. Screenshot.
   Also capture 1920x1200 and 390x844 (mobile).

2. Extract ALL design tokens using javascript_tool:
   - Page background color
   - Navbar: bg, height, padding, link styles (use TreeWalker for real text styles)
   - H1: font-family, size, weight, line-height, letter-spacing, color, max-width
   - Description: same properties
   - Buttons: bg, color, padding, border-radius, box-shadow (capture ALL layers)
   - Badge/tags: structure, bg, border-radius, padding
   - Decorative elements: gradients, transforms, blur, opacity
   - Trust/logo bar: text styles + logo extraction (check data-URI backgrounds!)

3. Run the animation detection scanner. Identify the animation tech and strategy.

4. Extract assets:
   - Logo SVG: querySelector('svg').outerHTML → save to file
   - Trust logos: filter divs by backgroundImage data:image → decode → save
   - Fonts: find .woff2 URLs in @font-face or performance entries

5. Scaffold: npm create vite@latest . -- --template react && npm install tailwindcss
   Build ALL components in one pass using extracted tokens.
   Map every value to Tailwind arbitrary values.

6. Start dev server. Open clone in new tab. Screenshot both.
   Compare and fix with pixel-position-specific deltas. Repeat 2-3 times.

Mandatory: Two-Agent Builder+Evaluator Pattern

The builder MUST NOT evaluate its own output. Always use two separate browser-use workers orchestrated by the AdaL Engineer supervisor. This is not optional — a single agent that both builds and judges its own clone produces measurably worse results.

Recommended Models (Cost-Effective + Visual + Coding)

Cloning is token-intensive (screenshots, DOM extraction, many fix rounds). Use cost-effective models that support vision (for screenshot comparison) and coding (for React/Tailwind):

ModelInput $/MOutput $/MVisionWhy
MiniMax M3 (recommended)$0.30$1.20✅Cheapest, strong coding, multimodal — best value for token-heavy clone sessions
Muse Spark 1.1$1.25$4.25✅Good agentic coding, always-on reasoning — solid alternative
Grok 4.5$2.00$6.00✅Strongest reasoning, but 4-5× the cost of MiniMax M3

Default recommendation: Use minimax-MiniMax-M3 for both Builder and Evaluator workers. If you need stronger reasoning for a complex clone, use grok-4.5 for the Evaluator only (it's the adversarial judge — reasoning quality matters most there).

# Builder — cost-effective, good at coding + vision
adal_worker_start(
  work_dir="/path/to/project",
  command=["adal", "--yolo", "--model", "minimax-MiniMax-M3", "--agent-mode", "browser-use"],
  launch_mode="attach", alias="builder"
)

# Evaluator — adversarial judge, can upgrade to grok-4.5 for harder cases
adal_worker_start(
  work_dir="/path/to/project",
  command=["adal", "--yolo", "--model", "minimax-MiniMax-M3", "--agent-mode", "browser-use"],
  launch_mode="attach", alias="evaluator"
)

Worker 1 — Builder (Browser-Use)

One agent does the full visual loop: navigate target, screenshot matrix, extract CSS/fonts/assets, run animation scanner, scaffold and build the clone.

Worker 2 — Evaluator (Browser-Use)

Separate session, adversarial prompt. After the builder finishes, the evaluator opens the live target and the clone in separate tabs, screenshots both at every viewport, compares pixel positions/colors/fonts/animation/content verbatim, and reports every failure with severity + file/line. Its system belief is "this clone is broken — prove it."

Planning Contract (before any clone code)

  1. Builder writes team-log/builder_plan.md (implementation approach, files, component breakdown, font/animation strategy)
  2. Evaluator writes team-log/test_plan.md (visual fidelity matrix, animation verification, design-token assertions, responsive edge cases)
  3. Engineer mediates — sends each plan to the other for critique, then writes team-log/contract.md with status Approved to Build
  4. Builder codes only after the contract is accepted. Evaluator evaluates only after builder reports done.

Build→Screenshot→Fix Loop

Each round:

  1. Evaluator screenshots clone + original at matching viewports
  2. Reports specific deltas with pixel positions: "H1 is 15px too high (clone y=579, original y=589)"
  3. Builder applies all fixes in one pass
  4. Repeat until the evaluator returns ACCEPT

Deployment Checklist

  • vite.config.js has base: '/repo-name/'
  • .github/workflows/deploy.yml configured for GitHub Pages
  • GitHub Pages enabled: gh api repos/OWNER/REPO/pages -X POST -f build_type=workflow
  • npm run build passes
  • Committed and pushed to main
  • Workflow run succeeded

Troubleshooting

  • "The background animation is missing!" → You assumed it was CSS. Run the animation scanner (Step 4) to find the hidden <video>, <canvas>, or library.
  • "The Button looks totally different!" → Extract the outerHTML of the button's parent. You likely missed overlapping blurred divs or 6-layer box shadows.
  • "The Text Wraps Wrong!" → You let the browser decide fluidly. Extract the exact bounding box width (Script 4) and hardcode it (max-w-[...]).
  • "Nav link styles look wrong" → Framer nests text deeply. Use the TreeWalker script (Script 1F) to find the real styled element.
  • "Logos are missing" → They're data-URI CSS backgrounds, not <img> tags. Use Script 7.
  • Save Paths: Always use absolute paths for saving screenshots and assets.
  • Zombie Browsers: If the browser-use agent is stuck, try closing and reopening the tab via tabs_context.

Ethical/Legal Note: When cloning websites, ensure you have the appropriate permissions. For learning purposes, focus on reverse-engineering the structural layout and design systems (spacing, colors, typography) rather than ripping proprietary copy, branding, or gated assets.

codegraph

Turn a codebase into a map a human can actually read.

The goal is not a graph that shows off how complex the code is — it is a graph that quietly teaches someone how the pieces fit together.

When to Use

Trigger on requests like:

  • "help me understand this codebase" / "I just joined this project"
  • "map / visualize / diagram this repo or its architecture"
  • "what are the entry points?" / "how does data flow through this?"
  • "generate an onboarding guide" / "where do I start reading?"
  • "show me the dependency graph" / "find circular dependencies"
  • "which files are most important here?"

Do not use this for a single-file explanation — just read the file.

Core Design (read this before running anything)

Three stages. Two are deterministic; only the middle one uses your intelligence.

1. scan.py    codebase  ->  graph.json + digest.md     deterministic, no LLM, no network
2. YOU        digest.md ->  enrich.json                 summaries, layer fixes, tours
3. render.py  both      ->  codegraph.html              one portable self-contained file
              (overview.py collapses the graph into the overview diagram en route)

Why this split matters — do not violate it:

StageOwnerGuarantee
Structure (files, imports, calls, metrics, cycles)scan.pyReproducible. Same commit always yields the same edges.
Meaning (what a file is for, tours)YouOnly a model can write this.
Delivery (layout, validation, HTML)render.pyValidated before write; a broken artifact never replaces a good one.

Never hand-write graph.json. It is machine output. You only ever write enrich.json. Never invent files, symbols, or relationships. Every id you emit must already exist in the digest.

Instructions

Step 1 — Scan (always start here)

python3 <skill>/scripts/scan.py <repo> -o <repo>/.codegraph

Nothing to install: Python 3.8+ stdlib only. ~2s for 230k LOC.

Useful flags:

  • --max-files N (default 4000) — raise it if output warns about truncation
  • --symbols-for N (default 250) — extract function/class nodes for the N most important files
  • --no-calls — skip heuristic cross-file call edges (faster, fewer false positives)

Then read digest.md, not graph.json. The digest is a compact briefing (entry points, directory map, ranked-importance table, cycles, dependencies, layer counts). graph.json can be megabytes and will flood your context for no benefit.

Step 2 — Enrich (this is your real work)

Write <repo>/.codegraph/enrich.json:

{
  "project": { "description": "1-3 sentences: what this codebase IS and does." },
  "nodes": {
    "file:src/server.ts": {
      "summary": "HTTP entry point. Wires middleware, mounts routers, starts the listener.",
      "layer": "entry",
      "tags": ["bootstrap", "http"]
    }
  },
  "layers": { "service": "Domain logic; no HTTP or SQL touches this layer." },
  "tours": [
    {
      "title": "Request lifecycle",
      "description": "Follow one HTTP request end to end.",
      "steps": [
        { "nodeId": "file:src/server.ts", "note": "Request arrives; middleware chain runs here." },
        { "nodeId": "file:src/routes/user.ts", "note": "Routing picks a handler." }
      ]
    }
  ]
}

Rules:

  1. Node ids must come from the digest verbatim (file:..., mod:..., sym:..., ext:...). Unknown ids are dropped with a warning — silent quality loss.
  2. Summarize the top ~30-60 ranked files first. Full coverage of a large repo is rarely worth the tokens; importance ordering already tells you what matters.
  3. Write what it is + why it exists, not a restatement of the filename. Bad: "Utils file with utilities." Good: "Retry/backoff helpers shared by every outbound API client."
  4. Fix wrong layers. scan.py guesses from paths and says so. If core/ is really data access, override it.
  5. At least one tour, 3-6 steps. Tours are the single highest-value output for onboarding — they encode reading order, which a graph alone cannot.
  6. Read actual source before summarizing important files. Do not infer from names alone.

Scale guidance: read the top files in batches, and prefer breadth (many short, correct summaries) over depth (a few essays).

Step 3 — Render and verify

python3 <skill>/scripts/render.py --in <repo>/.codegraph --open
  • Validates first; on failure it prints exact reasons and writes nothing.
  • --validate-only to check without writing; --strict to fail on warnings.
  • Output: <repo>/.codegraph/codegraph.html — one file, no CDN, works offline, safe to commit or send.

Always report to the user: node/edge counts, how many summaries and tours landed, and the artifact path.

What the artifact gives the reader

Three linked views in one file, cycled with Tab:

  1. overview — architecture diagram (module boxes on layer bands, flowing connectors, a comet on the primary dependency path). Answers "what are the parts?"
  2. star map — the same modules as an orbitable galaxy field, brightness = importance (Physics-atlas idiom: hot cores, double halos, diffraction spikes). Answers "where is the weight of this system?" Drag to orbit · scroll to dolly · shift-drag to pan · 0 to reset, with damped inertia and a slow idle auto-rotate — the same interaction contract as the atlas' OrbitControls, implemented as a projected 2.5D disc in Canvas so the artifact stays one dependency-free file (no three.js, no WebGL). Touch: one finger orbits, two pinch-zoom. Modules carry real z depth, so tilting reveals structure and distant galaxies fade.
  3. explore — an expandable tree, opened one level at a time. It starts at the project root showing only the top folders, and each click reveals the next level: folders -> files -> symbols. A +N badge on every collapsed node says how much is inside, so nothing is hidden silently. The rail's Start here list jumps straight to a real entry point. H toggles back to the flat all-at-once graph.

Clicking a module box or a galaxy drills into explore, focused on that module's files.

Every node says something (no LLM required)

scan.py reads the codebase's own docstrings and file-header comments — module docstrings, JSDoc blocks, Go/Rust line comments — and uses them as node summaries. Boilerplate (shebangs, licence headers, coding: lines) is filtered, and text is cut at Args:/Returns: so the summary stays one sentence.

Measured on a real 109k-LOC repo: 87% of files described with zero model calls. The agent's enrich.json overrides these where it can say something better, and the inspector labels which is which — an extracted summary is marked from the file's docstring, so provenance is never ambiguous. Nodes also list the symbols they define.

This matters because a graph of unlabelled dots teaches nothing: before this, 100% of nodes showed only LOC and degree.

The overview is derived, never authored: tiers, boxes, link weights and the journey all come from the deterministic scan, so the diagram cannot drift from the real code. Modules holding only config/docs are omitted (scaffolding is not architecture), and links are capped so a dense graph does not become a hairball.

CapabilityWhy it helps understanding
Overview diagramThe 5-second read: what this system is made of, and how it flows
Click a module → exploreOverview answers "where?", explore answers "how?"
3 detail levels (Folders / Files / Symbols)Progressive disclosure — start coarse, drill only where needed
Layer bands (entry → api → service → data → util)Shows architecture, not just a hairball
Click any nodeSummary, metrics, and navigable dependency lists both directions
Search (/)Find by name, path, summary text, or tag
Focus dimmingIsolates one node's actual neighborhood
entries toggle"Where do I start reading?" answered instantly
cycles toggleCircular dependencies = refactor targets
Guided tours (P, [, ])Teaches reading order — the thing new devs lack most
calls / deps togglesCross-file call edges; external dependency surface
Theme toggle (T), fit (0)Presentable in a README, PR, or onboarding doc
Flowing comet packetsDependency direction becomes visible motion, not a static arrow
Breathing halosEntry points, tour steps, and the selection pulse to draw the eye
Motion toggle (space, ⏸)Pause for screenshots; auto-off under prefers-reduced-motion
TabFlip between overview and explore
simplify (F)Folds edges of hub files — the single biggest declutter (~−48%)
focus (N)Shows only the selection and its top neighbours (~−87%)

Asking questions mid-explore

The artifact is offline and carries no API key, so it does not pretend to host a chat. Instead every node has an ask ▸ button that copies a complete prompt — path, summary, LOC/fan-in/fan-out, the symbols it defines, and both edge directions — ready to paste into any LLM. That is the context a model would otherwise have to guess at.

Deliberately NOT done: embedding an API key in the HTML. The file gets committed and shared, so a key in it is a leak waiting to happen.

Keeping explore readable

Dense repos produce a hairball, so the explore view starts simplified and lets the reader add detail back:

  • Tests hidden by default — often half a repo's files, but not its architecture.
  • Hub folding on by default. A handful of files carry most of the clutter (in one 109k-LOC repo, 10 files owned 23% of all edge endpoints). Their edges collapse to a ⋯n badge; click it to reveal them. Nothing disappears silently.
  • calls edges off by default — they typically outnumber imports ~5:1.
  • Distance LOD — zoomed far out the lines fade and the layer bands carry the structure (borrowed from Physics-atlas's uReveal).
  • Neighbourhood focus (N) — one node's direct relations only, capped so an extreme hub cannot re-create the hairball.

Measured on a 109k-LOC repo: 628 → 172 edges (−73%) at defaults, −87% in focus mode.

Why not 3D? It looks like the answer but is not: the clutter is edge count, not missing dimension, and 3D adds occlusion, rotation disorientation, and a ~600KB three.js dependency that breaks the single-file offline contract. LOD plus folding solves the actual problem.

Animation

The artifact is alive by default, in the glowmotion/deep-field idiom:

  • Comet packets travel source → target along each edge with an exponential fading trail, so import direction reads at a glance. Colour encodes kind (blue = imports, violet = calls, gold = the active tour path).
  • Focus redirects traffic: selecting a node concentrates packets on its neighbourhood and fades the rest to 6%.
  • Breathing halos ring entry points, tour steps, and the selection.
  • Parallax starfield drifts behind the graph as you pan (dark theme only; the light theme stays print-clean).

Performance is decoupled from graph size: the static scene is painted once on a base canvas and motion lives on a separate overlay, with packets capped at 190. Measured 60fps on a 2,660-node graph. Motion pauses on space / ⏸ and is off automatically when the viewer prefers reduced motion.

Graph Vocabulary

Node ids are typed prefixes (stable, so deep links and enrichment keep working):

PrefixMeaning
mod:<dir>Folder / module
file:<path>A file
sym:<path>#<name>:<line>Function / class / type
ext:<name>External dependency

Edges: contains (hierarchy), imports (resolved, reliable), calls (heuristic — name-based, unique-match only), depends_on (external), inherits.

Layers: entry, ui, api, service, data, util, config, infra, test, docs, other.

Importance = 0.55·PageRank(imports) + 0.25·fan-in + 0.20·size. It answers "what should I read first?"

Languages

Python, JS/TS (+JSX/TSX), Vue, Svelte, Go, Rust, Java, Kotlin, Scala, Ruby, PHP, C#, C/C++, Objective-C, Swift, shell, SQL, Terraform, GraphQL, Protobuf — plus config/docs/Docker as context nodes.

Import resolution is real (relative paths, package roots, @/ aliases, Go modules, Rust crate::/mod, JVM packages). Extraction is regex-based, not a full type-checking AST: excellent for imports and definitions, approximate for call edges. Tell the user this when they ask about call accuracy — never present inferred calls as verified fact.

Honest Limits

  • calls edges are heuristic (unique unambiguous names only; common names like get/run are deliberately skipped). Imports are trustworthy; calls are a hint.
  • Dynamic imports, DI containers, reflection, and runtime registration are invisible to static scanning.
  • Generated code, minified bundles, and lockfiles are excluded on purpose.
  • Layers are path heuristics until you override them. Say so rather than overclaiming.

Refresh

Re-run scan.py then render.py. enrich.json is separate from graph.json, so existing summaries survive a re-scan — only ids that no longer exist get dropped. Commit .codegraph/ to let teammates open the graph with zero setup and no API key.

Create Skill

Use this skill when the user asks to create a skill, make a skill, add a new skill, or similar requests.

When to Use

Trigger when user mentions:

  • "create a skill"
  • "make a skill"
  • "add a new skill"
  • "write a skill"
  • "scaffold a skill"
  • "set up a skill"

Step 1: Clarify Skill Type

Always ask the user which type of skill they want to create:

TypeLocationVisibilityUse Case
Personal~/.adal/skills/<name>/Only youCustom workflows, personal preferences
Project.adal/skills/<name>/Team (via git)Team conventions, project-specific patterns
PluginGitHub repoPublicCommunity-shareable, reusable across projects

Example prompt:

What type of skill would you like to create?

  1. Personal skill (~/.adal/skills/) - Just for you, not shared
  2. Project skill (.adal/skills/) - Shared with your team via git
  3. Plugin skill (GitHub repo) - Public, shareable with the community

Which type? (1/2/3)

Step 2: Gather Skill Details

Ask for:

  1. Skill name - lowercase, hyphenated (e.g., my-workflow, team-conventions)
  2. Description - Brief explanation of what it does and when to use it
  3. When to trigger - Keywords or scenarios that should activate this skill

Step 3: Create the Skill Structure

For Personal Skills (~/.adal/skills/)

mkdir -p ~/.adal/skills/<skill-name>

Create SKILL.md with required YAML frontmatter:

---
name: <skill-name>
description: <Brief description>
author: <your-name or org>
version: 1.0.0
---

# <Skill Title>

## When to Use
<Describe trigger scenarios>

## Instructions
<Step-by-step guidance for the agent>

⚠️ REQUIRED: The --- YAML frontmatter block is mandatory. Skills without it will fail to load. At minimum, include name and description.

For Project Skills (.adal/skills/)

mkdir -p .adal/skills/<skill-name>

Same SKILL.md format. Remember to commit to git for team sharing.

For Plugin Skills (GitHub)

  1. Create a GitHub repository with this structure:

    <repo>/
    ├── .claude-plugin/
    │   └── marketplace.json     # Required location for Claude Code compatibility
    ├── skills/
    │   └── <skill-name>/
    │       └── SKILL.md
    └── README.md
    
  2. marketplace.json (MUST be in .claude-plugin/ directory):

    {
      "name": "my-marketplace-name",
      "owner": {
        "name": "Your Name or Org",
        "email": "contact@example.com"
      },
      "metadata": {
        "description": "My collection of skills",
        "version": "1.0.0"
      },
      "plugins": [
        {
          "name": "my-plugin",
          "description": "Plugin description",
          "source": "./",
          "skills": ["./skills/skill-name"]
        }
      ]
    }
    

    Critical fields:

    • owner: Object with name and email (required by Claude Code)
    • metadata: Wrapper for description and version
    • plugins[].source: Path to skills root (use "./" for repo root)
    • plugins[].skills: Two formats supported:
      • Array (explicit): ["./skills/xlsx", "./skills/docx"] - list specific skill directories
      • String (scan): "skills" or "./" - recursively scan for SKILL.md files
  3. Installation commands:

    # Add marketplace
    /plugin marketplace add <owner>/<repo>
    
    # Direct install (marketplace-name from marketplace.json "name" field)
    /plugin install <plugin-name>@<marketplace-name>
    
  4. IMPORTANT: Keep marketplace.json in sync!

    Every time you add a new skill to the plugin, update the skills array in marketplace.json:

    "skills": ["./skills/create-skill", "./skills/new-skill-name"]
    

    Without this, the skill won't be discoverable via /skills command after plugin installation.

Step 4: Verify Installation

After creating:

  • Run /skills to verify the skill appears
  • Test by asking the agent to perform a task the skill should handle

Advanced Options

If the user wants multi-file skills, guide them on:

  • REFERENCE.md - Detailed documentation
  • scripts/ - Executable utilities (Python, bash)
  • Link supporting files from SKILL.md

Example Interaction

User: "Create a skill for our API conventions"

Agent: "What type of skill would you like?

  1. Personal - just for you
  2. Project - shared with team via git
  3. Plugin - public on GitHub"

User: "Project"

Agent: "I'll create .adal/skills/api-conventions/. What conventions should it include?"

Finger Frame AI

Turn a local video of the two-hand finger-frame gesture into an H.264 MP4 where the area inside the fingers reveals an AI-restyled version of the scene.

The bundled pipeline uses:

  1. Gemini Omni to restyle the existing clip while asking it to preserve timing, motion, framing, pose, and expression.
  2. MediaPipe Hand Landmarker to track both index fingers and thumbs.
  3. FFmpeg/OpenCV to composite the restyled video into the tracked quadrilateral and retain source audio.

When to Use

Trigger when the user asks to:

  • Apply a finger-frame, hand-frame, or fingers-as-a-window video effect.
  • Put an anime, claymation, watercolor, CGI, or custom AI world inside a finger gesture.
  • Run the Finger Frame AI video pipeline on a local clip.

Do not substitute Veo video generation. This effect needs a restyled version of the existing timeline so it can align with hand tracking from the source.

Required Input and Consent

Ask for the absolute local source-video path if it was not supplied.

The Gemini Omni request can take several minutes and may incur Google API charges. Before calling it, clearly state that and obtain confirmation unless the user already authorized the paid generation in the current conversation.

A key with gemini-omni-flash-preview access and quota is required. Never ask the user to paste a key into chat. Ask them to configure it in the terminal that launches AdaL:

export GEMINI_API_KEY='...'

GOOGLE_API_KEY is also supported. Never print, log, commit, or place a key in command arguments.

Instructions

Set <skill> to this skill directory, then perform these steps.

1. Check readiness

python3 <skill>/scripts/process.py --check

This check does not install packages, upload media, or call Gemini. If FFmpeg is missing, tell the user to install ffmpeg and ffprobe; do not attempt privileged installation.

2. Validate the source

Confirm the file exists. The clip should clearly show two hands forming opposing index-and-thumb “L” shapes. Preserve the original file.

Short clips are faster and cheaper. Sources larger than 15 MB are automatically compressed to a temporary 720p H.264 upload copy; the original remains untouched.

3. Generate

Default cyberpunk-styled 3D animated-movie look:

python3 <skill>/scripts/process.py "/absolute/path/to/input.mov"

Custom style:

python3 <skill>/scripts/process.py "/absolute/path/to/input.mov" \
  --prompt "Transform the scene into hand-painted watercolor animation while preserving the original motion and framing."

Optional output controls:

python3 <skill>/scripts/process.py input.mp4 \
  --output /absolute/path/to/result.mp4 \
  --keep-stylized

The runner automatically:

  • Creates/reuses <skill>/.venv.
  • Installs bundled Python requirements when missing.
  • Prompts for a hidden, non-persisted key only in an interactive terminal.
  • Creates and cleans up an oversized-source working copy.
  • Runs Gemini Omni restyling and local finger-frame compositing.
  • Deletes the intermediate fully stylized video unless --keep-stylized is set.
  • Writes the default result beside the source as <source>-finger-frame.mp4.

In headless AdaL, always provide the video path and set the key in AdaL's launching environment because hidden prompts require a terminal.

4. Verify and report

After completion, run ffprobe on the final file. Report:

  • Absolute output path
  • Duration
  • Resolution and frame rate
  • Video/audio codecs
  • File size

Do not claim success unless the file exists, is non-empty, and FFmpeg can decode it without errors.

Error Handling

  • HTTP 429 / quota 0: Stop. Ask the user to enable billing/quota or configure another key. Do not retry repeatedly.
  • Authentication failure: Ask the user to replace the locally configured key. Never request it in chat.
  • No tracked frame: Explain that both hands and spread index/thumb shapes must be visible.
  • Large upload still exceeds limit: Ask the user to trim the clip or explicitly choose a larger --max-upload-mb only if their API supports it.
  • Generation drift: Explain that Omni is generative and cannot guarantee mathematical frame-perfect alignment.
  • Interrupted run: Preserve the original and remove only pipeline-created temporary media.

Glowmotion

Create premium animated technical diagrams as single self-contained HTML files. Glowmotion combines a deterministic layout engine (dashmotion lineage: the script computes every coordinate and route, mechanized checkers verify the result) with a lanshu-style premium finish (glow-trail dots, pulsing module halos, grain + vignette, icon glyphs, title capsule) — implemented entirely as vector SVG/CSS/SMIL, so the output stays a few KB, scales losslessly, respects reduced motion, and opens in any browser straight from the filesystem.

Requires python3 (pure stdlib — no pip installs). There is no hand-layout fallback: the engine owns all geometry.

Step 1 — Pick the mode and theme

User wantsMode
Steps, sequence, branching, state transitions ("what happens, in what order")flow
Components, services, containment, topology ("what the system is made of")architecture

Mixed request → architecture; the animated journey is the flow.

Themes are light/dark switchable by default. Every generated file ships both a dark and a light palette and a ☀/☾ toggle button (top-right, next to pause); it opens following the viewer's OS prefers-color-scheme. You choose which two palettes pair up:

  • darkTheme (default midnight) — dark options: midnight (deep navy, emerald flow), neon (pure-black canvas, green/purple/cyan/amber), aurora (teal/violet on deep slate).
  • lightTheme (default daylight) — light options: daylight (soft blue-grey paper, saturated strokes, print-friendly). (only light theme today)
  • defaultMode: "auto" (default, follow OS) | "dark" | "light" — which side the file opens on. Set "light" when the user asks for a light diagram.
  • themeToggle: false — bake a single fixed theme (from theme/darkTheme), no button. Only when the user explicitly wants one locked look.

Legacy theme (single key) still works: a light value fills the light slot, a dark value the dark slot, the other slot takes its default — still switchable. Pick dark palettes by context: neon for landing-page drama, midnight for docs, aurora for data/ML topics.

Mermaid input — if the request contains Mermaid source (```mermaid block, .mmd file, or pasted code): supported types are flowchart/graph and stateDiagram-v2; say so and offer alternatives for others. Keep every node, edge, group, and legend label verbatim — never reword, merge, or add punctuation; Step 3's fidelity check compares exactly. Layout is always recomputed top-down regardless of the source's declared direction.

Step 2 — Author the graph, render the file

You author a semantic graph JSON — structure, types, journeys, copy — and the engine does everything else. Full contract in references/graph-format.md (read it before your first graph in a session). The essentials:

  1. Parse the request (or the Mermaid source) into the graph JSON: nodes (type for arch, shape only for flow pills/decisions, tier only for multi-group arch), edges (kind: sync/async/main/static), groups, 1–4 journeys (the animated request paths — always author at least one; the checker fails a diagram with no traveling dot), and the copy: title, titleHighlight (capsule phrase), subtitle, arch summary of exactly three cards, optional signature.
  2. Write the JSON to a temp path (mktemp/$TMPDIR), never the output folder — it is a throwaway intermediate.
  3. Render: python3 <skill-dir>/scripts/layout.py graph.json --render <topic>-glowmotion.html. The output is the complete deliverable: geometry, both theme palettes + ☀/☾ toggle, glow/trail/halo animation layer, icons, legend, cards, pause toggle, reduced-motion handling, ARIA wiring.

To change anything, edit the JSON and re-render (cheap, deterministic); for a one-off wording tweak, edit the emitted HTML directly. Never hand-compute coordinates and never write the HTML from scratch.

Step 3 — Verify before delivering (non-negotiable)

The file is done when the checkers say so — never verify by eyeballing the code or opening a browser/screenshot; label drift and geometry errors are invisible to the eye.

python3 <skill-dir>/scripts/check_diagram.py <your-file>.html

Detects: partial overlaps (C1), connectors through boxes (C2), dash-loop seams (C3), out-of-viewBox (C4), dots off their line (C5), black-fill paths (C6), endpoint pierce (C7), dangling SMIL begin refs (C8), foreign node inside a group box (C9), and a missing/overstuffed animation layer (C10). Fix every violation and re-run until it prints 0 violations — usually by editing the graph JSON and re-rendering.

If the input was Mermaid, also run the fidelity check and fix to PASS:

python3 <skill-dir>/scripts/check_fidelity.py <source>.mmd <your-file>.html

Deliver only after a clean pass. Tell the user the file opens directly in any browser, has a ☀/☾ light-dark toggle and a ⏯ pause button, and honors reduced-motion preferences.

GIF/MP4 export (only if asked)

Never render frames by hand. Screen-record the open file, or headless: npx timecut <file.html> --viewport=1200,900 --duration=3 --fps=30 --output=out.mp4 then ffmpeg -i out.mp4 out.gif. A 3s capture loops seamlessly when all durations divide 3s.

Output contract

One self-contained .html: embedded CSS, inline SVG, no external assets, no JS dependencies beyond the ~25-line inline theme/pause/reduced-motion script. Renders correctly opened from the filesystem, in light or dark per the viewer's preference (or the pinned defaultMode).

Model Office

A local FastAPI + WebSocket + HTML5 Canvas demo that visualizes capability-based job routing across multiple LLMs as a blocky Lego/Minecraft-style office. Inspired by pixel-agents-hq/pixel-agents, but built for capability-based multi-model routing rather than parsing a single coding agent's transcript.

Architecture

  • scripts/server.py — FastAPI backend: POST /api/task (submit a task), POST /api/events (producers push status), GET /ws (broadcast to browser), serves scripts/frontend/ as static files.
  • scripts/dispatcher.py — one Claude call decomposes the task into 2-4 subtasks and assigns each to the worker whose capability best fits (claude = code/reasoning, gpt = writing/general, sonar = research requiring live web facts). Emits jobCreated/jobAssigned events.
  • scripts/worker.py — runs each subtask against its real assigned model API, emitting queued → thinking → done/error status events as it goes. Subtasks for different workers run concurrently.
  • scripts/run.py — orchestrator: starts the server if not running, opens the browser, and (optionally) dispatches a task from argv.
  • scripts/frontend/ — canvas-based two-zone office UI: an upper grey "WORKING AREA" (desks with monitors) and a lower green "WAITING AREA" (lounge benches), separated by a thick red brick divider — Lego/Minecraft blocky art style. Worker avatars (sprites/claude.png, sprites/gpt.png, sprites/sonar.png) smoothly slide up to their desk when status becomes thinking, and slide back down to the lounge when done/idle/error. Job tickets fly from a queue to the assigned worker's desk; speech bubbles show live status text; a log feed sits underneath. Connects via WebSocket, replays event history on reconnect.

When to Use

Activate this skill when the user:

  • Wants to see/demo how work routes across multiple models based on capability
  • References "pixel agents", "pixel office", "model office", or this skill by name
  • Wants a live visual (browser) showing multiple agents/models picking up jobs and their status
  • Asks "can you show me job allocation across models visually"

Prerequisites

Real API keys must be present in the environment before running workers:

  • ANTHROPIC_API_KEY (dispatcher + claude worker)
  • OPENAI_API_KEY (gpt worker)
  • PERPLEXITY_API_KEY (sonar worker, native web search)

If any key is missing, worker.py raises an auth error for that worker only — the other workers still complete. Check with:

env | grep -E 'ANTHROPIC_API_KEY|OPENAI_API_KEY|PERPLEXITY_API_KEY' | sed 's/=.*/=<set>/'

An env var appearing in env output with a non-empty value after = is what matters — a bare KEY= (empty) still shows the name but has no value. Verify with echo "LEN=${#OPENAI_API_KEY}" (0 means unset/empty).

How to Run

cd skills/model-office/scripts
pip install -q -r requirements.txt   # first run only

# Option A: server + browser only, submit tasks from the UI
python3 server.py &
python3 -c "import webbrowser; webbrowser.open('http://127.0.0.1:8787')"

# Option B: one-shot — starts server, opens browser, dispatches a task, prints results
python3 run.py "Plan a 3-day Tokyo trip, write a fun blog intro, and research current visa rules for US citizens."

The dashboard also has a text input + Dispatch button, so once the server is running the user can type new tasks directly in the browser without invoking run.py again — it posts to /api/task which runs the dispatcher+workers in the background and streams status over the existing WebSocket.

If a live agent (e.g. AdaL, Claude Code) is already running and separate API keys aren't configured for worker.py, the agent can relay the pipeline itself: POST /api/events directly with jobCreated/jobAssigned/ workerStatus/jobDone events using its own model access (e.g. consult, web_search) so the browser still animates a live run.

Customizing Workers

Capability routing rules live in dispatcher.py::WORKER_CAPABILITIES and the DECOMPOSE_SYSTEM prompt. To add/swap a worker:

  1. Add its capability description to WORKER_CAPABILITIES.
  2. Add a _call_<worker>() function in worker.py and register it in _CALLERS.
  3. Add an entry to WORKERS in frontend/app.js with a desk x position.
  4. Generate a matching pixel-art sprite (16-bit style, magenta background, front-facing standing pose) and save to frontend/sprites/<worker>.png.

Known Limitations

  • Single-machine demo only — not wired into any specific agent's own orchestration; it's a standalone visualization of the concept of capability-based multi-model routing, using direct API calls to Anthropic/OpenAI/Perplexity.
  • No persistence — job history resets on server restart or POST /api/reset.
  • No cost/token tracking per worker yet (a natural next step: add token usage + running $ to the jobDone event payload and render it under the worker's name plate).
  • No self-evolving/learned routing yet (a natural next step: a skill-library cache mapping job-type signatures to the model+prompt combo that succeeded before, with fallback to the LLM dispatcher on cache miss).

PostHog Analytics Skill

Automate PostHog dashboard creation, sync, update, and export via API.

Prerequisites

Required Tools

  • curl - HTTP client (pre-installed on macOS/Linux)
  • jq - JSON processor: brew install jq or apt install jq
  • bash - Shell (the script is bash)

PostHog API Key

  1. Go to PostHog Settings → Personal API Keys
  2. Create a new key with read/write access
  3. Export it:
export POSTHOG_PERSONAL_API_KEY=phx_xxx

Note: The API key determines your organization and project. The script uses @current project context (your default project).

Verify Setup

# Test your API key - should return your project info
curl -s -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
  "https://us.i.posthog.com/api/projects/@current/" | jq '{id, name}'

Expected output:

{
  "id": 209268,
  "name": "Default project"
}

If you get an error, check your API key is correct and has proper permissions.

Quick Start: Blog Analytics Example

Step 1: Write Your Config

Create blog_dashboard.json:

{
  "name": "Blog Analytics",
  "description": "Track blog performance and reader engagement",
  "filter": {"key": "source", "value": "blog"},
  "dashboard_id": null,
  "insights": [
    {"name": "Blog Pageviews (Total)", "type": "pageviews_total"},
    {"name": "Unique Blog Readers", "type": "unique_users"},
    {"name": "Blog Traffic Trend", "type": "traffic_trend"},
    {"name": "Top Blog Posts", "type": "top_pages"}
  ]
}

Note: Set dashboard_id: null for new dashboards.

Step 2: Create Dashboard

./scripts/posthog_sync.sh create blog_dashboard.json

Output:

Creating dashboard: Blog Analytics
Dashboard created: ID 1166599
Creating insight: Blog Pageviews (Total)
{id: 6520531, name: "Blog Pageviews (Total)"}
...
Dashboard URL: https://us.posthog.com/project/209268/dashboard/1166599

The script:

  • Creates a new dashboard in your PostHog project
  • Returns dashboard_id (e.g., 1166599) and project_id (e.g., 209268) in the URL
  • Automatically updates your config file with the dashboard_id

Step 3: Add New Insights (Sync)

Edit config to add new insights, then:

./scripts/posthog_sync.sh sync blog_dashboard.json

Only creates NEW insights. Existing ones (matched by name) are skipped.

Step 4: Update Existing Insights

Changed your filter? Edit config, then:

./scripts/posthog_sync.sh update blog_dashboard.json

Updates ALL insights with current config settings. Use when changing filters.

Step 5: Export Existing Dashboard

./scripts/posthog_sync.sh export 1166599 > exported_dashboard.json

Config Reference

FieldRequiredDescription
nameYesDashboard name
descriptionNoDashboard description
filterNo*Event property filter: {"key": "source", "value": "blog"}
domain_filterNo*URL filter fallback: "blog.sylph.ai"
dashboard_idNoSet to null for create, or existing ID for sync/update
insightsYesArray of insight objects

*At least one filter recommended. filter takes precedence over domain_filter.

Insight Types

TypeDisplayDescription
pageviews_totalBoldNumberTotal pageview count
unique_usersBoldNumberUnique visitors (DAU)
traffic_trendLineGraphTraffic over time
top_pagesTableTop pages breakdown

Optional Insight Fields

FieldDefaultOptions
mathtotaltotal, dau, weekly_active, monthly_active
displayAutoBoldNumber, ActionsLineGraph, ActionsTable
date_range-30d-7d, -30d, -90d, etc.

Environment Variables

VariableRequiredDefaultDescription
POSTHOG_PERSONAL_API_KEYYes-Your API key (determines org/project)
POSTHOG_HOSTNous.i.posthog.comAPI host (EU: eu.i.posthog.com)
POSTHOG_UI_HOSTNous.posthog.comUI host for dashboard URLs

Files

  • scripts/posthog_sync.sh - CLI script (create/sync/update/export)
  • examples/blog_dashboard.json - Example config

References

SWE CLI Skills

man pages for machines — Your agent knows the commands. We teach it the workflows.

This skill provides expert-level CLI knowledge for the tools software engineers use daily. Each guide encodes senior engineer judgment — not reference docs, but operational workflows, safety guardrails, flag gotchas, error recovery, and composition patterns.

When to Use This Skill

Load a specific CLI guide when:

  • You need to run complex CLI operations (multi-step workflows, piped commands)
  • You're unsure about flag ordering, safety checks, or non-interactive alternatives
  • You encounter a CLI error and need the actual fix (not generic advice)
  • You need to compose multiple CLIs together (e.g., aws → jq → xargs)

Available CLI Guides

Guides are organized by category. Read the category index or jump directly to a CLI guide.

☁️ Cloud (skills/cloud/)

CLIFileUse For
AWS CLIskills/cloud/aws.mdS3 filter ordering, IAM auth, EC2 queries, JMESPath, Lambda
gcloudskills/cloud/gcloud.mdGCP project/config management, GKE, Cloud Run, IAM, logging
Azure CLIskills/cloud/azure.mdResource groups, AKS, App Service, RBAC, ARM deployments

🏗️ Infrastructure as Code (skills/iac/)

CLIFileUse For
Terraformskills/iac/terraform.mdState management, import workflows, safe apply, workspace migration

🐳 Containers & Orchestration (skills/containers/)

CLIFileUse For
Dockerskills/containers/docker.mdBuild cache, multi-stage builds, compose v2, cleanup, debugging
kubectlskills/containers/kubectl.mdContext safety, namespace gotchas, rollout/rollback, pod debugging
Helmskills/containers/helm.mdValues precedence, upgrade resets, rollback, chart debugging

🔀 Git & Version Control (skills/git-vcs/)

CLIFileUse For
Gitskills/git-vcs/git.mdNon-interactive alternatives, rebase, merge, conflict resolution
GitHub CLIskills/git-vcs/gh.mdPR workflows, issue management, releases, Actions

🛠️ Dev Tools (skills/dev-tools/)

CLIFileUse For
jqskills/dev-tools/jq.mdJSON filtering, select vs map, array ops, shell variable injection
sedskills/dev-tools/sed.mdStream editing, in-place substitution, macOS vs Linux portability
makeskills/dev-tools/make.mdBuild automation, Makefile patterns, phony targets, variables
curlskills/dev-tools/curl.mdAuth headers, multipart uploads, API debugging, response handling
SSH/SCPskills/dev-tools/ssh.mdTunneling, ProxyJump, key management, agent-safe patterns

📦 Package Managers (skills/package-managers/)

CLIFileUse For
npmskills/package-managers/npm.mdDependency management, scripts, workspaces, publishing, lockfiles
pip & uvskills/package-managers/pip-uv.mdVirtual envs, dependency resolution, uv acceleration, constraints

🗄️ Databases (skills/databases/)

CLIFileUse For
psqlskills/databases/psql.mdConnection strings, non-interactive queries, backup/restore, meta-commands
redis-cliskills/databases/redis.mdConnection, key operations, debugging, persistence, cluster management

🚀 Platforms & Services (skills/platforms/)

CLIFileUse For
Stripe CLIskills/platforms/stripe.mdWebhook testing, API debugging, fixtures, payment flow testing
Sentry CLIskills/platforms/sentry.mdRelease management, sourcemap uploads, deploy tracking
Vercel CLIskills/platforms/vercel.mdDeployments, env vars, serverless functions, domains
Firebase CLIskills/platforms/firebase.mdHosting deploy, Firestore rules, auth emulators, Cloud Functions
flyctlskills/platforms/fly.mdApp deployment, scaling, secrets, regions, Machines API

Quick Reference: Critical Gotchas

These are the highest-impact mistakes — check the full guide for details:

  • AWS S3: --exclude must come BEFORE --include (left-to-right evaluation)
  • Terraform: Always terraform plan after terraform import (detects drift)
  • Docker: Copy dependency files before source code (cache optimization)
  • kubectl: ALWAYS verify kubectl config current-context before apply
  • Helm: helm upgrade RESETS values not specified — use --reuse-values
  • Git: Use git --no-pager and --no-edit flags (agents have no TTY)
  • SSH: Use BatchMode=yes to prevent password prompt hangs
  • psql: Always use -v ON_ERROR_STOP=1 in scripts (psql continues after errors by default)
  • Redis: NEVER use KEYS * in production — use SCAN instead (blocks server)
  • gcloud: Always set --project explicitly in automation (don't rely on default project)
  • npm: Use npm ci in CI/CD, not npm install (ensures reproducible builds)
  • sed: sed -i behaves differently on macOS vs Linux — use -i.bak for portability
  • make: Indentation MUST be real tabs, not spaces (invisible error)
  • Stripe: stripe listen webhook secret changes on every restart — update your env var
  • Sentry: Sourcemap --url-prefix must exactly match browser request paths
  • Vercel: vercel without --prod deploys to preview, not production
  • Firebase: firebase deploy without --only deploys EVERYTHING

Token Efficiency

This skill uses a category sub-index architecture. Instead of loading all CLI guides at once:

  1. Read this root SKILL.md to find the right category
  2. Read only the specific CLI guide you need (e.g., skills/cloud/aws.md)

This keeps token usage minimal — load one guide (~200-400 lines) instead of the entire library.

Each Guide Contains

  1. Setup & Auth — Installation and credential configuration
  2. Core Workflows — The 20% of commands covering 80% of usage
  3. Flag Gotchas — Ordering traps, version quirks, surprising defaults
  4. Error Patterns — Real error messages → real fixes
  5. Anti-Patterns — "Never do X because Y" with safe alternatives
  6. Composability — How to pipe this CLI with others
  7. Agent Constraints — Non-interactive alternatives, TTY workarounds

Sponsors

Details

Marketplace
SylphAI-Inc/skills
Category
Community

More from SylphAI-Inc/skills

All 2