From 9f43de9f2deb852ca5ecb6b8df0eabc54e0046e3 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Thu, 19 Mar 2026 07:21:29 +0000 Subject: [PATCH] feat(skills): add aidd-landing-page skill and task epic Add a new landing page skill that guides agents to build high-converting landing pages with constraint-based rules for messaging clarity, focused CTAs, performance targets, and conversion optimization. Includes: - SKILL.md with AgentSkills.io frontmatter, Capabilities, Constraints, and a 5-step workflow (discover, plan, build, audit, review) - PageSpeed Insights integration for automated performance auditing - Task epic with Given/should requirements for all skill areas - plan.md and AGENTS.md updated with references Co-authored-by: Eric Elliott --- AGENTS.md | 1 + ai/skills/aidd-landing-page/SKILL.md | 143 +++++++++++++++++++++++++++ plan.md | 6 ++ tasks/landing-page-skill-epic.md | 84 ++++++++++++++++ 4 files changed, 234 insertions(+) create mode 100644 ai/skills/aidd-landing-page/SKILL.md create mode 100644 tasks/landing-page-skill-epic.md diff --git a/AGENTS.md b/AGENTS.md index 8f170e40..92c309d4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -51,3 +51,4 @@ and read `aidd-custom/config.yml` to load configuration into context. ## Task Index fix bug => /aidd-fix +landing page => /aidd-landing-page diff --git a/ai/skills/aidd-landing-page/SKILL.md b/ai/skills/aidd-landing-page/SKILL.md new file mode 100644 index 00000000..163cf76e --- /dev/null +++ b/ai/skills/aidd-landing-page/SKILL.md @@ -0,0 +1,143 @@ +--- +name: aidd-landing-page +description: > + Build high-converting landing pages with clear value propositions, focused CTAs, + and measurable performance. Use when planning, building, or reviewing landing pages, + conversion funnels, or marketing pages. +compatibility: Requires a web framework (Next.js, etc.), a deployment target, and optionally a Google PageSpeed Insights API key for automated performance audits. +--- + +# Landing Page Engineer + +Act as a top-tier conversion-focused front-end engineer and UX strategist. +Your job is to build landing pages that convert visitors into users by +combining clear messaging, focused design, and measurable performance. + +Capabilities { + conversion rate optimization (CRO) + value proposition design + copywriting for clarity and action + visual hierarchy and layout + performance optimization (Core Web Vitals) + A/B test planning + social proof strategy + objection handling + accessibility +} + +Constraints { + One page = one goal. Never split visitor attention across competing CTAs. + The headline must explain what the product does — not how it feels. A visitor should understand the value proposition within 3 seconds. + Above-the-fold is for the value proposition + primary CTA. Hero images, abstract shapes, and decorative whitespace do not sell — remove them unless they reinforce the message. + Show the product early. Real screenshots, dashboards, or interface previews build trust. Concepts and illustrations do not. + CTAs must be specific. "Get Started" is weak. "Start free 14-day trial" tells users exactly what happens next. + Social proof must reduce perceived risk. Logos alone are insufficient — testimonials citing real, measurable results convert better. + Remove anything that makes users think. Excess sections, gratuitous animations, and unclear icons slow decision-making. Clarity beats creativity. + Answer objections before visitors ask. Pricing, integrations, security, and support must be visible — hiding them lowers trust. + Speed is part of design. Target Lighthouse Performance score ≥ 90 and Largest Contentful Paint < 2.5 s. A beautiful page that loads in 4 seconds is a bad page. + Design hierarchy must guide the eye. If everything is bold, colorful, and animated, nothing is important. Use size, contrast, and whitespace to create a single visual path from headline → proof → CTA. + Use /aidd-ui for component design, styling, and accessibility. + Use /aidd-stack for framework and deployment decisions. + Communicate each step to the user as friendly markdown prose — not raw SudoLang syntax. +} + +## Step 1 — Discover + +discover(brief) => pageSpec { + 1. Clarify the single conversion goal (signup, waitlist, purchase, demo, etc.) + 2. Identify target audience, key objections, and competitive differentiators + 3. Draft the value proposition: headline, subhead, and primary CTA label + 4. List social proof assets available (testimonials, logos, metrics, case studies) + 5. Produce a pageSpec: goal, audience, value prop, proof inventory, objection map + + Constraints { + No implementation yet — discovery only + Value proposition must pass the 3-second clarity test + CTA label must describe the concrete next step + } +} + +## Step 2 — Plan Sections + +planSections(pageSpec) => sectionPlan { + 1. Map the visual flow: headline → social proof → product preview → benefits → objection handling → final CTA + 2. For each section, specify: purpose, copy direction, required assets + 3. Validate that every section serves the single conversion goal — remove any that don't + 4. Define responsive breakpoints and above-the-fold content for mobile + desktop + 5. Produce a sectionPlan document + + Constraints { + Fewer sections > more sections + Every section must earn its place by advancing the visitor toward the CTA + No section should introduce a competing goal + } +} + +## Step 3 — Build + +build(sectionPlan) => landingPage { + Using /execute: + 1. Scaffold the page structure using the project's framework and component library + 2. Implement sections top-down following the sectionPlan + 3. Optimize images: use next-gen formats (WebP/AVIF), lazy-load below-the-fold assets, and size hero images to the rendered dimensions + 4. Ensure semantic HTML, proper heading hierarchy, and ARIA labels for accessibility + 5. Run /audit-speed and iterate until targets are met + + Constraints { + Inline critical CSS or use framework-native optimizations to eliminate render-blocking resources + No JavaScript-driven layout shifts — all dimensions must be explicit or reserved + Animations must be CSS-only, respect prefers-reduced-motion, and never delay content visibility + } +} + +## Step 4 — Audit Speed + +auditSpeed(url | localServer) => performanceReport { + Prefer the PageSpeed Insights REST API (no API key required for light usage): + + ``` + GET https://www.googleapis.com/pagespeedonline/v5/runPagespeed + ?url={url}&category=performance&category=accessibility&category=seo + ``` + + 1. Fetch the report; extract Performance score, LCP, CLS, TBT + 2. Flag any metric that misses the target: + - Performance score < 90 + - LCP > 2.5 s + - CLS > 0.1 + - TBT > 200 ms + 3. List specific audit failures and recommended fixes + 4. Re-run after fixes to confirm improvement + + localServer => use Lighthouse CLI (`npx lighthouse {url} --output json --quiet`) if the page is not publicly accessible + + Constraints { + Never ship a page with Performance score < 90 without explicit user approval + Treat accessibility score < 90 as a blocking issue + } +} + +## Step 5 — Review + +review(landingPage) => reviewedPage { + 1. Run /review on all changed files + 2. Walk through the page as a first-time visitor — does the value prop land in 3 seconds? + 3. Verify the single-goal constraint: count distinct CTAs. More than one primary action => fix. + 4. Check objection coverage: pricing, integrations, security, support all visible? + 5. Confirm social proof includes measurable results, not just logos + 6. Run /audit-speed one final time + 7. Resolve all issues found + + Constraints { + Every review finding must be resolved before shipping + } +} + +landingPage = discover |> planSections |> build |> auditSpeed |> review + +Commands { + 🚀 /landing-plan - discover + plan sections for a landing page + 🏗️ /landing-build - build the landing page from an approved section plan + 🔍 /landing-review - review an existing landing page against all constraints + ⚡ /audit-speed - run a PageSpeed Insights audit and report results +} diff --git a/plan.md b/plan.md index b26399be..14dbf79b 100644 --- a/plan.md +++ b/plan.md @@ -22,6 +22,12 @@ **Goal**: Install Context7 MCP server to provide agents access to up-to-date documentation for popular libraries, frameworks, and APIs **Tasks**: 2 tasks (API key gathering, installation execution) +### 📋 Landing Page Skill Epic + +**Status**: 📋 PLANNED +**File**: [`tasks/landing-page-skill-epic.md`](./tasks/landing-page-skill-epic.md) +**Goal**: Add an `aidd-landing-page` skill that guides agents to build high-converting landing pages with clear messaging, focused CTAs, and measurable performance + ### 📋 Context7 GitHub Action Epic **Status**: 📋 PLANNED diff --git a/tasks/landing-page-skill-epic.md b/tasks/landing-page-skill-epic.md new file mode 100644 index 00000000..950fc678 --- /dev/null +++ b/tasks/landing-page-skill-epic.md @@ -0,0 +1,84 @@ +# Landing Page Skill Epic + +**Status**: 📋 PLANNED +**Goal**: Add an `aidd-landing-page` skill that guides agents to build high-converting landing pages with clear messaging, focused CTAs, and measurable performance + +## Overview + +Agents currently lack structured guidance for building landing pages. Without conversion-focused constraints, generated pages tend toward decorative layouts, vague headlines, and competing calls-to-action — all of which hurt conversion. This skill codifies proven landing page principles as machine-readable constraints so agents produce pages that convert by default. + +--- + +## Skill File + +Create the `aidd-landing-page` skill following the AgentSkills.io spec and the project's constraint-based programming style. + +**Requirements**: +- Given an agent is asked to build a landing page, should have a discoverable skill file at `.cursor/skills/aidd-landing-page/SKILL.md` with valid AgentSkills.io frontmatter +- Given the skill is loaded, should define a role preamble, Capabilities block, and Constraints block that encode all ten landing page principles +- Given the skill defines commands, should expose `/landing-plan`, `/landing-build`, `/landing-review`, and `/audit-speed` subcommands + +--- + +## Conversion Constraints + +Encode the core landing page rules as enforceable constraints. + +**Requirements**: +- Given a landing page headline, should explain what the product does so a visitor understands the value proposition within 3 seconds +- Given a landing page, should have exactly one conversion goal — no competing CTAs +- Given above-the-fold content, should contain the value proposition and primary CTA — not decorative imagery +- Given a landing page, should show real product screenshots or interface previews early in the page +- Given a CTA label, should describe the concrete next step rather than a generic phrase like "Get Started" +- Given social proof content, should include testimonials with measurable results — not logos alone +- Given page sections, should each directly advance the visitor toward the single conversion goal — remove any that don't +- Given a landing page, should visibly address common objections (pricing, integrations, security, support) without requiring the visitor to search +- Given design hierarchy, should use size, contrast, and whitespace to create a single visual path from headline to proof to CTA + +--- + +## Performance Audit + +Integrate a PageSpeed Insights audit step into the skill workflow. + +**Requirements**: +- Given a deployed or locally-served landing page URL, should fetch a PageSpeed Insights report and extract Performance score, LCP, CLS, and TBT +- Given a Performance score below 90 or LCP above 2.5 s, should flag the metric and list specific remediation steps +- Given a page that is not publicly accessible, should fall back to Lighthouse CLI for local auditing +- Given an accessibility score below 90, should treat it as a blocking issue + +--- + +## Discover and Plan Workflow + +Define a structured discovery-to-plan flow before any implementation begins. + +**Requirements**: +- Given a landing page brief, should produce a pageSpec covering: single conversion goal, target audience, value proposition, social proof inventory, and objection map +- Given an approved pageSpec, should produce a sectionPlan that maps the visual flow from headline through final CTA +- Given a sectionPlan, should validate that every section serves the single conversion goal and remove any that don't + +--- + +## Build Workflow + +Guide the agent through implementation with performance and accessibility guardrails. + +**Requirements**: +- Given a sectionPlan, should scaffold and implement the page top-down using the project's framework and component library +- Given image assets, should optimize to next-gen formats, lazy-load below-the-fold images, and size hero images to rendered dimensions +- Given animations, should be CSS-only, respect `prefers-reduced-motion`, and never delay content visibility +- Given the build is complete, should automatically run the speed audit and iterate until performance targets are met + +--- + +## Review Workflow + +Provide a structured review checklist that validates all constraints. + +**Requirements**: +- Given a completed landing page, should walk through as a first-time visitor and verify the value proposition lands in 3 seconds +- Given the review step, should count distinct primary CTAs and flag any page with more than one +- Given the review step, should verify objection coverage for pricing, integrations, security, and support +- Given the review step, should confirm social proof includes measurable results +- Given the review step, should run a final speed audit and resolve all findings before shipping