diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..b0a2dda --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,118 @@ +# AGENTS.md + +This file provides guidance to AI coding agents (Claude Code, Cursor, Copilot, etc.) when working with code in this repository. + +## Repository Overview + +A collection of skills for Claude Code and Claude.ai. Skills are packaged instructions and optional scripts that extend Claude's capabilities. + +## Skill Authoring Best Practices + +When creating or modifying skills, refer to the official best practices documentation: + +https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices + +Key principles: +- Be concise — Claude is already smart, only add context it doesn't have +- Set appropriate degrees of freedom for the task's fragility +- Test with the models you plan to use + +## Creating a New Skill + +### Directory Structure + +``` +{skill-name}/ # kebab-case directory name + SKILL.md # Required: skill definition with YAML frontmatter + scripts/ # Optional: executable scripts + {script-name}.sh # Bash scripts (preferred) + {script-name}.py # Python scripts + {supporting-files}.md # Optional: reference docs, templates, examples +``` + +### Naming Conventions + +- **Skill directory**: `kebab-case` (e.g., `audit-website-design`, `code-review`) +- **SKILL.md**: Always uppercase, always this exact filename +- **Scripts**: `kebab-case.sh` or `kebab-case.py` (e.g., `deploy.sh`, `analyze.py`) + +### SKILL.md Format + +```markdown +--- +name: {skill-name} +description: {One or two sentences describing what the skill does AND when to use it. Include trigger phrases. Max 1024 characters.} +--- + +# {Skill Title} + +{Brief description of what the skill does.} + +## How It Works / Workflow + +{Numbered list or sections explaining the skill's workflow} + +## Usage + +{Show common usage patterns and examples} + +## Output + +{Describe or show example output} +``` + +**Required frontmatter fields:** + +| Field | Requirements | +|-------|-------------| +| `name` | Max 64 chars, lowercase letters/numbers/hyphens only | +| `description` | Non-empty, max 1024 chars, third-person voice ("Extracts..." not "I extract...") | + +**Optional frontmatter fields:** + +| Field | Description | +|-------|-------------| +| `disable-model-invocation` | `true` to prevent Claude auto-triggering (manual `/name` only) | +| `user-invocable` | `false` to hide from `/` menu (background knowledge only) | +| `allowed-tools` | Space-separated tools pre-approved when skill is active | +| `argument-hint` | Hint shown in autocomplete, e.g. `[url]` or `[filename]` | +| `effort` | Reasoning effort: `low`, `medium`, `high`, `max` | +| `context` | Set to `fork` to run in a subagent | +| `agent` | Subagent type when `context: fork` (e.g., `Explore`, `Plan`) | +| `model` | Model override when skill is active | +| `paths` | Glob patterns limiting when skill activates | + +### Best Practices for Context Efficiency + +Skills are loaded on-demand — only the skill name and description are loaded at startup. The full `SKILL.md` loads into context only when the agent decides the skill is relevant. To minimize context usage: + +- **Keep SKILL.md under 500 lines** — put detailed reference material in separate files +- **Write specific descriptions** — helps the agent know exactly when to activate the skill +- **Use progressive disclosure** — reference supporting files that get read only when needed +- **Prefer scripts over inline code** — script execution doesn't consume context (only output does) +- **File references should be one level deep** — link directly from SKILL.md to supporting files, avoid chains of references + +### Script Best Practices + +- Use `#!/bin/bash` shebang and `set -e` for fail-fast behavior +- Write status messages to stderr: `echo "Message" >&2` +- Write machine-readable output (JSON) to stdout where applicable +- Include a cleanup trap for temp files +- Handle errors explicitly rather than letting Claude figure them out +- Document all constants (no "magic numbers") + +### End-User Installation + +**Claude Code (via skills.sh):** +```bash +# Install a specific skill +skills install {skill-name} +``` + +**Claude Code (manual):** +```bash +cp -r {skill-name} ~/.claude/skills/ +``` + +**Claude.ai:** +Add the skill zip to project knowledge or paste SKILL.md contents into the conversation. If the skill requires network access, add required domains at `claude.ai/settings/capabilities`. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..c4f1fdc --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +Read AGENTS.md for instructions on working with this repository. diff --git a/audit-website-design/SKILL.md b/audit-website-design/SKILL.md new file mode 100644 index 0000000..1028747 --- /dev/null +++ b/audit-website-design/SKILL.md @@ -0,0 +1,92 @@ +--- +name: audit-website-design +description: Performs a comprehensive design and technical audit of a website URL. Extracts layout, typography, colors, components, animations, spacing, tech stack, SEO metadata, and brand voice into a detailed reference document for replicating design decisions. Use when analyzing or auditing a website's design. +disable-model-invocation: true +allowed-tools: WebFetch Bash(curl *) +argument-hint: [url] +effort: high +--- + +# Website Design Audit + +Audit the website at `$ARGUMENTS` and produce a comprehensive design reference document that an engineer or LLM can use to replicate the site's design decisions. + +## Extraction strategy + +Gather data through multiple passes, then compile into the final report. + +### Pass 1: Raw HTML source + +Fetch the page source for technical and structural metadata: + +```bash +curl -sL -A "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36" "$URL" +``` + +If the output is very large, pipe through `head -1500` to capture `` and initial ``. If curl returns a Cloudflare challenge or empty body, note this and rely more on WebFetch in Pass 3. + +Extract from HTML: +- ``, `<meta name="description">`, Open Graph tags (`og:*`), favicon, canonical URL +- Font imports: Google Fonts `<link>` URLs, Adobe Fonts/Typekit embeds, `@font-face` declarations +- Stylesheet `<link>` URLs (needed for Pass 2) +- `<script>` tags: framework bundles, analytics, third-party libraries +- **Framework markers**: `__next` / `__NEXT_DATA__` (Next.js), `__nuxt` (Nuxt), `data-reactroot` (React), `ng-` attributes (Angular), `astro-island` (Astro), Svelte markers +- **CSS framework signals from class names**: Tailwind utilities (`flex`, `px-4`, `text-lg`, `bg-`), Bootstrap (`col-`, `btn-`, `container`, `row`), or custom BEM/semantic classes +- Heading hierarchy: all `<h1>` through `<h6>` elements +- Structural elements: `<header>`, `<nav>`, `<main>`, `<section>`, `<aside>`, `<footer>` — note nesting and order +- Hosting hints: `<meta name="generator">`, `_next/`, `_nuxt/`, `.netlify/`, Vercel deployment markers + +### Pass 2: Stylesheet analysis + +Fetch the primary stylesheet(s) identified in Pass 1 (limit to the 2-3 most relevant). Skip this pass if the site uses only utility CSS (Tailwind) with no meaningful standalone stylesheet, or if no stylesheet URLs were found. + +```bash +curl -sL "$CSS_URL" +``` + +Extract: +- **CSS custom properties** (`:root` block): `--color-*`, `--font-*`, `--spacing-*` etc. These are the design tokens and the highest-value extraction target +- **Colors**: All hex/rgb/hsl values. Group by role: primary, secondary, accent, backgrounds, text, borders +- **Typography**: `font-family` stacks, `font-size` scale, `font-weight` values, `line-height`, `letter-spacing`, `text-transform` +- **Spacing**: Recurring `padding`, `margin`, `gap` values. Identify the base unit and scale +- **Border radius**: Common values (e.g., `4px`, `8px`, `9999px` for pills) +- **Shadows**: `box-shadow` definitions for cards, buttons, modals, dropdowns +- **Breakpoints**: `@media` query values, ordered by size +- **Transitions & animations**: `transition` properties, `@keyframes` names, durations, easing functions +- **Layout constraints**: `max-width` on containers, grid template definitions +- **Gradients**: `linear-gradient`, `radial-gradient` definitions with colors and direction + +If CSS is minified and extremely large (>50KB), focus on CSS custom properties (`:root`), `@media` queries, and `@keyframes` definitions. + +### Pass 3: Visual and content analysis + +Use WebFetch to analyze the rendered page for qualities not extractable from source alone. Make one or two WebFetch calls with focused prompts covering: + +- Overall visual style, mood, and emotional impression +- Layout pattern and visual hierarchy (what draws the eye 1st, 2nd, 3rd) +- Header/nav style and behavior (sticky, transparent, hamburger, mega-menu) +- Footer style and content +- Section separation technique (color shifts, cards, dividers, whitespace) +- Imagery style (photography, illustration, icons) and treatment (filters, overlays, shapes) +- Button styles: shape, sizes, fill/outline/ghost variants, CTA wording examples +- Card patterns: shadow, border, radius, hover behavior +- Other components: forms, modals, badges, accordions, tables, testimonials, pricing +- Animation and interaction hints (scroll effects, hover states, page transitions) +- Copy tone and brand voice (casual, formal, playful, authoritative) +- Social proof elements (logos, testimonials, stats, trust badges) +- Whitespace density (tight/dense or open/airy) +- Anything unconventional, creative, or standout + +### Pass 4: Compile the report + +Merge all findings into the structured template in [TEMPLATE.md](TEMPLATE.md). Save as `style-ref-[domain].md` in the current working directory (e.g., `style-ref-stripe-com.md`). + +## Output rules + +- **Use exact values**: hex codes, px/rem sizes, font names as CSS values, not vague descriptions +- **Mark unknowns**: Write `[Not determinable from source]` if something cannot be confirmed. Do not guess +- **Include both value and context**: e.g., `**Primary color**: #635BFF (vibrant purple) -- used for CTAs and interactive elements` +- **Stay factual**: Report what is observed, not what is assumed +- **Keep entries scannable**: Use `**Label**: value` format on bullet points +- **Omit empty sections**: If a section has nothing to report (e.g., no dark mode, no sidebar), write a single line noting this rather than leaving placeholders unfilled +- **Paste relevant CSS custom properties verbatim**: If the site defines design tokens in `:root`, include them in the Color Palette section as a fenced code block diff --git a/audit-website-design/TEMPLATE.md b/audit-website-design/TEMPLATE.md new file mode 100644 index 0000000..fa0889a --- /dev/null +++ b/audit-website-design/TEMPLATE.md @@ -0,0 +1,241 @@ +# Design Audit: [Site Name] + +**URL**: [full URL] +**Date audited**: [YYYY-MM-DD] +**Domain**: [domain] + +--- + +## 1. Overall Impression & Identity + +- **Visual style/mood**: [e.g., minimal, playful, corporate, brutalist, luxury, tech-forward] +- **Target industry/niche**: +- **Emotional response on first load**: +- **Unifying design concept/theme**: +- **One-sentence summary**: + +--- + +## 2. Layout & Structure + +- **Layout pattern**: [single column, multi-column, grid-based, asymmetric] +- **Max content width**: [e.g., `1200px`, `1440px`, full-bleed] +- **Whitespace approach**: [tight/dense or generous/airy] +- **Section structure**: [how the page is divided into blocks] +- **Header**: [sticky/fixed, transparent, navigation type, height] +- **Footer**: [fat with columns, minimal, CTA-focused] +- **Sidebar**: [yes/no, position] +- **Content containment**: [cards, dividers, background color shifts, borders] +- **Grid system**: [12-col, CSS Grid, masonry, Flexbox, custom] +- **Full-width vs boxed sections**: [pattern] +- **Visual hierarchy**: [what draws eye 1st -> 2nd -> 3rd] + +--- + +## 3. Typography + +- **Primary heading font**: [name, weight, style] +- **Body font**: [name, weight, style] +- **Accent/display fonts**: [name — if any] +- **Font pairing strategy**: [e.g., serif + sans-serif, mono + sans] +- **Font delivery method**: [Google Fonts URL / Adobe Fonts / self-hosted] +- **Heading sizes**: + - H1: [size, weight] + - H2: [size, weight] + - H3: [size, weight] + - H4-H6: [sizes if used] +- **Body text**: [size, line-height] +- **Letter spacing**: [notable values and where applied] +- **Text transform**: [uppercase headings, small-caps, etc.] +- **Font weights used**: [list: light/regular/medium/semibold/bold/black] +- **Link styling**: [color, underline, hover behavior] +- **Text alignment patterns**: [left-aligned body, centered headings, etc.] +- **Emphasis conventions**: [bold for X, italic for Y] +- **Responsive font scaling**: [approach if identifiable — fluid clamp(), breakpoint steps] + +--- + +## 4. Color Palette + +- **Primary brand color**: [hex — description and usage] +- **Secondary color(s)**: [hex — description and usage] +- **Accent/highlight color(s)**: [hex — description and usage] +- **Background colors**: + - Main background: [hex] + - Alternating sections: [hex values] + - Card/surface: [hex] +- **Text colors**: + - Headings: [hex] + - Body text: [hex] + - Muted/secondary text: [hex] +- **Link colors**: [default hex, hover hex, visited if different] +- **Border/divider colors**: [hex values] +- **Gradients**: [full CSS value — colors, direction, where applied] +- **Dark mode**: [supported yes/no — if yes, list key dark palette values] +- **Contrast notes**: [any accessibility observations] +- **Section separation via color**: [how alternating backgrounds create rhythm] + +### CSS Custom Properties + +```css +/* Paste relevant :root custom properties here */ +``` + +--- + +## 5. Imagery & Media + +- **Photography style**: [lifestyle, abstract, product shots, editorial, AI-generated] +- **Image treatment**: [filters, overlays, duotone, B&W, rounded corners, masks] +- **Illustration style**: [flat, 3D, hand-drawn, isometric — if used] +- **Icon style**: [outlined, filled, duotone, custom] +- **Icon library**: [Heroicons, Lucide, FontAwesome, Phosphor, custom SVGs — if identifiable] +- **Icon size and stroke weight**: [if determinable] +- **Video usage**: [hero background, embedded, autoplay, none] +- **Image formats**: [WebP, AVIF, SVG, PNG, JPG] +- **Common aspect ratios**: [16:9, 4:3, 1:1, etc.] +- **Image masking/cropping**: [circles, rounded rects, blobs, custom shapes] +- **Decorative elements**: [blobs, patterns, grain/noise, geometric shapes, lines] +- **Favicon**: [style description] + +--- + +## 6. Components & UI Patterns + +### Buttons + +- **Shape/border-radius**: [value — rounded, pill `9999px`, square] +- **Sizes**: [small, medium, large — dimensions if determinable] +- **Variants**: [filled, outline, ghost, text-only] +- **Padding**: [value if determinable] +- **Hover state**: [color shift, shadow, scale, underline, etc.] +- **CTA examples**: [exact button text observed, e.g., "Get Started", "Try Free"] + +### Cards + +- **Shadow**: [box-shadow CSS value] +- **Border**: [color, width, style] +- **Border radius**: [value] +- **Padding**: [value] +- **Background**: [color] +- **Hover behavior**: [lift, glow, border change, shadow increase] + +### Navigation + +- **Desktop style**: [horizontal links, dropdowns, mega-menu, tabs] +- **Mobile pattern**: [hamburger, bottom nav, slide-out drawer] +- **Active state**: [underline, color, background, bold] +- **Breadcrumbs**: [yes/no, style] + +### Forms + +- **Input style**: [border color/width, background, height/padding, border-radius] +- **Labels**: [floating, above input, inline, placeholder-only] +- **Focus state**: [border color, shadow, outline] +- **Validation style**: [inline error, color change, icon] + +### Other Components + +- **Modals/dialogs**: [overlay color, border-radius, animation, backdrop blur] +- **Badges/tags/pills**: [colors, size, border-radius] +- **Tooltips**: [style, trigger method] +- **Tables**: [style, striped rows, borders] +- **Accordions/tabs**: [style, transition, indicator] +- **Testimonials/reviews**: [layout — carousel, grid, single quote, avatar usage] +- **Pricing tables**: [layout, toggle, feature comparison style] +- **Progress indicators**: [bars, steps, percentages, dots] +- **Alert/notification bars**: [top banner, toast, inline, colors] + +--- + +## 7. Animation & Interaction + +- **Page load**: [fade-in, stagger, skeleton loaders, none] +- **Scroll-triggered**: [parallax, reveal on scroll, slide-in, fade-up] +- **Hover effects**: [links, buttons, cards, images — describe each] +- **Page transitions**: [instant, fade, slide, none] +- **Micro-interactions**: [toggle switches, like buttons, form feedback, copy buttons] +- **Cursor**: [default, custom cursor, pointer changes] +- **Loading states**: [spinner, skeleton, shimmer, progress bar] +- **Easing style**: [snappy/fast, smooth/gentle, bouncy/elastic] +- **Timing**: [typical duration values — e.g., 150ms for hovers, 300ms for reveals] +- **Animation library**: [Framer Motion, GSAP, AOS, Lottie, CSS-only, View Transitions API] +- **Overall feel**: [subtle and polished, dramatic and bold, minimal/none] + +--- + +## 8. Spacing & Rhythm + +- **Base spacing unit**: [e.g., 4px, 8px] +- **Spacing scale**: [e.g., 4, 8, 12, 16, 24, 32, 48, 64, 96, 128] +- **Section padding (vertical)**: [typical top/bottom values] +- **Card/grid gap**: [typical values] +- **Heading-to-body margin**: [value] +- **Paragraph spacing**: [value] +- **Overall density**: [tight/compact, balanced, open/spacious] + +--- + +## 9. Responsive & Breakpoints + +- **Breakpoint values**: [list all found, e.g., 640px, 768px, 1024px, 1280px] +- **Design approach**: [mobile-first or desktop-first] +- **Layout changes**: + - Mobile (<768px): [description] + - Tablet (768-1024px): [description] + - Desktop (>1024px): [description] +- **Mobile navigation**: [hamburger, bottom nav, slide-out, full-screen overlay] +- **Elements hidden/shown**: [what changes by breakpoint] +- **Typography scaling**: [how sizes change] +- **Grid/image reflow**: [how columns collapse] + +--- + +## 10. Technical Stack + +- **CSS approach**: [Tailwind, Bootstrap, custom CSS, CSS Modules, styled-components, Emotion] +- **JS framework**: [React, Next.js, Vue, Nuxt, Astro, Svelte, SvelteKit, vanilla, jQuery] +- **CMS**: [WordPress, Webflow, Sanity, Contentful, Shopify, Strapi — if identifiable] +- **Hosting indicators**: [Vercel, Netlify, AWS, Cloudflare Pages, GitHub Pages] +- **Font delivery**: [Google Fonts (URL), Adobe Fonts, self-hosted] +- **Notable libraries**: [Swiper, Framer Motion, GSAP, Three.js, Lottie, Radix UI, Headless UI] +- **Analytics/tracking**: [Google Analytics, Plausible, Segment, Hotjar, etc.] +- **Performance patterns**: [lazy loading, image optimization (WebP/AVIF), code splitting, prefetching] +- **Build tooling hints**: [Webpack chunks, Vite, Turbopack — from script/asset naming patterns] + +--- + +## 11. SEO & Meta Presentation + +- **Page title**: `[exact title text]` +- **Title format pattern**: [e.g., "Page Title — Brand" or "Brand | Page"] +- **Meta description**: `[exact text]` +- **Open Graph tags**: + - og:title: `[value]` + - og:description: `[value]` + - og:image: [URL or description] + - og:type: [value] + - twitter:card: [value] +- **URL structure**: [pattern, e.g., `/blog/post-slug`, `/products/category/item`] +- **Heading hierarchy**: [proper H1 -> H2 -> H3 nesting? any issues?] +- **Canonical URL**: [present yes/no, value] +- **Structured data**: [JSON-LD types, microdata — if found] + +--- + +## 12. Brand Voice in Design + +- **Copy tone**: [casual, formal, playful, authoritative, witty, technical, empathetic] +- **CTA wording style**: [list examples: "Get Started", "Start Free Trial", "Let's Go"] +- **Text-to-visual ratio**: [text-heavy, visual-heavy, balanced] +- **Social proof usage**: [client logos, testimonials, stats/numbers, trust badges, case studies] +- **Design personality**: [friendly rounded shapes, sharp corporate lines, hand-crafted feel, etc.] + +--- + +## 13. Unique & Standout Features + +- [List anything unconventional or signature about this design] +- [Creative uses of scroll, layout, or interaction] +- [Notable "wow" moments or delightful details] +- [What distinguishes this site from generic templates]