cardiology-science-for-people
Write rigorous, accurate cardiology science for general audiences—not doctors. Use when the user wants to: (1) Explain clinical trials or research in plain English, (2) Write science content an 8th grader can understand WITHOUT dumbing it down, (3) Create thought leadership for the intelligent public rather than medical peers, (4) Transform complex cardiology findings into stories and narratives, (5) Write pieces where readers DON'T need another LLM to understand the explanation. Maintains full scientific rigor with PubMed citations for verification while avoiding academic language, trial acronyms, and intimidating statistics.
What this skill does
# Cardiology Science for People
Write rigorous cardiology science that real people actually want to read. Same accuracy as an academic editorial. Zero intimidation.
## Core Philosophy
**The problem you're solving**: Academic writing says correct things in ways that require a medical degree to understand. Dumbed-down content oversimplifies to the point of being wrong.
**The solution**: Write scientifically accurate content in the language people actually use. An 8th grader should understand it. A cardiologist should find no errors.
**What "for people" means**:
- Stories, not statistics
- What it means for them, not what the trial showed
- Names of conditions, not trial acronyms
- Explanations that stand alone, not explanations requiring explanations
## The Three Golden Rules
### 1. Lead with the Human Story
**Never start with**: "The STEP-HFpEF trial randomized 529 patients..."
**Always start with**: "If you have heart failure and struggle to walk up stairs, there's finally a drug that might help you do more of what you love."
The trial is evidence. The story is why anyone should care.
### 2. Translate Statistics to Meaning
**Never write**: "The hazard ratio was 0.65 (95% CI 0.51-0.82), representing a 35% relative risk reduction."
**Instead write**: "For every 100 people who took the drug, about 8 fewer had heart attacks compared to those who didn't. That's a meaningful difference—roughly 1 in 12 people benefited."
Always convert to:
- "X out of 100 people..." (absolute terms)
- "About 1 in Y people benefited"
- Real-world comparisons: "roughly the same benefit as..."
- Time frames that matter: "over the next 5 years..."
### 3. Background the Evidence, Foreground the Understanding
**Academic style**: "The DAPA-HF trial (McMurray et al., NEJM 2019) demonstrated that dapagliflozin reduced the composite of worsening heart failure or cardiovascular death by 26% (HR 0.74, 95% CI 0.65-0.85)."
**People style**: "A diabetes drug called dapagliflozin turns out to help hearts too—even in people without diabetes. In a large study, people taking this drug were about a quarter less likely to end up in the hospital for heart failure or die from heart problems. Scientists aren't entirely sure why it works, but the evidence is strong enough that cardiologists now prescribe it regularly."
The citation goes in your references section. The reader gets the understanding.
## Writing Process
### Step 1: Research (Same Rigor as Editorial Skill)
Use PubMed MCP exactly as you would for academic writing:
- `PubMed:search_articles` for finding trials and evidence
- `PubMed:get_article_metadata` for details
- `PubMed:get_full_text_article` when available
**Target**: 5-8 solid references from major journals (NEJM, JAMA, Lancet, JACC, Circulation, EHJ).
**Purpose of citations**: YOUR verification that you got the science right, and the user's ability to check your work. NOT to impress readers.
### Step 2: Extract the Core Story
Before writing, answer:
1. **What's the one thing readers need to understand?**
- Not what the trial showed. What it MEANS.
2. **Why should someone care?**
- Not "this is important because..."
- What changes in their life, their risk, their choices?
3. **What's the story arc?**
- What was the problem before?
- What did we discover?
- What's different now?
4. **What's the "so what" for a reader's life?**
- Should they ask their doctor about something?
- Should they change a behavior?
- Should they feel relieved or concerned?
### Step 3: Write for Understanding
#### Structure (Flexible—Narrative Flow Over Sections)
Unlike the rigid 7-section editorial, structure should serve the story:
**Option A: Problem → Discovery → Meaning**
- Start with a relatable problem ("Many people with heart failure can barely walk to the mailbox")
- Introduce the discovery as a story ("Then scientists tried something unexpected...")
- Land on what it means for the reader ("For you, this means...")
**Option B: Surprising Fact → Explanation → Implications**
- Hook with something unexpected ("A diabetes drug is now one of the best heart failure treatments")
- Explain how we got here
- Connect to reader's life
**Option C: Person's Story → Science → Takeaway**
- Start with a composite patient scenario
- Weave in the science
- End with actionable understanding
#### Voice Guidelines
**Write like a knowledgeable friend who happens to be a cardiologist—not like an expert talking down.**
DO:
- "Here's what this actually means for you..."
- "The short version is..."
- "Scientists figured out that..."
- "What surprised researchers was..."
- "In plain terms..."
DON'T:
- "It's important to understand that..."
- "One must consider..."
- "The clinical implications are..."
- "Healthcare providers should..."
#### Handling Trial Names
**General rule**: If YOU need the trial name to verify the science, keep it in your references. The reader almost never needs it.
**When to mention trial names**: Only when the name itself is widely known by patients (rare) or when you're writing a longer piece where you'll reference the same trial multiple times.
**How to handle**:
- ❌ "The SELECT trial showed..."
- ✅ "A large study of people taking semaglutide..."
- ✅ "When researchers tested this in over 17,000 patients..."
- ✅ "The biggest study to date found..." (cite in references)
#### Handling Statistics
**Convert ALL statistics to human terms:**
| Academic | For People |
|----------|------------|
| 35% relative risk reduction | About 1 in 3 fewer events |
| HR 0.74 (95% CI 0.65-0.85) | Roughly a quarter less likely |
| NNT = 25 | For every 25 people treated, 1 person benefits |
| p < 0.001 | Very strong evidence (drop this entirely usually) |
| Median follow-up 4.2 years | After about 4 years |
| Primary composite endpoint | The main things researchers were counting |
**When to use numbers:**
- Use actual numbers for things people can visualize: "3,000 patients" is fine
- Use fractions/ratios for effects: "about 1 in 10" is better than "10%"
- Use comparisons: "roughly the same risk reduction as stopping smoking"
#### Word Substitutions
See `references/plain-language-guide.md` for complete list. Quick reference:
| Medical | Plain |
|---------|-------|
| myocardial infarction | heart attack |
| cardiovascular death | death from heart problems |
| hospitalization for heart failure | ending up in the hospital because your heart is struggling |
| composite endpoint | combination of outcomes |
| randomized controlled trial | well-designed study where patients were randomly assigned |
| placebo | sugar pill / inactive treatment |
| statistically significant | unlikely to be a coincidence |
| hazard ratio | risk comparison |
| mechanism of action | how the drug works |
| pharmacokinetics | how the drug moves through your body |
| adverse events | side effects |
| contraindicated | shouldn't be used |
| comorbidities | other health conditions |
| titration | adjusting the dose |
| prognosis | likely outcome |
### Step 4: Verify Accuracy
Before finalizing, confirm:
- Every factual claim has a PubMed reference you can cite
- Numbers haven't been distorted in translation
- Simplification hasn't created inaccuracy
- A cardiologist reading this would nod, not cringe
### Step 5: Add References Section
At the end, include a "Sources" or "The Evidence" section:
**Format**:
```
## The Evidence
1. The heart failure drug study mentioned: McMurray JJV et al. Dapagliflozin in Patients with Heart Failure and Reduced Ejection Fraction. N Engl J Med. 2019;381(21):1995-2008. DOI: 10.1056/NEJMoa1911303
2. The weight loss medication study: Lincoff AM et al. Semaglutide and Cardiovascular Outcomes in Obesity without Diabetes. N Engl J Med. 2023;389(24):2221-2232. DOI: 10.1056/NEJMoa2307563
```
This section serves two purposes:
1. Your user can verify you interpreted the science correctly
2. Curious readers can dig deeper
## Length Guidelines
**ShoRelated in AI Agents
skill-development
IncludedComprehensive meta-skill for creating, managing, validating, auditing, and distributing Claude Code skills and slash commands (unified in v2.1.3+). Provides skill templates, creation workflows, validation patterns, audit checklists, naming conventions, YAML frontmatter guidance, progressive disclosure examples, and best practices lookup. Use when creating new skills, validating existing skills, auditing skill quality, understanding skill architecture, needing skill templates, learning about YAML frontmatter requirements, progressive disclosure patterns, tool restrictions (allowed-tools), skill composition, skill naming conventions, troubleshooting skill activation issues, creating custom slash commands, configuring command frontmatter, using command arguments ($ARGUMENTS, $1, $2), bash execution in commands, file references in commands, command namespacing, plugin commands, MCP slash commands, Skill tool configuration, or deciding between skills vs slash commands. Delegates to docs-management skill for official documentation.
reprompter
IncludedTransform messy prompts into well-structured, effective prompts — single or multi-agent. Use when: "reprompt", "reprompt this", "clean up this prompt", "structure my prompt", rough text needing XML tags and best practices, "reprompter teams", "repromptception", "run with quality", "smart run", "smart agents", multi-agent tasks, audits, parallel work, anything going to agent teams. Don't use when: simple Q&A, pure chat, immediate execution-only tasks. See "Don't Use When" section for details. Outputs: Structured XML/Markdown prompt, quality score (before/after), optional team brief + per-agent sub-prompts, agent team output files. Success criteria: Single mode quality score ≥ 7/10; Repromptception per-agent prompt quality score 8+/10; all required sections present, actionable and specific.
adaptive-compaction
IncludedAdaptive add-on policy and recovery layer that decides WHEN to compact, prune, snapshot, or fork -- replacing fixed-percent auto-compaction across Claude Code, Codex, and MCP-capable hosts. Trigger on auto-compact timing or damage: "when should I compact", "is it safe to compact now or start a fresh session", "auto-compact fires too early/mid-task", "switching to an unrelated task but the window still has space", "context rot", "answers get worse the longer the session runs", "the agent forgot the plan or my decisions after it summarized", "add a layer on top that manages context without changing the agent", raising autoCompactWindow to give the policy room, or installing/tuning a cross-tool compaction policy or PreCompact hook -- even when "compaction" is never said but the problem is context-window pressure or post-summarization memory loss. Do NOT use to summarize a conversation, build RAG, write a summarization prompt (decides WHEN not HOW), or answer max-context-length trivia.
agent-skill-creator
IncludedCreate cross-platform agent skills from workflow descriptions. Activates when users ask to create an agent, automate a repetitive workflow, create a custom skill, or need advanced agent creation. Triggers on phrases like create agent for, automate workflow, create skill for, every day I have to, daily I need to, turn process into agent, need to automate, create a cross-platform skill, validate this skill, export this skill, migrate this skill. Supports single skills, multi-agent suites, transcript processing, template-based creation, interactive configuration, cross-platform export, and spec validation.
llm-wiki
IncludedUse when building or maintaining a persistent personal knowledge base (second brain) in Obsidian where an LLM incrementally ingests sources, updates entity/concept pages, maintains cross-references, and keeps a synthesis current. Triggers include "second brain", "Obsidian wiki", "personal knowledge management", "ingest this paper/article/book", "build a research wiki", "compound knowledge", "Memex", or whenever the user wants knowledge to accumulate across sessions instead of being re-derived by RAG on every query.
skill-master
IncludedAgent Skills authoring, evaluation, and optimization. Create, edit, validate, benchmark, and improve skills following the agentskills.io specification. Use when designing SKILL.md files, structuring skill folders (references, scripts, assets), ingesting external documentation into skills, running trigger evals, benchmarking skill quality, optimizing descriptions, or performing blind A/B comparisons. Keywords: agentskills.io, SKILL.md, skill authoring, eval, benchmark, trigger optimization.