skill: article-writing

# Prompts that MUST load `article-writing`. The skill owns the DRAFT and the
# on-page surface of ONE long-form article — not topic selection, not the
# calendar, not the voice spec, not landing pages.
should_trigger:
  - prompt: "Write a 1,500-word blog post on how to compost in an apartment."
    why: "Core job — drafting one long-form article from a topic at a set depth."
  - prompt: "Rewrite this intro so the answer comes first instead of warming up for three paragraphs."
    why: "Non-obvious — the answer-first lede is this skill's signature; no SEO keyword language but squarely in scope."
  - prompt: "Add an FAQ section and FAQPage schema to my published article."
    why: "On-page surface ownership — FAQ block + Article/FAQPage JSON-LD ship with the piece."
  - prompt: "Escriu un article de blog sobre teletreball i productivitat optimitzat per SEO."
    why: "Catalan phrasing for drafting an SEO-optimized blog article — same core job in another language."
  - prompt: "This draft reads like AI wrote it and it's padded — tighten it to the depth the topic needs."
    why: "Fluff/AI-tell + intent-depth pass; no explicit 'article' word but the deliverable is one tightened draft."
  - prompt: "Restructure this rambling post into clear question-shaped H2s and H3s."
    why: "Non-obvious — heading hierarchy as a question map is owned here, framed as editing not writing."

# Prompts that must NOT load `article-writing` — each routes to a real sibling.
should_not_trigger:
  - prompt: "Find the best keywords and check which topics can actually rank for my site."
    route_to: seo-geo
    why: "Keyword research and topic/strategy selection — deciding WHAT to write, not drafting it."
  - prompt: "Build me a 3-month editorial calendar with topic clusters."
    route_to: content-engine
    why: "Calendar and pipeline across many pieces, not the draft of a single article."
  - prompt: "Define our brand tone of voice and a reusable writing style guide."
    route_to: brand-voice
    why: "The reusable voice spec the article is written IN, not one article."
  - prompt: "Write the homepage hero and CTA section to convert visitors."
    route_to: landing-copy
    why: "A conversion landing page (hero/offer/CTA), not a long-form article."

# At least one capability scenario, graded by rubric against a produced draft.
capability:
  - scenario: "Draft a ~1,500-word article from the target query 'how to choose a standing desk', producing the prose plus its full on-page surface."
    must_include:
      - "Answer-first lede that fully answers the query in the first ~200 words (best desk type + the deciding specs), before any windup."
      - "Question-shaped H2/H3 hierarchy with exactly one H1 matching the query."
      - "Title tag 50-60 chars with the primary keyword in the first ~30-35 chars."
      - "Meta description 140-160 chars, value-first."
      - "A short, keyword-bearing slug."
      - "An FAQ block of real questions plus matching Article/BlogPosting + FAQPage JSON-LD (JSON-LD only) describing the visible content."
      - "3-5 contextual internal-link slots with descriptive anchor text (not 'click here')."
      - "Depth matched to informational intent (~1,500-2,000 words) with no AI-tell padding — passes the banlist."
      - "An E-E-A-T signal: named author and/or cited credible sources, plus first-hand experience or original data."

# Evals — article-writing

`cases.yaml` is read by the repo's standard eval harness. The `should_trigger` and `should_not_trigger` cases test routing and description discrimination: each `should_trigger` prompt must load this skill (including the non-obvious answer-first-lede and the Catalan cases), and each `should_not_trigger` prompt must route to the named sibling (`seo-geo`, `content-engine`, `brand-voice`, `landing-copy`) instead — that confirms the boundary in the description holds. The single `capability` case is graded by rubric, not pass/fail automation: a grader (human or model) asks the skill to draft the standing-desk article and checks the produced markdown against each `must_include` item, then runs `scripts/verify.sh path/to/draft.md` to confirm the structural and banlist gates pass. There is no automated scoring beyond the harness and that verify lint; run it with the repo's usual eval runner.

# 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.

# 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.

#!/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