x-api

Read X/Twitter via API, post tweets with OAuth 1.0a, and draft X Articles through `shitrat x`. Check mentions, search, and ingest posts. Use app bearer tokens for read-only fetches. Use OAuth 1.0a user context for tweets. Use `shitrat x` for Articles.

Quality

76%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Low

Low-risk findings worth noting

Fix and improve this skill with Tessl

tessl review fix ./skills/x-api/SKILL.md

Quality

Content

71%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

A highly actionable, information-dense skill body dominated by executable commands, real secret names, and explicit safety rules for writes. Its weaknesses are the absence of any progressive disclosure (all account history and troubleshooting inlined in one file) and a few executable gaps such as a comment-only lease-revocation section and an inconsistent `secrets lease` export form.

Suggestions

Move dated troubleshooting logs (PIN OAuth note, auth verification, bookmark caveat) and per-account secret lists into a references file (e.g. references/accounts.md) and link them from SKILL.md.

Replace the comment-only "Revoke leases after use" section with the actual revocation command and lease-id capture pattern.

Reconcile the `secrets lease` usage: either document its JSON output in the export form (e.g. pipe through jq) or use one consistent helper.

Dimension	Reasoning	Score
Conciseness	The body is dense and operational — secrets lists, executable scripts, rate limits, and hard rules with almost no padding — but dated troubleshooting entries ("PIN OAuth note, 2026-06-28", "Auth verification, 2026-06-28") and duplicated per-account blocks sit outside any 'old patterns'/'deprecated' section and could be trimmed. This matches the 4 anchor (efficient, minor instances that could be trimmed) rather than 3, since the dated material is a small fraction of otherwise lean content.	4 / 5
Actionability	Nearly everything is copy-paste ready: the bearer-derivation Python script, curl search calls with full query strings, the OAuth1Session pattern, common API calls with real params, and `shitrat x` / `agent-browser` commands. Minor gaps keep it at 4: the "Revoke leases after use" section contains only a comment with no executable command, and `export CK=$(secrets lease x_consumer_key)` contradicts the other script, which parses JSON from `secrets lease` output.	4 / 5
Workflow Clarity	The reply/context pass is a clear numbered 5-step sequence, and write operations have explicit checkpoints (`--dry-run` is free, `--yes` is a write, approval gates for tweets and article creates, 401 → refresh before retry). It falls short of 5 because there are no explicit validate-fix-retry loops for API call failures, and short of nothing below — sequence and most checkpoints are present.	4 / 5
Progressive Disclosure	A ~250-line monolithic SKILL.md with no bundle files at all; account-specific secrets, PIN-OAuth troubleshooting history, and per-account details that clearly belong in separate reference files are inlined. Section headers are decent, matching the 3 anchor (some structure, content that should be separate is inline) rather than 2, since navigation is not impossible and sections are clearly labeled.	3 / 5
	Total	15 / 20 Passed

Description

71%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

A specific, capability-dense description that clearly distinguishes the three access paths (bearer token reads, OAuth 1.0a tweets, `shitrat x` Articles). Its main gap is the complete absence of a 'Use when...' trigger clause, which both caps completeness and weakens trigger-term and distinctiveness coverage.

Suggestions

Append an explicit trigger clause, e.g. "Use when the user mentions X, Twitter, tweets, posting, checking mentions, or searching X posts."

Add natural user phrasings like "timeline", "retweet", or "post to X" to broaden trigger-term coverage.

State when NOT to use it (e.g. other social platforms) to reduce overlap with generic ingestion/research skills.

Dimension	Reasoning	Score
Specificity	"Read X/Twitter via API, post tweets with OAuth 1.0a, and draft X Articles through `shitrat x`. Check mentions, search, and ingest posts" lists multiple concrete actions spanning read, write, and article paths with the exact auth mechanism for each. Coverage is comprehensive rather than having minor gaps, so it fits the 5 anchor rather than 4.	5 / 5
Completeness	The "what" is clear and specific (read via bearer token, post via OAuth 1.0a, draft Articles via `shitrat x`), but there is no "Use when..." clause or equivalent explicit trigger guidance. Per the judging guidelines a missing 'Use when' clause caps completeness at 3, and the 4 anchor requires both what and when.	3 / 5
Trigger Term Quality	Natural keywords like "X/Twitter", "tweets", "mentions", "search", and "Articles" are present, matching how users would phrase requests. A few common variations are missing (e.g. "timeline", "retweet", "post to X"), which fits the 4 anchor (good coverage, a few natural terms missing) rather than 5.	4 / 5
Distinctiveness Conflict Risk	The X/Twitter domain is a clear niche with distinct platform-specific terms, so conflict risk with unrelated skills is low. However, without trigger phrases, generic verbs like "search" and "ingest posts" leave minor overlap risk with ingestion/research skills, matching the 4 anchor rather than 5.	4 / 5
	Total	16 / 20 Passed

Validation

93%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 15 / 16 Passed

Validation for skill structure

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	15 / 16 Passed

Repository: joelhooks/joelclaw
Path: skills/x-api/SKILL.md
Commit: aa0116c

Reviewed: 8 days ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.