feat: xurl skill — cost-optimized X/Twitter via sandbox + live modes#70
Merged
Conversation
Add xurl skill to fiale-awesome-skills plugin wrapping the official X CLI with pay-per-use cost awareness and local playground sandbox integration. Key features: - Sandbox-first via API_BASE_URL → playground (zero cost, same commands) - Batch reads (/2/tweets?ids=...) for ~75% bulk savings - Compose + confirm gate for live writes with trust mode opt-in - Configurable session spending limits ($0.25 / $2.00 / $10.00 tiers) - Mode prefixes [SANDBOX] / [LIVE $X.XX] on every output - Error recovery for playground down, auth expired, 429, limit hit - Quick-pick menu and workflow templates (post+monitor, search+engage) Also adds fiale-awesome-skills to root README plugin table. Bumps plugin version to 0.2.0.
…timate - Fix session summary referencing non-existent /tmp/xurl-session-costs.json (correct: /tmp/xurl-session-config.json) - Use conservative full-rate estimate for batch reads in guardrail tracking (actual batch cost may be lower, but overestimating is safer)
- Add explicit issues:write + pull-requests:write permissions (pull_request_target doesn't grant these by default) - Short-circuit if PR author is repo owner (no org check needed) - Fall back to collaborator check when owner is a user account, not a GitHub org (orgs API returns 404 for user accounts)
1. Remove broken `xurl --auth app /2/usage/tweets` from session summary (requires bearer token auth, separate from OAuth2 setup user follows). Session summary now uses local spend tracker only. 2. Remove incorrect batch read 75% savings claim. X bills each post in a batch separately — batching saves rate limit quota, not credits. 3. Remove hardcoded playground account 0 from cost queries. Account ID is derived from auth token; use account-independent /api/credits/pricing. 4. Change playground default port to 3080 to avoid conflict with xurl OAuth callback on port 8080. 5. Soften README — "local session spend tracking" instead of "real usage tracking via /2/usage/tweets".
…e install 1. Replace `playground status` with `curl localhost:3080/health` for sandbox detection — upstream playground status only checks default ports (8080, 3000, 8081), not our configured 3080. 2. Add `-p 3080` to error recovery playground start command — was missing, would start on wrong port. 3. Make trust mode per-session only — reset trusted_actions to [] at session start. Previously trusted_actions persisted in /tmp across sessions, allowing a later session to skip write confirmations unexpectedly. 4. Integrate playground installation into first-use flow — offer to install when not found, check for Go, link to pre-built binaries as fallback.
1. Use inline API_BASE_URL=... prefix on every sandbox command instead of export. Export doesn't persist between separate Bash tool calls, so later commands could silently hit the real API. 2. Reset spent/operations/trusted_actions at session start — only spending_limit carries over. Prevents false warnings from stale spend data inherited from prior sessions.
xurl needs OAuth credentials to construct requests even against the local playground (which accepts any token without billing). A user with playground running but no auth configured would hit 401s. Now clearly states auth is required for both modes and guides users to set up auth first when playground-only state is detected.
playground start is a foreground server — running it directly would hang the agent session. Now uses &>/dev/null & to detach, followed by a health check to verify it started.
OAuth2 flow fails unless the app is set as default first. Add xurl auth default <app> before xurl auth oauth2.
…ndpoints Playground validates OAuth token type. xurl shortcut commands that require user-context auth (whoami, post, like, follow, dm) fail with 403 because playground sees the token as app-only. App-auth shortcuts (search, read) work fine. Document raw path workaround for user-context endpoints in sandbox mode.
…workflow 1. Replace dump-all-setup with guided first-run interview: detect what's configured, show status checkmarks, ask what user wants to do, guide through only the missing pieces. 2. Document both auth types clearly: - OAuth2 for user-context ops (post, like, timeline, bookmarks) - Bearer token for usage tracking (/2/usage/tweets) Both recommended, each with setup instructions. 3. Add bookmark processing workflow: fetch → read → process into knowledge base → optionally unbookmark. Cost estimate included. 4. Restore usage API in session summary now that bearer token setup is documented. Notes it only tracks post reads, not all operations.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
0.1.0→0.2.0Cost optimization features
API_BASE_URL— same xurl commands, zero costAPI_BASE_URL=http://localhost:3080 xurl ...prefix per command (no export leak across tool calls)[SANDBOX]/[LIVE $X.XX]on every output/2/usage/tweets(requires bearer token auth)Auth model
Two auth types, both recommended:
Workflows included
Known sandbox limitation
Playground validates OAuth token type. User-context shortcuts (
whoami,post,like) need raw path form in sandbox. App-auth shortcuts (search,read) work directly.Files changed
plugins/fiale-awesome-skills/skills/xurl.mdplugins/fiale-awesome-skills/commands/xurl.mdplugins/fiale-awesome-skills/.claude-plugin/plugin.json.claude-plugin/marketplace.jsonplugins/fiale-awesome-skills/README.mdREADME.md.github/workflows/pr-gate.ymlTest plan
xurl whoami)xurl bookmarks -n 10returns real dataxurl --auth app "/2/usage/tweets?days=1"returns consumption/xurltriggers skill and first-run interview works