x-api
Read and post to X/Twitter via API. Check mentions, post tweets, search. Use app bearer tokens for read-only fetches and OAuth 1.0a user context for account actions.
62
73%
Does it follow best practices?
Impact
—
No eval scenarios have been run
Advisory
Suggest reviewing before use
Optimize this skill with Tessl
npx tessl skill review --optimize ./skills/x-api/SKILL.mdQuality
Discovery
82%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
This is a strong description with concrete actions and excellent trigger terms specific to X/Twitter. The main weakness is the absence of an explicit 'Use when...' clause, which would help Claude know exactly when to select this skill. The authentication detail (bearer tokens, OAuth 1.0a) adds useful specificity but is more of an implementation detail than a selection trigger.
Suggestions
Add an explicit 'Use when...' clause, e.g., 'Use when the user asks to tweet, check Twitter/X mentions, or interact with the Twitter/X API.'
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple concrete actions: read, post, check mentions, post tweets, search. Also specifies authentication methods (app bearer tokens, OAuth 1.0a), which adds technical specificity. | 3 / 3 |
Completeness | Clearly answers 'what' (read, post, check mentions, search via Twitter API) but lacks an explicit 'Use when...' clause. The when is only implied by the actions listed. | 2 / 3 |
Trigger Term Quality | Includes strong natural trigger terms: 'X/Twitter', 'API', 'mentions', 'tweets', 'search', 'post'. Users would naturally use these terms when requesting Twitter-related tasks. | 3 / 3 |
Distinctiveness Conflict Risk | Very distinct niche — X/Twitter API interaction is unlikely to conflict with other skills. The platform name and specific actions (tweets, mentions) create clear boundaries. | 3 / 3 |
Total | 11 / 12 Passed |
Implementation
64%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a solid, highly actionable skill with executable code for all major X/Twitter API operations and clear authentication patterns. Its main weaknesses are the lack of error handling/validation checkpoints in workflows (especially for posting and deletion) and the monolithic structure that could benefit from splitting detailed API examples into a separate reference file. The rules section provides good safety guardrails.
Suggestions
Add explicit validation/error-handling steps after API calls, especially for destructive operations like tweet deletion (e.g., check response status, confirm tweet ID before deleting).
Consider splitting the Common API calls section into a separate REFERENCE.md file and linking to it, keeping SKILL.md as a concise overview with just the auth setup and one or two example operations.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Generally efficient with good code examples, but includes some unnecessary detail (e.g., explaining what bearer tokens are for, listing out what read-only access covers, the full-archive search notes could be tighter). The inline Python for deriving the bearer token is lengthy but justified since it's executable. Some sections like Account Info and Rate Limits are appropriately terse. | 2 / 3 |
Actionability | Excellent actionability — provides fully executable Python scripts for both auth flows, copy-paste ready API calls for all common operations (mentions, timeline, post, reply, search, follow, delete), specific secret names, concrete curl examples, and even the agent-browser fallback for articles. Every operation has runnable code. | 3 / 3 |
Workflow Clarity | The auth flows are clearly sequenced (lease secrets → derive token → make request → revoke), and the 'revoke leases after use' step is consistently emphasized. However, there are no explicit validation checkpoints — no error handling for failed auth, no check that the bearer token was successfully obtained before proceeding, and no guidance on what to do if a POST fails. For destructive operations like deleting tweets, there's no confirmation step. | 2 / 3 |
Progressive Disclosure | The content is well-organized with clear section headers (Authentication, Common Operations, X Articles, Rate Limits, Rules), but it's a fairly long monolithic file (~150+ lines) with no references to external files. The full bearer-token derivation script and all API examples are inline. Some content (e.g., the full list of common API calls, full-archive search details) could be split into referenced files for better navigation. | 2 / 3 |
Total | 9 / 12 Passed |
Validation
90%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 10 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
frontmatter_unknown_keys | Unknown frontmatter key(s) found; consider removing or moving to metadata | Warning |
Total | 10 / 11 Passed | |
- Repository
- joelhooks/joelclaw
- Commit
03f0a59
- Reviewed
Table of Contents
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.