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

73%

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.

The body is highly actionable with executable examples and clear write-path validation, and is well-organized by section. It loses points on conciseness from inline dated log notes and on progressive disclosure because all content is monolithically inlined with no bundle structure.

Suggestions

Move the dated PIN-OAuth and auth-verification notes into a dedicated 'Deprecated / historical auth notes' section to remove time-sensitive clutter from the active secrets guidance.

Split the 'Common API calls' catalog and 'Account Info' into reference files (e.g. references/api-calls.md, references/accounts.md) and link them one level deep from SKILL.md to improve progressive disclosure.

Dimension	Reasoning	Score
Conciseness	The body is largely lean and code-driven, but inline time-sensitive log entries ('PIN OAuth note, 2026-06-28', 'Auth verification, 2026-06-28') sit in the secrets section rather than a deprecated/old-patterns section, so it could be tightened.	3 / 5
Actionability	Copy-paste-ready bash/curl/python blocks cover the common cases (mentions, timeline, post, reply, search, user lookup, follow, delete, article draft) with concrete endpoints and parameters.	5 / 5
Workflow Clarity	The reply/context pass is a numbered 5-step sequence and writes carry validation checkpoints (tweet approval gating, `--dry-run`/`--yes` for articles), though some sequences rely on implicit verification.	4 / 5
Progressive Disclosure	No bundle files exist and the ~250-line body is entirely inline; account-info, secrets reference, and the common API-call catalog are well-sectioned but could be split into separate referenced files.	3 / 5
	Total	15 / 20 Passed

Description

75%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.

The description is specific, actionable, and clearly scoped to the X/Twitter API niche with concrete tooling references. Its main weakness is the absence of an explicit 'Use when...' trigger clause, which caps completeness.

Suggestions

Append an explicit trigger clause such as 'Use when reading or posting to X/Twitter, checking mentions, searching tweets, or drafting X Articles.'

Add a few natural synonyms (e.g. 'tweets', 'X posts', 'Twitter') alongside the technical OAuth/bearer-token terminology to broaden trigger coverage.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions — 'Read X/Twitter via API', 'post tweets with OAuth 1.0a', 'draft X Articles', 'Check mentions, search, and ingest posts' — giving comprehensive coverage of capabilities.	5 / 5
Completeness	The 'what' is clear and concrete, but there is no 'Use when...' clause or equivalent explicit trigger guidance, so completeness is capped at 3 per the rubric guideline.	3 / 5
Trigger Term Quality	Natural terms like 'post tweets', 'check mentions', 'search', and 'ingest posts' appear, but the description leans on technical jargon ('OAuth 1.0a', 'bearer tokens') and omits common synonyms or extensions.	4 / 5
Distinctiveness Conflict Risk	A clear X/Twitter API niche anchored on the specific `shitrat x` tool gives distinct triggers with minimal risk of firing for the wrong skill.	5 / 5
	Total	17 / 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: 7094ced

Reviewed: 3 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.