rsc-universal 0.1.1

package/skills/api-design/references/openapi-contract.md

@@ -0,0 +1,86 @@
+# OpenAPI 3.1 contract
+
+The contract is the artifact. Capture a REST design as an **OpenAPI 3.1** document — a real, lintable file that a framework skill generates server stubs and clients from, and that `scripts/verify.sh` checks.
+
+Why 3.1: it aligns with JSON Schema 2020-12, so your request/response schemas are reusable JSON Schema, and it adds `webhooks` and richer `$ref` handling over 3.0.
+
+## Minimal skeleton
+
+```yaml
+openapi: 3.1.0
+info:
+  title: Projects API
+  version: 1.0.0
+servers:
+  - url: https://api.acme.com/v1
+paths:
+  /projects:
+    get:
+      summary: List projects
+      parameters:
+        - { name: cursor, in: query, schema: { type: string } }
+        - { name: limit, in: query, schema: { type: integer, maximum: 100, default: 50 } }
+      responses:
+        "200":
+          description: A page of projects
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/ProjectPage" }
+        default:
+          $ref: "#/components/responses/Problem"
+    post:
+      summary: Create a project
+      parameters:
+        - { name: Idempotency-Key, in: header, schema: { type: string } }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/ProjectCreate" }
+      responses:
+        "201":
+          description: Created
+          headers:
+            Location: { schema: { type: string } }
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/Project" }
+        "422": { $ref: "#/components/responses/Problem" }
+        default: { $ref: "#/components/responses/Problem" }
+components:
+  responses:
+    Problem:
+      description: RFC 9457 problem details
+      content:
+        application/problem+json:
+          schema: { $ref: "#/components/schemas/Problem" }
+  schemas:
+    Problem:
+      type: object
+      properties:
+        type: { type: string, format: uri }
+        title: { type: string }
+        status: { type: integer }
+        detail: { type: string }
+        instance: { type: string }
+      required: [type, title, status]
+    ProjectPage:
+      type: object
+      properties:
+        data: { type: array, items: { $ref: "#/components/schemas/Project" } }
+        next_cursor: { type: [string, "null"] }
+        has_more: { type: boolean }
+      required: [data, has_more]
+```
+
+## Conventions that keep it clean
+
+- **One reusable `Problem` schema and `Problem` response**, referenced by every error case — enforces the single RFC 9457 envelope.
+- **A `default` response on every operation** so unexpected statuses still resolve to the problem shape.
+- **Every list operation carries `cursor` + `limit`** params — verify.sh warns when a list path lacks them.
+- **No verbs in path keys** — verify.sh flags `/get*`, `/create*`, `/delete*` segments.
+- **`info.version` is the contract version**, distinct from the URL `/v1` major; bump it on any non-breaking addition too.
+
+## Handoff
+
+Give the framework skill this file. It becomes the source of truth: FastAPI/NestJS/Go/Node tooling can generate models, route stubs, and validation from it, and clients can generate SDKs. Keep the OpenAPI doc updated *before* the code changes — design-first, not code-first.

package/skills/api-design/references/rest-conventions.md

@@ -0,0 +1,63 @@
+# REST conventions
+
+Depth behind the SKILL. Framework-neutral. Adopt as house style and keep it consistent across every endpoint.
+
+## Status-code map — when each
+
+| Code | Meaning | Use when |
+|---|---|---|
+| 200 OK | success + body | GET, or a PUT/PATCH that returns the updated resource |
+| 201 Created | created | POST created a resource — include `Location: /collection/{id}` |
+| 202 Accepted | accepted, not done | async work queued — return a status/poll URL |
+| 204 No Content | success, no body | DELETE, or PUT/PATCH that returns nothing |
+| 304 Not Modified | cache hit | conditional GET with `If-None-Match` and ETag matched |
+| 400 Bad Request | malformed | body/params unparseable or syntactically wrong |
+| 401 Unauthorized | unauthenticated | missing/invalid credentials — re-auth may help |
+| 403 Forbidden | unauthorized | authenticated but lacks permission/scope |
+| 404 Not Found | absent | resource doesn't exist (or is hidden from this caller) |
+| 405 Method Not Allowed | wrong verb | path exists, method doesn't — set `Allow` header |
+| 409 Conflict | state collision | duplicate, version mismatch, concurrent edit |
+| 412 Precondition Failed | stale write | `If-Match` ETag no longer matches |
+| 415 Unsupported Media Type | bad content-type | server can't process the sent representation |
+| 422 Unprocessable Content | semantic invalid | parses fine, fails business validation |
+| 429 Too Many Requests | rate limited | include `Retry-After` |
+| 500 Internal Server Error | server fault | unexpected — never leak the stack |
+| 503 Service Unavailable | temporarily down | maintenance/overload — `Retry-After` if known |
+
+Rule of thumb: client mistakes are 4xx, server faults are 5xx. Never blame the client for your bug, never hide your bug behind a 200.
+
+## Query grammar (filter / sort / sparse fieldsets)
+
+Keep one grammar across all list endpoints so clients learn it once.
+
+```http
+GET /projects?status=active&owner=u_42&sort=-created_at,title&fields=id,title,status&limit=50
+```
+
+- **Filter** by field name as a query key: `?status=active`. For operators, namespace them: `?created_at[gte]=2026-01-01`. Pick one operator syntax and never mix.
+- **Sort** with a comma list; `-` prefix = descending: `?sort=-created_at,title`.
+- **Sparse fieldsets** let clients trim payloads: `?fields=id,title`. Whitelist allowed fields server-side.
+- **Reserve** `limit`, `cursor` (or `offset`), `sort`, `fields`, `q` (free-text search) so they never collide with resource fields.
+
+## Content negotiation
+
+- Default to `application/json`. Honor `Accept`; return `406 Not Acceptable` if you can't satisfy it.
+- Validate `Content-Type` on writes; `415` if unsupported.
+- Version via media type only if you chose header versioning (see versioning reference); otherwise keep it simple.
+
+## Rate-limit headers
+
+Expose limits so well-behaved clients self-throttle:
+
+```http
+RateLimit-Limit: 1000
+RateLimit-Remaining: 12
+RateLimit-Reset: 1735689600
+Retry-After: 30
+```
+
+On 429 always send `Retry-After`. Prefer the IETF `RateLimit-*` fields; the older `X-RateLimit-*` names are still common in the wild.
+
+## HATEOAS — pragmatic stance
+
+Full hypermedia (links driving all client navigation) is rarely worth it for typical JSON APIs; clients hardcode URLs anyway. Useful subset: include a `Location` on 201, a `Link` header for pagination/successor-version, and self/next links in list envelopes when it costs little. Don't build a hypermedia framework no client will follow.

package/skills/api-design/references/versioning-and-evolution.md

@@ -0,0 +1,49 @@
+# Versioning & evolution
+
+Default posture: **evolve additively, version rarely.** A version is a fork of your client base — earn it.
+
+## Breaking vs non-breaking matrix
+
+| Change | Breaking? | Notes |
+|---|---|---|
+| Add a new optional response field | No | clients ignore unknown fields if you told them to |
+| Add a new endpoint | No | nothing existing changes |
+| Add a new optional query/body param | No | old requests still valid |
+| Add a new enum value | No* | *only if clients were told to tolerate unknown values; otherwise breaking |
+| Loosen a validation rule | No | previously-rejected input now accepted |
+| Remove or rename a field | **Yes** | clients reading it break |
+| Change a field's type or format | **Yes** | `string` → `object`, date format change, etc. |
+| Make an optional field required | **Yes** | old requests start failing |
+| Tighten validation (narrower accepted range) | **Yes** | previously-valid input now rejected |
+| Change a status code for a case | **Yes** | client branching breaks |
+| Change an error `type` URI for a case | **Yes** | clients branch on `type` |
+| Change pagination/cursor semantics | **Yes** | in-flight pagination breaks |
+
+Design hint: tell clients up front to **ignore unknown fields and tolerate unknown enum values** ("must-ignore" / robustness rule). That single contract clause turns many would-be breaking changes into additive ones.
+
+## Three versioning mechanisms
+
+| Mechanism | Example | Pros | Cons |
+|---|---|---|---|
+| **URL path** | `/v1/projects` | visible, cacheable, browser-testable, expected by most clients | version leaks into every URL; "v" is coarse-grained |
+| **Header / media type** | `Accept: application/vnd.acme.v2+json` | clean URLs, content-negotiated | harder to test/cache, easy to forget, opaque to humans |
+| **Query param** | `/projects?version=2` | trivial to add | pollutes URLs, easy to omit, muddies caching |
+
+**Default to URL path for public APIs.** Reserve header/media-type versioning for internal APIs where tooling controls the header. Don't mix mechanisms.
+
+## Deprecation & sunset workflow
+
+1. Ship the successor (new field/endpoint/version) additively.
+2. Mark the old surface deprecated in responses:
+
+```http
+Deprecation: true
+Sunset: Sat, 31 Oct 2026 23:59:59 GMT
+Link: <https://api.acme.com/v2/projects>; rel="successor-version"
+```
+
+3. Document the migration and the sunset date; notify known integrators.
+4. Hold the deprecated surface working until the `Sunset` date — give clients real time (months, not days, for public APIs).
+5. After sunset, return `410 Gone` for the removed surface (not `404`) so clients learn it was intentional.
+
+Keep the deprecation window generous and the messaging programmatic — clients should learn from headers, not from breakage.

package/skills/api-design/scripts/verify.sh

@@ -0,0 +1,138 @@
+#!/usr/bin/env bash
+# verify.sh — read-only check of an API-design artifact (OpenAPI 3.1 spec).
+#
+# The api-design skill emits its contract as an OpenAPI document. This script
+# finds candidate spec files under a target dir, validates they parse and carry
+# the required OpenAPI keys, and emits non-fatal warnings for the design
+# anti-patterns it can detect statically. It never writes anything.
+#
+# Usage:   verify.sh [TARGET_DIR]   (default: current directory)
+# Exit:    0  no spec found (soft-pass) OR all found specs valid
+#          1  a spec file is present but invalid/unparseable
+#
+# Soft-pass on a clean/empty target: a design may live only in a doc.
+
+set -uo pipefail
+
+TARGET="${1:-.}"
+fail=0
+
+note()  { printf '  - %s\n' "$1"; }
+warn()  { printf '  ! %s\n' "$1"; }
+
+if [ ! -d "$TARGET" ]; then
+  echo "verify(api-design): target '$TARGET' is not a directory — nothing to check."
+  exit 0
+fi
+
+# Collect candidate OpenAPI files (read-only). Tolerate no matches.
+# Portable to bash 3.2 (macOS default): no mapfile; newline-delimited list.
+specs=()
+while IFS= read -r f; do
+  [ -n "$f" ] && specs+=("$f")
+done < <(
+  find "$TARGET" \
+    \( -name 'openapi.yaml' -o -name 'openapi.yml' -o -name 'openapi.json' \
+       -o -name '*.openapi.yaml' -o -name '*.openapi.yml' -o -name '*.openapi.json' \) \
+    -type f 2>/dev/null
+)
+
+if [ "${#specs[@]}" -eq 0 ]; then
+  echo "verify(api-design): no OpenAPI spec found under '$TARGET' — soft-pass (design may be in-doc only)."
+  exit 0
+fi
+
+# Choose a linter if available; else fall back to a structural check.
+LINTER=""
+if command -v redocly >/dev/null 2>&1; then
+  LINTER="redocly"
+elif command -v spectral >/dev/null 2>&1; then
+  LINTER="spectral"
+fi
+
+# Structural fallback: parse + required keys, using whatever is on PATH.
+parse_check() {
+  local f="$1"
+  case "$f" in
+    *.json)
+      if command -v jq >/dev/null 2>&1; then
+        jq -e 'has("openapi") and has("info") and has("paths")' "$f" >/dev/null 2>&1
+        return $?
+      fi
+      ;;
+    *.yaml|*.yml)
+      if command -v python3 >/dev/null 2>&1; then
+        python3 - "$f" <<'PY' >/dev/null 2>&1
+import sys
+try:
+    import yaml
+except Exception:
+    sys.exit(2)  # no yaml lib -> can't check, treat as inconclusive
+with open(sys.argv[1]) as fh:
+    d = yaml.safe_load(fh)
+sys.exit(0 if isinstance(d, dict) and all(k in d for k in ("openapi", "info", "paths")) else 1)
+PY
+        local rc=$?
+        [ "$rc" -eq 2 ] && return 3   # inconclusive
+        return $rc
+      fi
+      ;;
+  esac
+  return 3  # inconclusive: no suitable parser on PATH
+}
+
+# Static anti-pattern warnings (grep-based, never fatal).
+antipattern_scan() {
+  local f="$1"
+  if grep -Eiq '"?/[A-Za-z0-9_]*(get|create|update|delete|fetch|list)[A-Za-z0-9_]*"?[[:space:]]*:' "$f"; then
+    warn "verb-like path segment(s) detected — paths should be nouns; HTTP methods are the verbs."
+  fi
+  if grep -Eq '(/[A-Za-z0-9_/{}]*)+[[:space:]]*:' "$f" && ! grep -Eiq 'cursor|limit|offset|first|after|page' "$f"; then
+    warn "no pagination params (cursor/limit/offset) found — list endpoints should paginate."
+  fi
+  if ! grep -Eiq 'problem\+json|"4[0-9][0-9]"|default[[:space:]]*:' "$f"; then
+    warn "no 4xx / default error responses found — every operation should define an error response (RFC 9457)."
+  fi
+}
+
+echo "verify(api-design): checking ${#specs[@]} spec file(s) under '$TARGET'"
+[ -n "$LINTER" ] && echo "  using linter: $LINTER"
+
+for f in "${specs[@]}"; do
+  echo "* $f"
+  ok=1
+  if [ -n "$LINTER" ]; then
+    if [ "$LINTER" = "redocly" ]; then
+      redocly lint "$f" >/dev/null 2>&1 || ok=0
+    else
+      spectral lint "$f" >/dev/null 2>&1 || ok=0
+    fi
+    if [ "$ok" -eq 0 ]; then
+      # Linter unhappy: confirm with structural parse before failing hard.
+      parse_check "$f"; pc=$?
+      if [ "$pc" -eq 0 ]; then
+        warn "$LINTER reported issues but the spec parses and has required keys — review lint output."
+      else
+        note "spec is invalid per $LINTER."
+        fail=1
+        continue
+      fi
+    fi
+  else
+    parse_check "$f"; pc=$?
+    case "$pc" in
+      0) : ;;  # valid
+      3) warn "no parser on PATH (jq/python3+pyyaml) — skipped structural validation." ;;
+      *) note "spec does not parse or is missing required keys (openapi/info/paths)."; fail=1; continue ;;
+    esac
+  fi
+  antipattern_scan "$f"
+done
+
+if [ "$fail" -ne 0 ]; then
+  echo "verify(api-design): FAIL — one or more specs are invalid."
+  exit 1
+fi
+
+echo "verify(api-design): OK (warnings, if any, are advisory)."
+exit 0

package/skills/article-writing/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: article-writing
+description: "Use when drafting a long-form blog post or article from a topic or target query and you need publishable prose plus the on-page surface that ships with it — an answer-first lede, a question-shaped H2/H3 hierarchy, title tag, meta description, slug, FAQ block, and Article/FAQPage JSON-LD. Use when an intro buries the answer, a draft rambles or reads padded with AI tells, or a piece needs depth matched to search intent for AI Overviews and featured snippets. Triggers: 'write a blog post about X', 'draft a 1500-word article', 'rewrite this intro so the answer comes first', 'add FAQ schema to this post', 'cut the fluff out of this draft', 'escriu un article de blog sobre teletreball optimitzat per SEO', 'redacta un artículo optimizado para SEO'. NOT keyword research or which topics to target (that is seo-geo), and NOT the editorial calendar or content pipeline (that is content-engine)."
+tags: [article, blog, long-form, seo-writing, geo, on-page, eeat, copywriting]
+recommends: [seo-geo, content-engine, brand-voice, landing-copy, technical-writing, case-studies]
+origin: risco
+---
+
+# Article writing
+
+Draft one long-form article end to end: the prose **and** the on-page surface that ships with it — answer-first lede, question-shaped headings, title tag, meta description, slug, FAQ block, and the JSON-LD that makes the piece machine-readable.
+
+You own a single finished article. You do not pick the topic, build the calendar, or define the house voice — those are siblings below.
+
+## When to use
+
+- Drafting a blog post or long-form article from a topic or a target query.
+- Turning a brief or outline into finished, publishable prose at the right depth.
+- Writing the answer-first lede — the first ~200 words that fully answer the primary query.
+- Restructuring a rambling draft into a question-shaped H2/H3 hierarchy.
+- Writing the on-page surface: title tag, meta description, H1, slug, FAQ section, and Article/FAQPage JSON-LD.
+- Cutting an AI-tell, fluff-padded draft down to the depth the query actually needs.
+
+## When NOT to use
+
+| You want… | Go to |
+| --- | --- |
+| Keyword research, SERP tracking, technical SEO, deciding which topics to target | [`../seo-geo/SKILL.md`](../seo-geo/SKILL.md) |
+| Editorial calendar, topic-cluster plan, pipeline across many pieces | [`../content-engine/SKILL.md`](../content-engine/SKILL.md) |
+| The reusable brand tone-of-voice spec the article is written in | [`../brand-voice/SKILL.md`](../brand-voice/SKILL.md) |
+| A conversion landing or sales page (hero, offer, CTA) | [`../landing-copy/SKILL.md`](../landing-copy/SKILL.md) |
+| An email newsletter issue (subject line, send) | [`../newsletter/SKILL.md`](../newsletter/SKILL.md) |
+| Product docs, API reference, software how-tos | [`../technical-writing/SKILL.md`](../technical-writing/SKILL.md) |
+| A customer outcome story / narrative | [`../case-studies/SKILL.md`](../case-studies/SKILL.md) |
+
+Rule: if the deliverable is not *one publishable article*, you are in the wrong skill.
+
+## Start from intent, not a word count
+
+Before you write a sentence, read the top of the SERP for the target query. Name two things: the **dominant intent** (informational, transactional, comparison, navigational) and the **winning format** Google already rewards (listicle, step guide, definition + table, comparison). Match that format — fighting the shape Google already chose loses.
+
+Then set depth from intent, not from a number you were handed. The first-page Google average is ~1,447 words across 11.8M results (Backlinko) — a *descriptive average*, never a target. Thoroughness and intent satisfaction rank, not length.
+
+| Intent | Typical depth | Shape |
+| --- | --- | --- |
+| Simple how-to / quick answer | 400–800 words | Direct answer, short steps, one image |
+| Standard informational post | 1,500–2,000 words | Answer-first lede + question H2s |
+| Comprehensive guide | 1,700–2,500 words | Full subtopic coverage, tables, FAQ |
+| Pillar page | 2,500–5,000 words | Hub with two-way cluster links |
+
+Why: padding a 600-word answer to 2,000 to "look thorough" dilutes it and reads as filler. Cutting a guide to 800 words leaves the query half-answered. Length follows the question.
+
+## The answer-first lede
+
+The first ~200 words must directly and completely answer the primary query. Lead with the answer (TL;DR-first / inverted pyramid), then expand. This is the structure that wins featured snippets and AI Overview citations — and with zero-click hitting ~60% of searches (2024) and AI Overviews appearing in ~13% of queries (May 2025), being the extracted answer matters more than the click.
+
+```markdown
+<!-- Bad: warms up for three paragraphs before answering -->
+## Should you compost in an apartment?
+Composting has become increasingly popular in recent years as more people
+look for sustainable lifestyle choices. Many city dwellers assume they can't
+participate because of limited space. But is that really true? Let's explore
+the fascinating world of urban composting and find out together.
+```
+
+```markdown
+<!-- Good: answers in the first two sentences, then expands -->
+## Can you compost in an apartment?
+Yes — a sealed countertop bokashi bin or a small worm bin (vermicomposting)
+lets you compost food scraps in a flat with no yard and no smell. Bokashi
+ferments scraps in ~2 weeks; a worm bin yields finished compost in 3–6 months.
+Here is how to choose between them and set one up in a 60×40 cm footprint.
+```
+
+If the query is a question, the H1 or first H2 should *be* that question and the next sentence should answer it. Worked lede examples are in [`references/on-page-seo.md`](references/on-page-seo.md).
+
+## Outline as a question map
+
+Build the skeleton from real subtopics, not from what you feel like writing.
+
+- **One H1**, matching the primary query or its close paraphrase.
+- **H2/H3 are questions or named subtopics** that mirror the SERP's "People also ask", related searches, and the headings competitors share — plus the gaps they all miss (that gap is your edge).
+- **One idea per heading.** A heading that needs an "and" is two headings.
+- Headings are subtopics, not slogans: `## How much does a standing desk cost?` not `## The Price Question`.
+
+Why question-shaped headings: only ~38% of pages cited in AI Overviews rank top-10, so clean, extractable, question→answer structure can win citations without traditional authority. Make every section answerable on its own.
+
+## Drafting for depth and E-E-A-T
+
+Google does **not** penalize AI-assisted content as such. It penalizes *scaled content abuse* — high-volume, no-editorial-review, thin, no-first-hand-experience pages. The March 2026 core update named scaled content abuse a primary target; offending sites saw 50–80% traffic drops. The defense is not avoiding AI; it is genuine value, depth, and human review.
+
+So every draft earns its keep with E-E-A-T (Experience, Expertise, Authoritativeness, **Trust** — Trust is the load-bearing member):
+
+- **First-hand experience** — a thing you tested, measured, or saw. "We ran the worm bin for 90 days and weighed the output" beats "worm bins are effective".
+- **Original data or insight** — a number, comparison, or angle not already on page one.
+- **Credible cited sources** for claims you did not generate yourself — link them inline.
+- **Clear authorship** — a named author with relevant standing, not "admin".
+- **Match intent over keyword density.** Answer the question fully; the keywords fall out naturally. Never stuff.
+
+Run a human-review pass before ship. If nothing in the draft could only have been written by someone who actually knows the topic, it is thin — add experience or do not publish.
+
+## The on-page surface
+
+Every article ships with these. Keep them in the file's front-matter or a clearly labelled block so [`scripts/verify.sh`](scripts/verify.sh) can lint them.
+
+- **Title tag**: 50–60 characters / under ~580–600 px desktop (~480 px mobile). Put the primary keyword in the first ~30–35 characters. Titles of 51–55 chars are rewritten by Google least often.
+- **Meta description**: 140–160 characters (desktop ~920 px ≈ 158 chars; mobile cuts at ~120). One to three sentences, lead with the value. It does not rank, but it drives CTR and is often the snippet AI engines echo.
+- **H1**: exactly one, matching the query.
+- **Slug**: short, lowercase, hyphenated, keyword-bearing, no stop-word noise — `/compost-in-apartment` not `/how-to-start-composting-in-your-apartment-today`.
+- **FAQ block**: 3–6 real questions from "People also ask", each answered in 2–4 sentences.
+
+Quick checklist:
+
+- [ ] Title 50–60 chars, keyword in first ~35
+- [ ] Meta 140–160 chars, value-first
+- [ ] Exactly one H1
+- [ ] Slug short + keyword-bearing
+- [ ] FAQ questions match visible page content
+
+Full pixel/char tables, slug rules, and copy-ready `Article`/`BlogPosting` + `FAQPage` JSON-LD (JSON-LD only — never microdata) live in [`references/on-page-seo.md`](references/on-page-seo.md). The JSON-LD must describe what is actually on the page; schema that does not match visible content is a quality flag, not a win.
+
+## Internal links and topical authority
+
+Place **3–5 contextual internal links** in the body of a standard article (more only for a long-form pillar). Rules:
+
+- **Descriptive anchor text** — `worm bin setup guide`, never `click here` or a bare URL.
+- Keep priority pages within ~3 clicks of the post.
+- For a pillar, link **two ways**: pillar → each cluster article and each cluster article → pillar. That two-way map is the topical-authority signal AI engines read.
+
+You insert the link *slots* and anchors that fit this article. Deciding the *cluster structure* — which pillar owns which clusters across the site — is [`../content-engine/SKILL.md`](../content-engine/SKILL.md)'s job, not yours.
+
+## Cut the AI tells and the fluff
+
+Do one ruthless pass: **delete every sentence that adds no fact.** If a sentence could sit in any article on any topic, it is filler.
+
+Banned on sight (short sample): "In today's fast-paced world", "It's important to note that", "When it comes to", "Let's dive in", "the world of X", "navigating the landscape of", "unlock the power of", "in conclusion". The full banlist with Bad→Good rewrites and the depth self-review is in [`references/ai-tell-banlist.md`](references/ai-tell-banlist.md) — and that file is the single source `verify.sh` greps against.
+
+```markdown
+<!-- Bad: 28 words, zero facts -->
+In today's fast-paced world, it's important to note that choosing the right
+standing desk can really make a difference when it comes to your health.
+```
+
+```markdown
+<!-- Good: 19 words, three facts -->
+A standing desk adjustable from 70–120 cm fits users 1.5–2.0 m tall and cuts
+the lower-back load reported across sit-all-day workdays.
+```
+
+## Anti-patterns
+
+| Anti-pattern | Why it fails | Do instead |
+| --- | --- | --- |
+| Padding to hit a word count | Dilutes the answer; reads as filler | Set depth from intent; ~1,447w is an average, not a target |
+| Intro that warms up before answering | Loses snippets, AI Overviews, and ~60% zero-click readers | Answer the query in the first ~200 words |
+| Keyword stuffing for density | Reads spammy; Google rewards intent match, not density | Answer fully; keywords fall out naturally |
+| H2s that are slogans, not subtopics | Not extractable; misses People-also-ask citations | Question-shaped, one idea per heading |
+| No named author or cited sources | Thin E-E-A-T; vulnerable in core updates | Add first-hand experience, data, citations, an author |
+| FAQ with no FAQPage schema (or schema ≠ visible content) | Not machine-readable; mismatched schema is a quality flag | Ship matching `FAQPage` JSON-LD describing on-page Q&As |
+| Generic AI-tell prose | Flagged as scaled, low-value content | Run the banlist + delete-no-fact-sentence pass |
+| Ignoring the SERP's winning format | Fights the shape Google already rewards | Match the dominant format, then beat it on depth |
+
+## Ship checklist
+
+Restating the gates `verify.sh` enforces, for the human review:
+
+- [ ] Answer-first lede — primary query fully answered in first ~200 words
+- [ ] Exactly one H1; at least two question-shaped H2s
+- [ ] Title 50–60 chars (keyword early); meta 140–160 chars
+- [ ] JSON-LD present with `@type` `Article`/`BlogPosting`; `FAQPage` too if an FAQ section exists
+- [ ] At least one contextual internal-link slot with a descriptive anchor (target 3–5)
+- [ ] AI-tell / fluff banlist scan is clean
+- [ ] Depth matches intent; first-hand experience or original data present; author + sources named
+
+Run `scripts/verify.sh path/to/article.md`. It is a lint of structure and banned phrasing — it does not judge whether the content is *good*. That is the capability eval's job, and yours.

package/skills/article-writing/evals/README.md

@@ -0,0 +1,3 @@
+# 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.

package/skills/article-writing/evals/cases.yaml

@@ -0,0 +1,47 @@
+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."