evgyur/hermes-bird-xurl-skill

Bird

Bird is the single X/Twitter router. Use SocialData as the default, cheap read plane. Use the official xurl CLI only when the task requires authenticated account context, an X-native object, or an explicitly approved account mutation. Do not make both providers answer the same routine read.

Triggers and compatibility

Use for X/Twitter URLs, tweet/thread/article extraction, search, profiles, replies/quotes/context, media retrieval, and X account actions.

Preserve these entrypoints:

• /bird <request> — canonical router.
• Legacy bird.py <URL-or-ID> — still reads through SocialData.
• /xurl ... — compatibility entrypoint for users who explicitly request xurl; it must follow Bird's routing and write gates.

Deterministic routing

Intent	Primary	Fallback	Boundary
Read tweet by URL/ID	SocialData	web/browser only for public visible evidence	Never escalate to xurl merely because it exists
Read thread/conversation/replies	SocialData	xurl read only when X-native context is uniquely required and supported	Determine thread from fetched data, not URL shape
Search posts	SocialData bounded search	existing SocialData/web research route	Current xurl recent-search access is not assumed
Read public profile	SocialData	xurl user lookup if account-specific/current X view is needed	No bulk graph collection
X Article	SocialData tweet payload first; parse nested article	xurl raw tweet endpoint with article field	Follow linked first-party page when article text is absent
Download attached media	SocialData metadata + bounded HTTPS download	browser only for visible public media	No cookies in URLs/logs; validate host/size/type
Who am I / authenticated identity	xurl	none	Read-only account context
Exact X-native object needed for later engagement	xurl	SocialData for discovery/context	Use xurl only for the exact object/endpoint
Post, reply, quote, delete, like, repost, bookmark, follow, block, mute, DM, upload	xurl	none	Explicit approval of exact target, content, and effect required

Load provider routing for endpoint recipes, errors, and fallback rules. Load xurl operations only for an xurl-specific task.

Provider and cost contract

• SocialData is the default for every ordinary read. Use the configured direct SOCIALDATA_API_KEY first in the current runtime. Use the approved Human20 Keys SocialData proxy when a direct key is absent and the H20 customer key has socialdata capability. A generic H20 model key may exist but return provider not allowed: socialdata; that does not justify switching to xurl.
• The live Human20 Keys default price class for social-request was verified at 0 credits/request; treat that as mutable runtime state and recheck before claiming cost.
• One user request should normally consume one lookup/search plus only the bounded dependent reads needed for a thread or requested context. Do not fan out, scrape followers/following, export, stream, poll, or bulk-fetch.
• Never silently fall back from SocialData to paid X API calls. xurl is selected by capability need, not by provider failure.

Secrets and execution safety

• Never read, print, parse, summarize, or expose secret stores, ~/.xurl, cookies, authorization headers, API keys, bearer tokens, request signatures, or environment values.
• Verify credentials only through safe status/probe commands. Do not use xurl --verbose/-v or inline credential flags.
• SocialData calls are read-only and bounded. Treat 401/403 as credential/policy, 402 as credits/billing, 404 as absent/private/deleted, 429 as rate limit, and 5xx as provider failure. Do not mislabel one class as another.
• Browser/relay is last resort and never a cookie-extraction mechanism.
• Writes are protected effects. Before any xurl mutation, reread the exact target and payload, require explicit user approval for that exact effect, execute once, and verify from raw xurl/X response. Approval to research is not approval to engage or publish.
• DMs, deletion, blocks, account changes, media upload, and public posting never happen implicitly.

Workflow

1. Classify the request: read, search, profile, thread, article, media, account-read, or write.
2. Normalize X URL/ID without changing the identifier. Fetch before deciding tweet vs thread.
3. Route from the table. For routine reads, call SocialData exactly once first.
4. Parse defensively. Article payloads may live under article.title, article.preview_text, and article.content_state.blocks[]; media may be nested in quoted or retweeted objects.
5. If the user asks whether the item matters, open linked first-party repositories/docs/articles and inspect attached media. Keep the X post as a claim/source, not automatic proof.
6. If the selected provider fails, report the exact failure. Use only the stated fallback when it can still answer the same request without expanding cost, privacy, or effect.
7. Return source-faithful output and a compact provider receipt.

Output Contract

Return:

Result: <full requested content or concise faithful answer>
Type: tweet | thread | article | profile | search | account-action
Author/source: <safe public identity + canonical URL>
Provider: SocialData | xurl | web/browser fallback
Evidence: <IDs, timestamp, metrics/context when available>
Action receipt: <only for approved xurl mutations; exact status/object ID>
Limitation: <missing/private/deleted/rate/plan/provider gap, or none>

Do not expose internal keys, auth modes, secret locations, or private runtime details in user-facing receipts.

Quick Test Checklist

• /bird <tweet URL> selects SocialData, not xurl.
• /bird search from:handle selects bounded SocialData search.
• /bird whoami selects read-only xurl identity.
• /bird reply <URL> <text> stops for exact approval before xurl.
• SocialData 402 is not reported as missing credentials; xurl recent-search failure does not disable identity/profile reads.
• Thread and article parsing use fetched structure, not URL guesses.
• Removing the SocialData-default or write-approval contract makes validation fail.

Done Criteria

• The requested X content/action is complete or one exact blocker is reported.
• Routine reads used SocialData first and avoided duplicate provider spend.
• xurl was used only for a capability-specific reason.
• Any write had exact approval and raw API readback.
• No secret/cookie/private credential material entered output, artifacts, or logs.