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.
78
73%
Does it follow best practices?
Impact
Pending
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 excellent specificity and trigger term coverage, naming concrete actions and both platform names (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 details add useful technical context but don't substitute for explicit trigger guidance.
Suggestions
Add an explicit 'Use when...' clause, e.g., 'Use when the user asks to tweet, check Twitter mentions, search X/Twitter, or interact with the Twitter API.'
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific 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 does this do' (read/post to X/Twitter, check mentions, post tweets, search) and provides technical context about auth methods, but lacks an explicit 'Use when...' clause with trigger guidance, which caps this at 2 per the rubric guidelines. | 2 / 3 |
Trigger Term Quality | Includes strong natural trigger terms users would say: 'X', 'Twitter', 'API', 'mentions', 'tweets', 'search', 'post'. Covers both the old and new platform names (X/Twitter), which is excellent for matching user queries. | 3 / 3 |
Distinctiveness Conflict Risk | Very clearly scoped to X/Twitter API interactions with distinct platform-specific triggers. Unlikely to conflict with other skills since it names a specific social media platform and specific API authentication patterns. | 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 real executable code for all major X/Twitter API operations. Its main weaknesses are the lack of explicit validation checkpoints in workflows (especially for destructive operations like posting/deleting) and the monolithic structure that could benefit from splitting the API reference into a separate file. The content is mostly concise but has minor redundancies.
Suggestions
Add explicit validation steps after posting/deleting tweets (e.g., check `r.status_code`, print `r.json()` to confirm success) to create feedback loops for destructive operations.
Extract the 'Common API calls' reference section into a separate file (e.g., X_API_REFERENCE.md) and link to it from the main skill to improve progressive disclosure.
Integrate the Joel-approval rule directly into the posting workflow as a numbered step rather than only listing it in the Rules section.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is mostly efficient with concrete code examples, but includes some unnecessary explanation (e.g., explaining what bearer tokens are for, the parenthetical about ADR-0119, noting that OAuth 1.0a tokens don't expire twice). The inline bearer token derivation script is lengthy but justified since it's executable. Some tightening possible. | 2 / 3 |
Actionability | Fully executable code throughout — the bearer token derivation script, OAuth1Session setup, and all common API calls are copy-paste ready with real endpoints, user IDs, and correct parameter structures. Secret leasing and revocation commands are concrete. | 3 / 3 |
Workflow Clarity | The auth flows are clear and the 'revoke leases after use' step is present, but there's no explicit validation/error-handling checkpoint after API calls. For destructive operations like posting tweets and deleting tweets, there's no verification step (e.g., check response status). The Rules section mentions Joel approval but doesn't integrate it into the posting workflow as a checkpoint. | 2 / 3 |
Progressive Disclosure | The content is well-structured with clear headers and logical sections, but it's a fairly long monolithic file (~130 lines of substantive content). The common API calls section could be split into a reference file. No external file references are used despite the content length warranting it. | 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
825972c
- 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.