hero-section-diagnosis
Skill2 starsChanged 4 months agoMITView on GitHub
Reads the headline, subhead, visual and primary CTA as one unit and finds where they contradict each other. Use when each hero element looks fine alone but the section as a whole does not land, or before a hero rewrite ships.
In this repository26 other files it gives its agents.
- AGENTS.mdAGENTS.md
- above-the-fold-clarity-reviewSkill
- accessibility-conversion-blocker-checkSkill
- comparison-page-positioning-reviewSkill
- conversion-leak-finderSkill
- cta-clarity-checkSkill
- form-friction-finderSkill
- google-ads-landing-page-experience-reviewSkill
- landing-page-ab-test-readoutSkill
- landing-page-copy-readability-passSkill
- landing-page-scale-readiness-checkSkill
- landing-page-triageSkill
- lead-form-sales-handoff-checkSkill
- mobile-conversion-reviewSkill
- objection-map-builderSkill
- offer-clarity-diagnosisSkill
- page-length-fit-checkSkill
- page-speed-impact-reviewSkill
- paid-traffic-message-match-auditSkill
- popup-and-overlay-timing-reviewSkill
- pricing-page-clarity-reviewSkill
- social-proof-strength-auditSkill
- thank-you-page-opportunity-auditSkill
- traffic-temperature-match-reviewSkill
- trial-vs-demo-path-decisionSkill
- trust-signal-auditSkill
The file
We split this skill into the rules it gives an agent
10 rules. About 0 are common, 9 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈9
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 18
all four hero elements together: headline, subhead, visual, primary CTA.
- Distinctive: line 22
If the visual is described rather than supplied, say the visual findings are based on a description.
- Very specific: line 24
Not for: what is visible without scrolling (above-the-fold-clarity-review), or whether the offer is specific (offer-clarity-diagnosis).
- Distinctive: line 29
Check whether the hero matches traffic intent and buyer stage.
- Distinctive: line 40
Do not rank these findings by conversion impact without data.
- Distinctive: line 41
Never rewrite all four at once.
- Distinctive: line 66
Do not rewrite the whole hero unless asked.
- Distinctive: line 67
Do not judge a visual from a description without saying so.
- Distinctive: line 68
Do not use taste language about the visual.
- Distinctive: line 69
Do not claim a conversion impact for a hero change.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Hero Section Diagnosis
Use this skill when
- the hero elements are all available and the section reads as four separate decisions rather than one argument.
- each hero element looks fine reviewed alone, and the section still does not land.
- the headline and the subhead appear to be speaking to two different people.
This skill reads the four hero elements as one argument. For what is visible without scrolling, use above-the-fold-clarity-review.
Required input
- all four hero elements together: headline, subhead, visual, primary CTA. Partial input produces a partial review, and this skill is specifically about the interaction between them.
- what the product does, in the team's own words, so the hero can be checked against it.
- who the hero is meant to address.
- optional: any variant of the hero that has run before, and how it performed.
- If the visual is described rather than supplied, say the visual findings are based on a description.
Not for: what is visible without scrolling (above-the-fold-clarity-review), or whether the offer is specific (offer-clarity-diagnosis).
Analysis workflow
- Assess headline, subheadline, primary CTA, visual, proof cue and form entry point as one decision unit.
- Check whether the hero matches traffic intent and buyer stage.
- Flag hero failures: vague headline, no concrete outcome, weak proof, no audience cue, buried CTA or visual noise.
- Compare hero promise with downstream section content and form commitment.
- Recommend a revised hero structure with exact message roles for each element.
Decision rules
- The four elements have to support one argument. Name the argument each one makes; where two differ, that is the finding.
- An audience change between headline and subhead is the most common and most expensive contradiction. Check it first.
- The CTA has to match the buying motion the copy implies. "Get started free" under enterprise-grade language is a contradiction, not a preference.
- A visual that carries no information about the product wastes the largest element in the section. Say what it currently communicates, which is often nothing.
- Do not rank these findings by conversion impact without data. Say the ranking is judgement when it is.
- Never rewrite all four at once. Name which single element is off-argument, and fix that one.
Output format
| Element | The argument it makes | Audience it addresses | Agrees with the others |
| Headline / subhead / visual / CTA | One line | Named audience | Yes, or which element it contradicts |
End with:
The section's actual argument:one sentence, or "three different arguments" with the listThe off-argument element:which one, and why it was chosenDecision:rewrite one element / choose the audience first / test / ask for dataMissing data:what would move the ranking from judgement to measurement
Practical example
User: "Headline: Stop guessing which ads work. Subhead: Enterprise-grade attribution infrastructure for modern data teams. Visual: a stock photo of a smiling team in an office. CTA: Get started free. This hero has been live 5 months and was never tested against anything."
Assistant should note: the headline speaks to an operator's frustration and the subhead speaks to a data team's procurement, so the section changes audience between line 1 and line 2; the visual carries no information about the product and could sit on any page in any category, which wastes the largest of the 4 elements; Get started free promises self-serve while enterprise-grade infrastructure implies a sales process, so the CTA and the subhead disagree about how buying works. Four elements, three different arguments.
Then: the fix is choosing which audience the hero addresses before rewriting a word, and the off-argument element is the subhead, because the headline and the CTA already agree on a self-serve operator. What this cannot conclude is the size of the cost, because 5 months live with no test and no conversion data supplied means there is no baseline to compare against; the ranking of the three defects is judgement, stated as judgement.
Guardrails
- Do not rewrite the whole hero unless asked.
- Do not judge a visual from a description without saying so.
- Do not use taste language about the visual. Say what it communicates.
- Do not claim a conversion impact for a hero change.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

