Skip to content

Add an agent skill for using the CLI (skills/ directory) - #55

Open
robertn702 wants to merge 2 commits into
tamnd:mainfrom
robertn702:add-agent-skill
Open

robertn702 wants to merge 2 commits into
tamnd:mainfrom
robertn702:add-agent-skill

Conversation

@robertn702

@robertn702 robertn702 commented Sep 3, 2026 •

Copy link
Copy Markdown

Closes #54

What

Ships a first-party agent skill at skills/x-cli/SKILL.md teaching coding agents how to use the x CLI effectively, in the SKILL.md format agents load on demand.

Contents

  • Install paths and x doctor as the first health check
  • The credential tier model (Tier 0 syndication / --guest / session) — the one thing agents must know to route reads correctly, including the exit-4 needs-auth signal
  • A question-to-command map with the tier each read needs, mirroring the README table
  • Core workflows: search a topic (search + counts), read a thread (thread + replies), pull a users tweets (timeline --guest), crawl into the local store and query/export it (crawl, db stats, query, export)
  • Output shaping for pipelines (JSONL when piped, -o, --fields, --template, string ids), exit codes (4/5/6), and rate-limit behavior
  • The read-only guarantee, stated up front
  • Pointer to x mcp for agents that prefer MCP over shelling out, and to the self-describing commands (x tiers, x routes, x surfaces, x fields, x <cmd> --help) so the skill stays true as the CLI moves

Maintenance

None beyond the CLI itself: the skill leans on the self-describing commands and the docs site rather than duplicating their tables.

Validation

Crosschecked with a with-skill vs. baseline agent eval (3 realistic prompts, subagents running the built binary against live X): read a tweet/thread, rank a users recent tweets by likes, and per-day topic counts — the last one exercising the session + rate-limit path. With-skill runs passed 14/14 objective assertions (author/content verified against independent pulls; counts matched ground truth exactly), baselines 9/14. The skills visible effects: health-check discipline on every run, correct tier routing, and on the rate-limited read, waiting out the window and delivering the full answer instead of stopping at the first failure. The description also follows the pushy/trigger-dense convention so the skill fires even when the CLI is not named.

Teaches coding agents the x CLI without README-scraping: the credential
tier model, a question-to-command map, the core workflows (search, read
a thread, pull a timeline, crawl-and-query the local store), output
shaping for pipelines, exit codes, and the read-only guarantee. The
skill points at the self-describing commands (x doctor, x tiers, x
routes, x surfaces, x --help) rather than duplicating their tables, and
at x mcp for agents that prefer MCP over shelling out.

Closes tamnd#54
skill-creator guidance: descriptions are the trigger, and the failure
mode is undertriggering, so name the cases where the CLI is not
mentioned (a bare x.com link, a thread to read, a topic to count) as
well as the capabilities.
@robertn702
robertn702 marked this pull request as ready for review September 3, 2026 16:54

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add an agent skill for using the CLI (skills/ directory)

1 participant