rsc-universal 0.1.1

package/skills/linkedin-carousels/scripts/verify.sh

@@ -0,0 +1,160 @@
+#!/usr/bin/env bash
+#
+# verify.sh — static linter for a `linkedin-carousels` slide-by-slide spec.
+#
+# WHAT IT DOES (read-only; never edits a file)
+#   Network-free static checks over a produced carousel spec (markdown/text):
+#     1. HARD  no cover slide is labeled (cover / slide 1 marker).
+#     2. HARD  no CTA closer with an explicit ask verb (follow/comment/save/share/visit/subscribe).
+#     3. HARD  no portrait/square canvas named (1080x1350 or 1080x1080).
+#     4. HARD  no type floor named (28 or larger) AND/OR no "PDF" export target.
+#     5. HARD  slide count outside 5-15.
+#     6. SOFT  slide count outside the 6-12 band (warn).
+#     7. SOFT  an interior slide block lists 3+ bullet points (crammed; one-idea-per-slide).
+#
+#   Hard violations exit 1. Soft violations warn and exit 0 (spec is judgement).
+#   An empty or clean target is a clean pass (exit 0) — no false failure.
+#
+# HOW TO RUN (point it at YOUR spec, not the skills repo)
+#   ./verify.sh path/to/carousel-spec.md   # check one file
+#   ./verify.sh                            # scan ./ for *.{md,mdx,txt}
+#   ./verify.sh --path specs               # scan a subdirectory
+#   ./verify.sh --strict                   # treat soft warnings as failure (exit 1)
+#
+# EXIT CODES
+#   0  clean, empty target, or warnings-only without --strict
+#   1  a hard violation, or --strict with any warning
+#   2  bad usage
+#
+# POSIX sh, no external deps beyond grep/wc/sort. Runs on stock macOS /bin/sh.
+
+set -eu
+
+if [ -t 1 ]; then
+  RED=$(printf '\033[31m'); GRN=$(printf '\033[32m'); YEL=$(printf '\033[33m'); NC=$(printf '\033[0m')
+else
+  RED=''; GRN=''; YEL=''; NC=''
+fi
+
+warn_count=0
+fail_count=0
+
+ok()   { printf '%s[ ok ]%s %s\n'  "$GRN" "$NC" "$*"; }
+warn() { printf '%s[warn]%s %s\n'  "$YEL" "$NC" "$*"; warn_count=$((warn_count + 1)); }
+fail() { printf '%s[fail]%s %s\n'  "$RED" "$NC" "$*"; fail_count=$((fail_count + 1)); }
+
+usage() { sed -n '2,33p' "$0" | sed 's/^#\{0,1\} \{0,1\}//'; }
+
+TARGET=""
+STRICT=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --strict) STRICT=1 ;;
+    --path) shift; TARGET="${1:-}" ;;
+    -h|--help) usage; exit 0 ;;
+    -*) printf 'unknown option: %s\n' "$1" >&2; usage >&2; exit 2 ;;
+    *) TARGET="$1" ;;
+  esac
+  shift
+done
+[ -n "$TARGET" ] || TARGET="."
+
+# --- collect files ----------------------------------------------------------
+FILES=""
+if [ -f "$TARGET" ]; then
+  FILES="$TARGET"
+elif [ -d "$TARGET" ]; then
+  FILES=$(find "$TARGET" -type f \
+    \( -name '*.md' -o -name '*.mdx' -o -name '*.txt' \) 2>/dev/null \
+    | grep -v '/node_modules/' || true)
+else
+  printf 'no such file or directory: %s\n' "$TARGET" >&2
+  exit 2
+fi
+
+if [ -z "$FILES" ]; then
+  ok "no spec files found under '$TARGET' — nothing to check"
+  exit 0
+fi
+
+# explicit-ask verbs that mark a real CTA (case-insensitive)
+ASK_VERBS='follow|comment|save|share|repost|visit|subscribe|download|sign up|book|grab'
+
+checked=0
+for f in $FILES; do
+  [ -f "$f" ] || continue
+  [ -s "$f" ] || continue
+  checked=$((checked + 1))
+
+  # 1. HARD: a labeled cover slide.
+  if grep -Eiq '(^|[^a-z])cover([^a-z]|$)|slide *0*1 *[—:-]' "$f"; then
+    :
+  else
+    fail "$f: no cover slide labeled — the cover wins or loses the swipe to slide 2"
+  fi
+
+  # 2. HARD: a CTA closer with an explicit ask verb.
+  if grep -Eiq 'cta' "$f" && grep -Eiq "$ASK_VERBS" "$f"; then
+    :
+  elif grep -Eiq "$ASK_VERBS" "$f"; then
+    warn "$f: an ask verb is present but no 'CTA' closer slide is labeled — label the closer"
+  else
+    fail "$f: no CTA closer with an explicit ask (follow/comment/save/share/visit) — every deck needs one ask"
+  fi
+
+  # 3. HARD: a portrait/square canvas.
+  if grep -Eiq '1080 *[x×] *1350|1080 *[x×] *1080' "$f"; then
+    :
+  else
+    fail "$f: no portrait/square canvas named (expected 1080x1350 or 1080x1080) — no landscape for the feed"
+  fi
+
+  # 4. HARD: a type floor (>=28) and PDF export target.
+  if grep -Eiq '(2[89]|[3-9][0-9]|[1-9][0-9][0-9]) *px' "$f"; then
+    :
+  else
+    fail "$f: no type floor >= 28 px stated — body is read on a phone, anything smaller is a stop"
+  fi
+  if grep -Eiq '(^|[^a-z])pdf([^a-z]|$)' "$f"; then
+    :
+  else
+    fail "$f: no PDF export target named — PDF is the only format that renders consistently"
+  fi
+
+  # 5/6. slide count. Count distinct 'slide N' markers (case-insensitive).
+  count=$(grep -Eio 'slide *0*[0-9]+' "$f" 2>/dev/null \
+    | grep -Eo '[0-9]+' | sort -un | wc -l | tr -d ' ')
+  if [ "${count:-0}" -gt 0 ]; then
+    if [ "$count" -lt 5 ] || [ "$count" -gt 15 ]; then
+      fail "$f: ${count} slides — outside the 5-15 hard range (< 5 underdelivers, > 15 loses people)"
+    elif [ "$count" -lt 6 ] || [ "$count" -gt 12 ]; then
+      warn "$f: ${count} slides — outside the 6-12 sweet band (~8 is the target)"
+    fi
+  fi
+
+  # 7. SOFT: a crammed interior slide — 3+ bullet lines within ~12 lines of a slide marker.
+  #    Heuristic: if the file has any run of 3+ consecutive bullet lines, warn once.
+  bullets=$(grep -Ec '^[[:space:]]*([-*•]|[0-9]+\.) ' "$f" 2>/dev/null || true)
+  if [ "${bullets:-0}" -ge 3 ]; then
+    max_run=$(awk '
+      /^[[:space:]]*([-*•]|[0-9]+\.) /{run++; if(run>max)max=run; next}
+      {run=0}
+      END{print max+0}' "$f")
+    if [ "${max_run:-0}" -ge 3 ]; then
+      warn "$f: a slide block lists ${max_run}+ consecutive bullets — keep one idea per slide, split the rest"
+    fi
+  fi
+done
+
+printf '\n'
+if [ "$fail_count" -gt 0 ]; then
+  fail "$fail_count hard violation(s), $warn_count warning(s) across $checked file(s)"
+  exit 1
+fi
+if [ "$warn_count" -gt 0 ]; then
+  warn "$warn_count warning(s) across $checked file(s)"
+  [ "$STRICT" -eq 1 ] && { printf '%s--strict: treating warnings as failure%s\n' "$RED" "$NC"; exit 1; }
+  exit 0
+fi
+ok "clean — $checked file(s) checked, no violations"
+exit 0

package/skills/linkedin-content/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: linkedin-content
+description: "Use when writing the actual words of one LinkedIn feed post — turning a raw idea, story, or asset into ready-to-paste copy that earns dwell time and comments: a text post, a document/carousel cover + slide copy + caption, or a 30–90s native-video script + caption. Use to fix a weak hook so people tap 'see more', reformat a wall of text for the mobile feed, or get a CTA that provokes a real comment (not 'thoughts?'). Triggers: 'write me a LinkedIn post about X', 'my hook is weak, rewrite the first three lines so people click see more', 'give me a CTA that gets comments not thoughts?', 'should the link go in the post or the first comment?', 'escríbeme un post de LinkedIn que enganche', 'fes-me un post de LinkedIn amb ganxo sobre el llançament'. NOT planning what/when to post or cadence (that is linkedin-strategy), NOT designing the carousel slides/layout/PDF export (that is linkedin-carousels), NOT DM/connection sequences (that is linkedin-outreach), NOT programmatic publish (that is linkedin-api)."
+tags: [linkedin, social-copywriting, hooks, content-writing, dwell-time, ctas, document-posts]
+recommends: [linkedin-strategy, linkedin-carousels, linkedin-outreach, linkedin-api, brand-voice, video-shorts]
+origin: risco
+---
+
+# LinkedIn Content — The Words a Human Pastes Into the Feed
+
+*You write the copy of one LinkedIn post.* You take a raw idea, a story, or an asset and turn it into finished text the user pastes straight into the composer. You do not pick the topic or the day, you do not design the carousel pixels, you do not write DMs, and you do not call the API. You hand over words.
+
+**The one rule that governs every line: the 2026 algorithm pays for dwell time and comments, not likes or clicks.** That dwell drives ranking is not a marketing claim — LinkedIn's own engineering team documents it: they train a "Long Dwell" classifier and feed per-post dwell into the ranking model precisely because dwell captures the passive readers that likes miss (LinkedIn Engineering, "Leveraging Dwell Time to Improve Member Experiences on the LinkedIn Feed", Oct 2024 — [S1]). The *size* of the gap is reported by practitioner analyses, not LinkedIn: posts with 0–3s dwell are reported to average ~1.2% engagement vs. ~15.6% at 61+s, a ~13x gap ([S2], corroborated by [S3]). Treat the mechanism as solid and the multiplier as directional. A 30-second read beats 50 quick likes. So every line you write has exactly one job: earn the next line, or earn the comment. If a sentence does neither, cut it. *Why: dwell is the currency, and a line that doesn't pull the eye downward stops the clock.*
+
+## Sources — what backs the numbers (and how hard)
+
+Every figure below is keyed inline as `[S#]`. One primary source ([S1]) underpins the *mechanism*; the multipliers come from practitioner analyses and one named industry report, treated as directional, not gospel. All accessed 2026-06-02.
+
+- **[S1] — primary, authoritative.** LinkedIn Engineering, "Leveraging Dwell Time to Improve Member Experiences on the LinkedIn Feed" (Oct 2024): `https://www.linkedin.com/blog/engineering/feed/leveraging-dwell-time-to-improve-member-experiences-on-the-linkedin-feed`. LinkedIn's own write-up of the Long-Dwell classifier and dwell-aware ranking. Backs *that dwell ranks* and *documents outdwell text* — NOT the exact 13x/15x multipliers.
+- **[S2] — practitioner analysis.** dataslayer.ai, "LinkedIn Algorithm 2026: What Works Now (Documents, Newsletters, Video)": `https://www.dataslayer.ai/blog/linkedin-algorithm-february-2026-whats-working-now`. Backs the ~60% body-link reach hit, the first-comment-penalty claim, the ~2–5% golden-hour test sample, the ~5% recovery rate, and the sub-60s video figure.
+- **[S3] — practitioner analysis, second source.** meet-lea.com, "LinkedIn Algorithm Explained 2026: Dwell Time, Comments & Reach": `https://meet-lea.com/en/blog/linkedin-algorithm-explained`. Independently states the 1.2% vs. 15.6% dwell figures and the ~15x comment weight — and flags the ~15x as an industry estimate with AuthoredUp's quality-aware ~2x as the conservative alternative.
+- **[S4] — named industry research report.** Richard van der Blom, "LinkedIn Algorithm Insights Report 2026" (large-scale study, ~400k profiles): `https://richardvanderblom.com/`. Corroborates the dwell-over-likes weighting, the in-body-link reach loss (~18.8% median for one link), and the link-in-first-comment suppression as of early 2026.
+
+When a fact rests on [S2] alone for a time-stamped algorithm behavior (notably the first-comment penalty), the body hedges it as *reported*, not confirmed — see the link rule below.
+
+## Boundary — what is yours and what is the sibling's
+
+The nearest miss is **strategy vs. words**. Deciding *whether to post, on what topic, at what cadence* is `../linkedin-strategy/SKILL.md`. Writing *the actual words of this one post* is you. "Plan my month of LinkedIn" routes away; "write this post" stays.
+
+The second is **words vs. pixels**. For a document/carousel post, `../linkedin-carousels/SKILL.md` designs the slides — layout, visual system, PDF export. You write the document post's *text*: the cover-slide line, the per-slide copy, and the feed caption that frames it. Words here, pixels there.
+
+Also route out: connection notes and DM sequences → `../linkedin-outreach/SKILL.md`; programmatic schedule/publish → `../linkedin-api/SKILL.md`; the durable brand tone the copy must obey → `../brand-voice/SKILL.md`; a cross-platform short-form video idea → `../video-shorts/SKILL.md`.
+
+## Step 0 — pick the format first
+
+Each format has a different engagement ceiling and a different structure, so choose before you write a word. This branches, so use the table.
+
+| Format | 2026 avg engagement | Pick it when | Structure you write |
+|---|---|---|---|
+| Document / PDF (carousel) | ~6.6–7.0% (+14% YoY) — highest | The idea is a list, a framework, a teardown, or a before→after that wants pages | Cover line + 3–10 slides of copy + 100–200-word caption |
+| Native video | ~5.6% (+36% YoY, growing 2x faster; ~3x a text post) | A face, a demo, a story that lands better spoken | 30–90s script beats + caption |
+| Text only | Lowest of the three | A sharp story or insight that needs no asset; fastest to ship | One 1,300–1,900-char post |
+
+Per-format engagement rates from [S3] and the named research report [S4]; the document-format edge is corroborated by LinkedIn Engineering's own finding that document/carousel updates generate longer dwell than text or image updates ([S1]). Format choice is a real lever, not a coin flip — a document post can clear ~6x a text-only one on the same idea.
+
+## The hook — the first ~150 characters
+
+The mobile feed truncates after ~150–210 characters (the first ~3 lines) before *see more* ([S2] / [S3]). If those lines don't earn the tap, dwell never starts and the rest of your post is invisible. The hook is the whole game.
+
+Rules, each with its why:
+
+- **Lead with specificity, a number, or tension — not context.** *Why: the reader is scrolling; an abstraction reads as skippable, a concrete claim reads as a promise.*
+- **Front-load the most surprising true thing.** *Why: you have ~150 chars before the cut; spend them on the payoff-seed, not the setup.*
+- **Never open with a greeting or "excited to share / thrilled to announce".** *Why: those words signal an ad, and the eye has learned to skip ads.*
+- **One idea in the first line. The second line escalates it.** *Why: a line break in the visible zone earns its own micro-decision to keep reading.*
+
+| Bad hook | Good hook |
+|---|---|
+| "Excited to share that we hit a new milestone this quarter! 🎉" | "We almost shut the product down in March. Then one churned customer told us why." |
+| "I've been thinking a lot about leadership lately." | "I fired my best engineer. Revenue went up. Here's what that taught me about teams." |
+| "Some thoughts on remote work and productivity." | "We went fully remote and our output dropped 30%. The fix wasn't more meetings." |
+| "Happy to announce our new feature is live!" | "It took 4 rewrites and a near-mutiny to ship one button. Worth it." |
+
+For the full 8–10 pattern library (number-lead, false-start, contrarian, open-loop, named-stakes), see `references/hooks-and-formats.md`.
+
+## The story arc and the character budget
+
+A text post runs **hook → turn → payoff → CTA**. The length sweet spot is **1,300–1,900 characters** — reported as ~47% higher engagement than short posts because it sustains dwell while staying consumable; the hard max is 3,000 ([S3] / [S4]). Budget it:
+
+| Section | Budget | Job |
+|---|---|---|
+| Hook | ~150 chars (first ~3 lines) | Earn the *see more* tap |
+| Turn | ~300–400 chars | The pivot — the thing that wasn't obvious |
+| Payoff | ~600–900 chars | The lesson/story/proof the hook promised |
+| CTA | ~100–200 chars | Provoke a comment only the reader can give |
+
+Don't pad to hit the range; if the idea is genuinely a 700-char post, ship 700. The range is where most stories *should* land, not a quota.
+
+## Line-break formatting — write for the thumb
+
+Short 1–2 sentence paragraphs with line breaks are reported to sustain ~40% longer dwell than a wall of text ([S2] / [S3]). The composer has **no native bold or italic**, so Unicode is the only in-feed emphasis — use it on one or two phrases at most, never a whole line.
+
+Rules: one idea per line; a blank line between thought-blocks; emoji as occasional bullets (▸, →, or a single 📌), never confetti.
+
+```text
+Bad (wall):
+We tried three onboarding flows over six months and the first two failed because they front-loaded configuration before value, which meant users churned before they ever saw the product work, so we rebuilt it around a single first action and activation jumped from 19% to 54% in two weeks which taught us that time-to-value beats feature-completeness every time.
+```
+
+```text
+Good (broken for the thumb):
+We tried three onboarding flows in six months.
+
+The first two failed for the same reason:
+they made users configure before they saw value.
+
+So we cut everything but one first action.
+
+Activation went 19% → 54% in two weeks.
+
+The lesson: time-to-value beats feature-completeness. Every time.
+```
+
+## The CTA that earns comments
+
+Comments are widely reported as ~15x the weight of likes ([S2] / [S3]) — though that exact multiplier is an industry estimate, and AuthoredUp's quality-aware analysis puts it closer to ~2x ([S3]). Either way the direction holds: a comment outweighs a like, and a meaningful comment more still. So the CTA's only job is to provoke a comment the reader is *uniquely* able to give. *Why: a generic ask gets a generic like; a specific question gets a sentence, and a sentence is a comment.*
+
+Ask for the reader's own experience, number, or disagreement — something they can answer without you. Banlist of dead CTAs that get scrolled past: "thoughts?", "agree?", "let me know below", "what do you think?", "drop a comment".
+
+| Dead CTA | Live CTA |
+|---|---|
+| "Thoughts?" | "What's the one onboarding step you'd kill if you could?" |
+| "Agree?" | "If you've shipped fully remote — did output go up or down for you? Curious where I'm wrong." |
+| "Let me know below." | "What metric finally made *you* trust an activation number?" |
+
+## Format-specific bodies
+
+**Document / PDF post** — write three things, never the slide design:
+1. **Cover line** — the hook, sized to be readable as a thumbnail; it does the *see more* job here too.
+2. **Per-slide copy** — one idea per slide, **3–10 slides** (the high-performing range; [S2] / [S4]); each slide ends pulling the swipe.
+3. **Caption** — ~100–200 words that frame the deck and carry the comment-CTA.
+
+Hand the slide *text* to `../linkedin-carousels/SKILL.md` for layout and export.
+
+**Native video** — best at **30–90 seconds**, and sub-60s short-form is reported to get ~53% more engagement than longer ([S2]). Write:
+1. **Script beats** — hook in the first 3 seconds (the visual hook, since most watch muted), then turn → payoff → spoken CTA.
+2. **Caption** — the text-post arc in miniature, ending on the comment-CTA.
+
+Full templates with char budgets for all three formats live in `references/hooks-and-formats.md`.
+
+## The link rule and the golden hour
+
+**Put no link in the post body.** A body link is reported to cost ~60% of reach ([S2], with [S4] measuring one in-body link at ~18.8% median reach loss — both agree the hit is large; the exact figure varies by sample). The riskier, time-stamped claim is that the old "link in the first comment" workaround is *also* penalized as of early 2026 — reported by both [S2] and the named research report [S4], which describes external-link comments being suppressed. It is not confirmed by LinkedIn, so treat it as a strong reported signal, not a law: the safe default is to assume the escape hatch is at least partly closed. If a link is non-negotiable, accept the reach hit knowingly; otherwise put the URL nowhere and tell people to DM/comment for it. *Why: LinkedIn suppresses anything that pulls users off-platform, and the comment trick is widely reported as detected.*
+
+**Work the golden hour.** LinkedIn first tests a post on only ~2–5% of your network in the first hour; only ~5% of posts that underperform in that window are reported to ever recover broader reach ([S2]). The first-hour-test mechanism is consistent with LinkedIn Engineering's described pipeline of scoring early engagement on an initial sample before expanding distribution ([S1]). So after posting: reply to every comment fast, and seed the thread with a real follow-up question. The post you abandon for an hour is the post the algorithm abandons.
+
+## Learn from 02-DOCS
+
+If the project has an `02-DOCS/` post log, read it before drafting: pull prior posts and their measured outcomes (impressions, dwell, comments, saves) and bias the new draft toward the hook patterns, formats, and CTA types that actually performed *for this account* — not generic best practice. Then log the new post back with its hook, format, and CTA type so the next draft is sharper. The front-matter schema (date, format, hook, cta_type, impressions, dwell_s, comments, saves) is in `references/hooks-and-formats.md`.
+
+## Anti-patterns
+
+| Anti-pattern | Why it kills the post | Fix |
+|---|---|---|
+| Link in the body (or "link in first comment") | ~60% reach hit; comment trick reported penalized too ([S2]/[S4]) | URL nowhere; offer it via DM/comment, or accept the hit knowingly |
+| Greeting / "excited to share" hook | Reads as an ad; eye skips before *see more* | Open on the most surprising true thing, ≤150 chars |
+| Wall of text | Tanks dwell ~40% vs. broken copy | 1–2 sentence paragraphs, blank line between blocks |
+| "Thoughts?" CTA | Gets a like, not a comment; comments weigh ~15x | Ask what only the reader can answer |
+| Post then ghost the golden hour | Underperforms the first-hour test → ~5% recover | Reply fast, seed a real question for 60–90 min |
+| Chasing likes over comments | Likes are the weakest signal | Write the arc toward a comment, not applause |
+| Padding to hit 1,900 chars | Padding lowers dwell, doesn't raise it | Ship the true length; the range is a target, not a quota |
+| Picking text by default | Text is the lowest-ceiling format | Choose format from the idea (Step 0) — document/video often win |
+
+## Before you hand over the draft
+
+Run the mechanical lint on the drafted file — it catches reach-killers, not judgment:
+
+```bash
+scripts/verify.sh path/to/draft.md
+```
+
+It flags an over-long hook line, an http(s) link in the body, banned dead CTAs, and wall-of-text blocks. It is read-only and exits 0 on a clean or empty file. Judgment (does the hook actually pull? is the CTA answerable?) stays with you and the capability eval.

package/skills/linkedin-content/evals/README.md

@@ -0,0 +1,13 @@
+# Evals — linkedin-content
+
+These cases are read by the catalog's routing harness (or by hand); there is no
+bundled automated scorer. `should_trigger` asserts the SKILL.md description and body
+are specific enough that each listed prompt would load `linkedin-content`;
+`should_not_trigger` asserts a near-miss prompt routes to the named real sibling
+instead (every `route_to` id must exist in the catalog); and `capability` is a
+rubric — feed the scenario to an agent with this skill loaded and grade the generated
+post against every `must_include` bullet as pass/fail. To sanity-check a *generated*
+draft against the mechanical rules separately, run `../scripts/verify.sh path/to/draft.md`
+— it is read-only and flags an over-long hook line, an http(s) body link, banned dead
+CTAs, and wall-of-text blocks. Judgment (does the hook pull? is the CTA answerable?)
+stays with the capability rubric; verify.sh only catches mechanical reach-killers.

package/skills/linkedin-content/evals/cases.yaml

@@ -0,0 +1,62 @@
+skill: linkedin-content
+
+# Prompts that MUST load `linkedin-content`. The skill owns THE WORDS of one
+# LinkedIn feed post — text, document/carousel copy (cover + slides + caption),
+# or a native-video script + caption — written to earn dwell and comments. It
+# does NOT plan what/when to post (linkedin-strategy), design the carousel
+# pixels (linkedin-carousels), write DMs/connection notes (linkedin-outreach),
+# or publish via API (linkedin-api).
+should_trigger:
+  - prompt: "Write a LinkedIn post about how we cut onboarding from 3 weeks to 3 days."
+    why: "Core job — turn a raw before→after story into a finished text post with hook, arc, and comment-CTA."
+
+  - prompt: "My hook is weak — rewrite the first three lines so people actually click 'see more'."
+    why: "Non-obvious: the user names the symptom (first three lines / see more), not the skill. The ~150-char hook rule and the Bad→Good hook table answer it directly."
+
+  - prompt: "Turn this into a LinkedIn document/carousel — give me the cover line and the slide copy."
+    why: "Document-post TEXT (cover + per-slide copy + caption) is owned here; only the slide layout/export belongs to linkedin-carousels."
+
+  - prompt: "Write a 45-second native-video script and the caption that goes with it."
+    why: "Native-video format (30–90s beats + caption) is one of the three formats this skill writes."
+
+  - prompt: "Give me a CTA that gets comments, not 'thoughts?'."
+    why: "Non-obvious phrasing — the comment-earning CTA + the dead-CTA banlist exist for exactly this; comments weigh ~15x likes."
+
+  - prompt: "fes-me un post de LinkedIn amb ganxo sobre el llançament"
+    why: "Catalan trigger — same skill regardless of language; the hook rules and arc apply."
+
+  - prompt: "Should the link go in the post or in the first comment?"
+    why: "Non-obvious: the body-link ~60% reach hit AND the now-dead first-comment workaround are a load-bearing fact this skill owns."
+
+should_not_trigger:
+  - prompt: "Plan my LinkedIn content calendar and pillars for next month."
+    route_to: linkedin-strategy
+    why: "What/when/cadence is strategy; this skill only writes the words of one post inside that plan."
+
+  - prompt: "Design the actual carousel slides — layout and visuals — and export the PDF."
+    route_to: linkedin-carousels
+    why: "Pixels, not copy. linkedin-content writes the slide TEXT; the visual deck and export are linkedin-carousels."
+
+  - prompt: "Write connection requests and a DM follow-up sequence for these prospects."
+    route_to: linkedin-outreach
+    why: "Outbound 1:1 messages, not a public feed post — different playbook entirely."
+
+  - prompt: "Programmatically schedule and publish this post via the LinkedIn API."
+    route_to: linkedin-api
+    why: "Shipping/automation, not writing; the API integration is linkedin-api."
+
+  - prompt: "Define our durable LinkedIn brand tone and the words we never use."
+    route_to: brand-voice
+    why: "The reusable voice the copy must obey is brand-voice; this skill consumes that voice to write one post, it doesn't define it."
+
+capability:
+  - scenario: "Given a rough story — 'we lost our biggest client and here's what I learned about retention' — produce a finished, ready-to-paste LinkedIn text post."
+    must_include:
+      - "A hook in the first ~150 characters with specificity or tension and NO greeting / no 'excited to share'."
+      - "The hook's first line reads complete on its own (won't truncate mid-clause on mobile)."
+      - "A clear hook → turn → payoff → CTA arc."
+      - "Total length lands ~1,300–1,900 characters (or a justified shorter length, not padded)."
+      - "Mobile line breaks: 1–2 sentence paragraphs with blank lines between blocks — no wall of text."
+      - "A comment-earning CTA that asks what only the reader can answer — never 'thoughts?' / 'agree?'."
+      - "No link in the body, and no 'link in first comment' suggestion."
+      - "A note about working the golden hour (reply fast, seed a question in the first 60–90 min)."

package/skills/linkedin-content/references/hooks-and-formats.md

@@ -0,0 +1,114 @@
+# Hooks, format templates, and the 02-DOCS post log
+
+Depth offloaded from `SKILL.md`. Use this when you need the full hook library, a
+fill-in template for any of the three formats, or the schema for logging posts and
+reading outcomes back. Every char budget and engagement figure traces to the keyed
+sources `[S1]`–`[S4]` listed in `SKILL.md` ("Sources" section, all accessed
+2026-06-02); the multipliers there are flagged as directional, not confirmed.
+
+## Hook pattern library
+
+The hook lives in the first ~150 characters — the visible zone before *see more*.
+Pick the pattern that fits the idea; each one front-loads tension or specificity so
+the eye keeps moving.
+
+| # | Pattern | Shape | Bad | Good |
+|---|---|---|---|---|
+| 1 | Number-lead | A surprising metric first | "We grew a lot last year." | "We added $1.2M ARR with zero paid ads. Here's the only channel that worked." |
+| 2 | False-start | Admit the thing people won't | "Some lessons on hiring." | "I hired for culture fit for 5 years. It was the most expensive mistake I made." |
+| 3 | Contrarian | Reject the consensus | "Networking is important." | "Networking events are a waste of time. I closed our biggest deal in a DM." |
+| 4 | Open-loop | Promise an answer, withhold it | "Here's how we handle churn." | "One churned customer's exit interview changed our whole roadmap. I almost deleted the email." |
+| 5 | Named-stakes | Put a real cost on the line | "Thoughts on pricing." | "We raised prices 40% expecting churn. We lost 2 customers and gained $300k." |
+| 6 | Before→after | Two states, sharp delta | "Onboarding improved." | "Onboarding took 3 weeks. Now it takes 3 days. The change was one deleted step." |
+| 7 | Confession | A mistake you own | "Mistakes were made." | "I ghosted a candidate for 6 weeks. He's now a competitor's VP. Here's what I'd do differently." |
+| 8 | Pattern-callout | Name a thing everyone does | "Meetings can be inefficient." | "Every 'quick sync' on your calendar is a decision someone was afraid to make alone." |
+| 9 | Question-trap | A question the reader can't not answer | "Do you struggle with focus?" | "When did 'busy' become the answer to 'how are you?' I want to opt out." |
+| 10 | Receipt | Lead with proof | "Our product helps teams." | "47 support tickets in one week, all the same complaint. We rebuilt the feature in a sprint." |
+
+Rule across all ten: the first line must be readable and complete on its own line on
+mobile — do not let a thought run past the truncation point mid-clause.
+
+## Text post template (1,300–1,900 chars)
+
+```text
+[HOOK — ~150 chars, one of the 10 patterns. First line readable alone.]
+[Second line escalates the hook.]
+
+[TURN — ~300–400 chars. The pivot: the non-obvious thing.
+1–2 sentence paragraphs, blank line between blocks.]
+
+[PAYOFF — ~600–900 chars. The story/lesson/proof the hook promised.
+One idea per line. Use → or ▸ as occasional bullets, not confetti.
+Unicode emphasis on at most one or two phrases.]
+
+[CTA — ~100–200 chars. A question only the reader can answer.
+Never "thoughts?".]
+
+[No link. No "link in comments". If a link is unavoidable, decide knowingly.]
+```
+
+## Document / PDF post template (3–10 slides)
+
+```text
+COVER (slide 1):
+  [Hook line, large, thumbnail-readable — does the see-more job here too.]
+
+SLIDES 2–N (3–10 total):
+  Slide 2: [One idea. Ends pulling the swipe.]
+  Slide 3: [One idea.]
+  ...
+  Slide N: [Payoff + the single takeaway.]
+
+CAPTION (100–200 words):
+  [Frame the deck in the text-post arc, miniaturized.]
+  [End on a comment-earning CTA.]
+```
+
+Hand the slide *text* to `../linkedin-carousels/SKILL.md` for layout, visual system,
+and PDF export. You write words; that skill renders pixels.
+
+## Native-video template (30–90s)
+
+```text
+SCRIPT BEATS:
+  0–3s   HOOK (visual + spoken; most viewers are muted, so the on-screen
+         text must carry it alone).
+  3–15s  TURN — the non-obvious pivot.
+  15–75s PAYOFF — story/proof, escalating.
+  last   SPOKEN CTA — one answerable question.
+
+CAPTION (text-post arc in miniature):
+  [Hook line + 2–4 short lines + comment-CTA. No body link.]
+```
+
+Sub-60s short-form gets ~53% more engagement than longer; 30–90s is the band. For a
+cross-platform vertical short (Reels/TikTok/Shorts), route to `../video-shorts/SKILL.md`.
+
+## The 02-DOCS post log
+
+Log every published post so the next draft can learn. One markdown file per post (or
+a single appended log), front-matter first:
+
+```yaml
+---
+date: 2026-06-02        # publish date
+format: text            # text | document | video
+hook: "We almost shut the product down in March."
+hook_pattern: confession # one of the 10 patterns above
+cta_type: experience-ask # experience-ask | disagreement-ask | number-ask
+char_count: 1640
+# --- filled in later, once metrics land ---
+impressions: 0
+dwell_s: 0              # avg dwell in seconds (the currency)
+comments: 0
+saves: 0
+---
+[the full post body, for reference]
+```
+
+**Reading it back to bias drafts:** before writing, scan the log and sort by
+`dwell_s` and `comments` (the weighted signals), not impressions. Note which
+`hook_pattern`, `format`, and `cta_type` recur among the top performers *for this
+account*, and lean the new draft toward them. A pattern that wins generically but
+flops for this audience loses to one that wins here. After publishing, append the new
+row; fill metrics in when they stabilize (~48–72h).