diff --git a/skills/social-media/xurl/SKILL.md b/skills/social-media/xurl/SKILL.md
index 257e86af3..f25ecbbf6 100644
--- a/skills/social-media/xurl/SKILL.md
+++ b/skills/social-media/xurl/SKILL.md
@@ -192,6 +192,15 @@ xurl search "from:elonmusk" -n 20
 xurl search "#buildinpublic lang:en" -n 15
 ```
 
+For X Articles, use raw API mode instead of the `read` shortcut. `xurl read`
+expects a post ID or post URL; do not put `read` before a `/2/tweets/...`
+endpoint. Request the `article` tweet field and ingest `data.article.plain_text`
+from the JSON response:
+
+```bash
+xurl --app APP_NAME '/2/tweets/2057909493250539891?expansions=author_id,attachments.media_keys,referenced_tweets.id&tweet.fields=created_at,lang,public_metrics,context_annotations,entities,possibly_sensitive,conversation_id,in_reply_to_user_id,referenced_tweets,article'
+```
+
 ### Users, Timeline, Mentions
 
 ```bash
diff --git a/tests/skills/test_xurl_article_ingestion_docs.py b/tests/skills/test_xurl_article_ingestion_docs.py
new file mode 100644
index 000000000..6364b9289
--- /dev/null
+++ b/tests/skills/test_xurl_article_ingestion_docs.py
@@ -0,0 +1,29 @@
+from pathlib import Path
+
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+SKILL_MD = REPO_ROOT / "skills" / "social-media" / "xurl" / "SKILL.md"
+DOC_MD = (
+    REPO_ROOT
+    / "website"
+    / "docs"
+    / "user-guide"
+    / "skills"
+    / "bundled"
+    / "social-media"
+    / "social-media-xurl.md"
+)
+
+
+def test_xurl_article_ingestion_uses_raw_api_mode():
+    skill_text = SKILL_MD.read_text(encoding="utf-8")
+    docs_text = DOC_MD.read_text(encoding="utf-8")
+
+    for text in (skill_text, docs_text):
+        assert "For X Articles, use raw API mode" in text
+        assert "`xurl read`" in text
+        assert "do not put `read` before a `/2/tweets/...`" in text
+        assert "tweet.fields=created_at,lang,public_metrics" in text
+        assert "referenced_tweets,article" in text
+        assert "data.article.plain_text" in text
+        assert "read '/2/tweets/" not in text
diff --git a/website/docs/user-guide/skills/bundled/social-media/social-media-xurl.md b/website/docs/user-guide/skills/bundled/social-media/social-media-xurl.md
index 9bbfffc29..f030fa081 100644
--- a/website/docs/user-guide/skills/bundled/social-media/social-media-xurl.md
+++ b/website/docs/user-guide/skills/bundled/social-media/social-media-xurl.md
@@ -206,6 +206,15 @@ xurl search "from:elonmusk" -n 20
 xurl search "#buildinpublic lang:en" -n 15
 ```
 
+For X Articles, use raw API mode instead of the `read` shortcut. `xurl read`
+expects a post ID or post URL; do not put `read` before a `/2/tweets/...`
+endpoint. Request the `article` tweet field and ingest `data.article.plain_text`
+from the JSON response:
+
+```bash
+xurl --app APP_NAME '/2/tweets/2057909493250539891?expansions=author_id,attachments.media_keys,referenced_tweets.id&tweet.fields=created_at,lang,public_metrics,context_annotations,entities,possibly_sensitive,conversation_id,in_reply_to_user_id,referenced_tweets,article'
+```
+
 ### Users, Timeline, Mentions
 
 ```bash