rsc-universal 0.1.1

package/skills/article-writing/references/ai-tell-banlist.md

@@ -0,0 +1,114 @@
+# AI-tell banlist + E-E-A-T self-review
+
+The single source of truth for the fluff/AI-tell phrases. `scripts/verify.sh` greps the draft against the fenced `BANLIST` block below — keep **one phrase per line**, lowercase, so the script can read it. The padding patterns and the E-E-A-T self-review are for the human/agent pass; the script only handles the literal phrase grep.
+
+## BANLIST
+
+These are case-insensitive substrings. A match is a fail — rewrite or delete the sentence.
+
+```text
+in today's fast-paced world
+in today's digital age
+in the world of
+when it comes to
+it's important to note that
+it's worth noting that
+it is worth noting
+needless to say
+at the end of the day
+let's dive in
+let's dive into
+let's explore
+dive deep into
+navigating the landscape
+navigating the world of
+the ever-evolving landscape
+unlock the power of
+unleash the power of
+unlock the potential
+harness the power of
+take your x to the next level
+in conclusion
+in summary,
+when all is said and done
+a game-changer
+game changer in the
+the key takeaway is
+without further ado
+look no further
+whether you're a beginner or
+this comprehensive guide
+in this article, we will
+buckle up
+rest assured
+it goes without saying
+plays a crucial role in
+plays a vital role
+a testament to
+embark on a journey
+the realm of
+```
+
+## Padding patterns (rewrite, not just delete)
+
+These are not single phrases the grep catches; they are shapes. Spot them in review.
+
+| Pattern | Tell | Fix |
+| --- | --- | --- |
+| Restating the question as a paragraph before answering | "You might be wondering whether…" | Cut it; answer directly |
+| Listing what the article *will* cover | "In this guide we'll look at A, B, and C" | Delete; let the headings do it |
+| Hedged non-claims | "can potentially help in some cases" | State the claim with a condition and a number |
+| Empty transitions | "Now that we've covered X, let's move on to Y" | Delete; the next H2 is the transition |
+| Definition padding for a known term | "SEO, which stands for search engine optimization, is…" | Define only if the audience needs it |
+| Symmetry filler | "On the one hand… on the other hand…" with no real tension | Pick the answer; note the real trade-off |
+| Summary that repeats the body verbatim | A conclusion restating each H2 | Replace with a next step or a decision rule |
+
+## The delete-no-fact pass
+
+Read each sentence and ask: **does this add a fact, a number, a step, or a named example?** If no, delete it. A 1,500-word draft that survives this pass beats a 2,500-word draft that does not.
+
+Concrete test — every paragraph should contain at least one of: a number, a proper noun, a measured result, a named tool, a date, a specific step, or a cited source. A paragraph of pure adjectives is filler.
+
+## Bad → Good rewrites
+
+```markdown
+<!-- Bad -->
+When it comes to choosing a standing desk, it's important to note that there
+are many factors to consider. In today's world, ergonomics plays a crucial
+role in our daily lives, so let's dive in and explore your options.
+```
+
+```markdown
+<!-- Good -->
+Choose a standing desk on three specs: height range (match your standing elbow
+height, usually 95–120 cm), motor (dual beats single for stability), and lift
+capacity (100 kg+ if you mount a monitor arm and a heavy display).
+```
+
+```markdown
+<!-- Bad -->
+Oat milk has become increasingly popular as a game-changer in the world of
+dairy alternatives. Without further ado, let's unlock the secrets of why so
+many people are making the switch.
+```
+
+```markdown
+<!-- Good -->
+Oat milk overtook almond as the top US plant milk by 2022 sales. It is creamier
+because oats release beta-glucan; the trade-off is more carbs (~16 g/cup) than
+soy or almond, which matters if you watch blood sugar.
+```
+
+## E-E-A-T self-review (human/agent pass, not scripted)
+
+Before ship, answer each. A "no" is a gap to fix, not a nuance to wave past.
+
+- [ ] **Experience** — does the piece include something only someone who did/tested/used the thing would know?
+- [ ] **Expertise** — are claims accurate, current, and at the right technical level for the audience?
+- [ ] **Authoritativeness** — is there a named author with a bio and relevant standing (not "admin")?
+- [ ] **Trust** — are non-obvious claims cited to credible sources, linked inline? Is anything misleading?
+- [ ] **Original value** — is there a number, comparison, or angle not already on page one of the SERP?
+- [ ] **Intent match** — does the piece fully answer the query, in the SERP's winning format?
+- [ ] **Human review** — has a person read it end to end and would they put their name on it?
+
+If the draft passes the banlist grep but fails this list, it is structurally clean and substantively thin. Thin content is what the March 2026 scaled-content-abuse target penalizes. Fix the substance before shipping.

package/skills/article-writing/references/on-page-seo.md

@@ -0,0 +1,133 @@
+# On-page SEO — title/meta tables, slug rules, JSON-LD templates
+
+The full pixel/char detail and copy-ready schema the SKILL.md body points to. Every number is sourced and dated in the spec (accessed 2026-06-02).
+
+## Title tag — char and pixel bands
+
+| Metric | Desktop | Mobile |
+| --- | --- | --- |
+| Display ceiling | ~580–600 px | ~480 px |
+| Practical char band | 50–60 chars | shorter; front-load |
+| Rewritten least often | 51–55 chars | — |
+| Keyword position | first ~30–35 chars | first ~30–35 chars |
+
+Notes:
+
+- Google rewrites titles ~33–40% of the time overall; the 51–55 char band is rewritten *least*. Stay in it.
+- Pixel width varies by character (an `m` is wide, an `i` is narrow), so the char band is a proxy — if the title is title-case with many wide caps, lean toward 50–55.
+- Front-load the primary keyword. A title that buries the keyword past char 35 risks truncation cutting it off on mobile.
+- One title per page. The `<title>` tag and the on-page H1 may differ; the H1 can be longer and more human.
+
+## Meta description — char and pixel bands
+
+| Metric | Desktop | Mobile |
+| --- | --- | --- |
+| Display ceiling | ~920 px ≈ 158 chars | ~680 px ≈ 120 chars |
+| Practical char band | 140–160 chars | front-load value in first ~120 |
+| Sentences | 1–3 | 1–2 |
+
+Notes:
+
+- The meta description does **not** rank directly, but it drives click-through and is frequently the snippet AI engines echo verbatim. Treat it as ad copy for the result.
+- Lead with the value/answer, not a windup. Include the primary keyword once, naturally (Google bolds matched terms).
+- If you write past 160 chars, write so the first ~120 stand alone — that is what mobile shows.
+
+## Slug rules
+
+- Lowercase, words hyphen-separated, ASCII.
+- 3–5 meaningful words; drop stop words (`the`, `a`, `to`, `your`, `how`) unless they carry meaning.
+- Keyword-bearing and stable — do not change a published slug without a 301 redirect.
+- Bad: `/how-to-start-composting-in-your-apartment-today` → Good: `/compost-in-apartment`.
+- No dates or volatile params in evergreen slugs (`/standing-desk-guide`, not `/2026/03/standing-desk-guide-v2`).
+
+## Worked answer-first ledes
+
+Pattern: **state the answer in sentence 1–2, qualify in 3–4, signpost what follows.**
+
+Query: *how to choose a standing desk*
+
+> The best standing desk for most people is an electric sit-stand desk with a 70–120 cm height range, a dual motor, and at least 100 kg lift capacity. Pick by adjustment range (match your height), stability at full extension, and warranty (aim 5+ years on the frame). Below: how to size it, what specs actually matter, and the mistakes that waste money.
+
+Query: *is oat milk good for you*
+
+> Oat milk is a reasonable dairy alternative: ~120 kcal and 3 g protein per cup, naturally low in saturated fat, and usually fortified with calcium and B12. It is not ideal if you need high protein or are watching blood sugar (it is higher in carbs than soy or almond milk). Here is how it compares cup-for-cup and who should pick something else.
+
+Both answer the query before the reader scrolls — the requirement for featured snippets and AI Overview extraction.
+
+## JSON-LD templates (JSON-LD only — never microdata)
+
+Embed in a `<script type="application/ld+json">` block in the page `<head>` or body. Use **one** article type per page. The schema must describe what is actually visible on the page.
+
+### Article / BlogPosting
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "BlogPosting",
+  "headline": "How to Choose a Standing Desk: Specs That Matter",
+  "description": "A spec-by-spec guide to choosing a sit-stand desk: height range, motor, lift capacity, stability, and warranty.",
+  "image": ["https://example.com/img/standing-desk-guide.jpg"],
+  "datePublished": "2026-06-02T08:00:00+01:00",
+  "dateModified": "2026-06-02T08:00:00+01:00",
+  "author": {
+    "@type": "Person",
+    "name": "Jordi Vila",
+    "url": "https://example.com/author/jordi-vila",
+    "jobTitle": "Ergonomics editor"
+  },
+  "publisher": {
+    "@type": "Organization",
+    "name": "Example Media",
+    "logo": {
+      "@type": "ImageObject",
+      "url": "https://example.com/logo.png"
+    }
+  },
+  "mainEntityOfPage": {
+    "@type": "WebPage",
+    "@id": "https://example.com/standing-desk-guide"
+  }
+}
+```
+
+Use `Article` for general/news, `BlogPosting` for blog content. Keep `headline` ≤110 chars. `author` should be a real named `Person` with a `url` to a bio (an E-E-A-T signal). Set `dateModified` honestly on every meaningful edit.
+
+### FAQPage (only when a real FAQ section exists on the page)
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "FAQPage",
+  "mainEntity": [
+    {
+      "@type": "Question",
+      "name": "How much does a good standing desk cost?",
+      "acceptedAnswer": {
+        "@type": "Answer",
+        "text": "A reliable electric sit-stand desk runs roughly €300–€600. Below that, motors and stability suffer; above it you pay for materials and brand."
+      }
+    },
+    {
+      "@type": "Question",
+      "name": "Is a standing desk worth it?",
+      "acceptedAnswer": {
+        "@type": "Answer",
+        "text": "Yes if you currently sit all day — alternating sitting and standing reduces reported lower-back discomfort. The benefit comes from movement, not standing all day."
+      }
+    }
+  ]
+}
+```
+
+### FAQPage eligibility caveat
+
+Google narrowed FAQ rich-result *display* to authoritative government and health sites in 2023; most sites no longer get the visible FAQ rich result in the SERP. **Still ship the `FAQPage` JSON-LD** — it remains valid structured data that AI engines and assistants parse for extraction, and the Q&A structure is exactly what AI Overviews cite. Every `Question`/`Answer` in the schema must match a visible Q&A on the page; schema-only answers not shown to users are a spam signal.
+
+## On-page surface — assembly order
+
+1. Draft the body and FAQ first.
+2. Write the title from the H1 (tighter, keyword-front-loaded, 50–60 chars).
+3. Write the meta description from the answer-first lede (140–160 chars, value-first).
+4. Generate the slug from the primary keyword.
+5. Build the `Article`/`BlogPosting` JSON-LD; add `FAQPage` only if a visible FAQ exists.
+6. Run `scripts/verify.sh` over the assembled markdown.

package/skills/article-writing/scripts/verify.sh

@@ -0,0 +1,165 @@
+#!/usr/bin/env bash
+#
+# verify.sh — structural + banlist lint for an `article-writing` draft.
+#
+# Usage: scripts/verify.sh path/to/article.md
+#
+# Read-only. Checks the on-page surface and banned phrasing of a single
+# article markdown file. It is a lint of STRUCTURE and PHRASING, not a
+# judge of whether the content is good — that is the capability eval's job.
+#
+# Exit 0 = all hard checks pass (or nothing to check). Exit 1 = a hard
+# check failed. Warnings never fail the run.
+#
+# The file is expected to carry, in YAML front-matter or a clearly
+# labelled block, a `title:` and `meta_description:` line, plus a JSON-LD
+# block (```json or <script type="application/ld+json">).
+
+set -u
+
+TARGET="${1:-}"
+
+# --- No target / empty target: pass cleanly, never a false failure. -------
+if [ -z "$TARGET" ]; then
+  echo "verify.sh: no article path given — nothing to check. PASS"
+  exit 0
+fi
+if [ ! -f "$TARGET" ]; then
+  echo "verify.sh: '$TARGET' is not a file — nothing to check. PASS"
+  exit 0
+fi
+if [ ! -s "$TARGET" ]; then
+  echo "verify.sh: '$TARGET' is empty — nothing to check. PASS"
+  exit 0
+fi
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+BANLIST_FILE="$SCRIPT_DIR/../references/ai-tell-banlist.md"
+
+fail=0
+warn=0
+pass() { printf 'PASS  %s\n' "$1"; }
+bad()  { printf 'FAIL  %s\n' "$1"; fail=1; }
+note() { printf 'WARN  %s\n' "$1"; warn=1; }
+
+# --- 1. Title length ------------------------------------------------------
+# Grab the first `title:` value (front-matter or labelled block).
+title_line="$(grep -i -m1 -E '^[[:space:]]*title[[:space:]]*:' "$TARGET" || true)"
+if [ -z "$title_line" ]; then
+  note "no 'title:' line found — cannot check title length"
+else
+  title_val="$(printf '%s' "$title_line" | sed -E 's/^[[:space:]]*[Tt][Ii][Tt][Ll][Ee][[:space:]]*:[[:space:]]*//; s/^["'\'']//; s/["'\''][[:space:]]*$//')"
+  tlen=${#title_val}
+  if [ "$tlen" -ge 50 ] && [ "$tlen" -le 60 ]; then
+    pass "title is $tlen chars (50-60 band)"
+  elif [ "$tlen" -ge 45 ] && [ "$tlen" -le 65 ]; then
+    note "title is $tlen chars (outside 50-60, inside 45-65 tolerance)"
+  else
+    bad "title is $tlen chars (target 50-60): \"$title_val\""
+  fi
+fi
+
+# --- 2. Meta description length ------------------------------------------
+meta_line="$(grep -i -m1 -E '^[[:space:]]*(meta_description|meta|description)[[:space:]]*:' "$TARGET" || true)"
+if [ -z "$meta_line" ]; then
+  note "no 'meta_description:' line found — cannot check meta length"
+else
+  meta_val="$(printf '%s' "$meta_line" | sed -E 's/^[[:space:]]*[A-Za-z_]+[[:space:]]*:[[:space:]]*//; s/^["'\'']//; s/["'\''][[:space:]]*$//')"
+  mlen=${#meta_val}
+  if [ "$mlen" -ge 140 ] && [ "$mlen" -le 160 ]; then
+    pass "meta description is $mlen chars (140-160 band)"
+  elif [ "$mlen" -ge 120 ] && [ "$mlen" -le 170 ]; then
+    note "meta description is $mlen chars (outside 140-160, inside 120-170 tolerance)"
+  else
+    bad "meta description is $mlen chars (target 140-160)"
+  fi
+fi
+
+# --- 3. Exactly one H1, at least two H2s ----------------------------------
+h1_count="$(grep -c -E '^# [^#]' "$TARGET" || true)"
+h2_count="$(grep -c -E '^## [^#]' "$TARGET" || true)"
+if [ "$h1_count" -eq 1 ]; then
+  pass "exactly one H1"
+else
+  bad "found $h1_count H1 headings (need exactly 1)"
+fi
+if [ "$h2_count" -ge 2 ]; then
+  pass "$h2_count H2 headings (>=2)"
+else
+  bad "found $h2_count H2 headings (need >=2)"
+fi
+
+# --- 4. JSON-LD present with Article/BlogPosting; FAQPage if FAQ exists ----
+has_jsonld=0
+grep -q -E 'application/ld\+json' "$TARGET" && has_jsonld=1
+grep -q -E '"@type"[[:space:]]*:[[:space:]]*"(Article|BlogPosting)"' "$TARGET" && has_jsonld=1
+if grep -q -E '"@type"[[:space:]]*:[[:space:]]*"(Article|BlogPosting)"' "$TARGET"; then
+  pass "JSON-LD has @type Article/BlogPosting"
+elif [ "$has_jsonld" -eq 1 ]; then
+  bad "JSON-LD block present but no @type Article/BlogPosting"
+else
+  bad "no JSON-LD block with @type Article/BlogPosting found"
+fi
+
+# FAQ section present? (English / Catalan / Spanish heading)
+if grep -q -i -E '^#{1,3}[[:space:]].*(faq|preguntes|preguntas|frequently asked)' "$TARGET"; then
+  if grep -q -E '"@type"[[:space:]]*:[[:space:]]*"FAQPage"' "$TARGET"; then
+    pass "FAQ section has matching FAQPage JSON-LD"
+  else
+    bad "FAQ section present but no FAQPage JSON-LD"
+  fi
+fi
+
+# --- 5. At least one internal-link slot (relative / site path) ------------
+# Markdown link whose target is not an absolute external http(s) URL.
+if grep -q -E '\]\((/|\.{1,2}/|#)[^)]*\)' "$TARGET"; then
+  pass "internal-link slot present"
+else
+  note "no internal-link slot found (target 3-5 contextual internal links)"
+fi
+
+# --- 6. AI-tell / fluff banlist scan -------------------------------------
+if [ ! -f "$BANLIST_FILE" ]; then
+  note "banlist file not found at $BANLIST_FILE — skipping phrase scan"
+else
+  # Extract the fenced ```text BANLIST block: lines between the first
+  # ```text after the '## BANLIST' header and the next ``` fence.
+  banlist="$(awk '
+    /^## BANLIST/      { insec=1; next }
+    insec && /^```text/ { infence=1; next }
+    infence && /^```/   { infence=0; insec=0; next }
+    infence            { print }
+  ' "$BANLIST_FILE")"
+
+  hits=0
+  while IFS= read -r phrase; do
+    [ -z "$phrase" ] && continue
+    # strip a trailing comma-only token nuance; match literal, case-insensitive
+    if matches="$(grep -i -n -F -- "$phrase" "$TARGET")"; then
+      while IFS= read -r m; do
+        [ -z "$m" ] && continue
+        printf 'BANNED  "%s"  -> %s\n' "$phrase" "$m"
+        hits=$((hits + 1))
+      done <<< "$matches"
+    fi
+  done <<< "$banlist"
+
+  if [ "$hits" -eq 0 ]; then
+    pass "banlist scan clean (0 matches)"
+  else
+    bad "banlist scan found $hits AI-tell/fluff match(es) — rewrite the lines above"
+  fi
+fi
+
+# --- Summary --------------------------------------------------------------
+echo "---"
+if [ "$fail" -ne 0 ]; then
+  echo "verify.sh: FAIL (one or more hard checks failed)"
+  exit 1
+fi
+if [ "$warn" -ne 0 ]; then
+  echo "verify.sh: PASS with warnings"
+else
+  echo "verify.sh: PASS"
+fi
+exit 0