Skills for Agents

Most CLIs are documented for humans. The developer reads the README, learns the flags, writes the command. An AI agent has to read the same README, extract the relevant information, and figure out the correct usage from prose — every time.

tabstack takes a different approach: the CLI knows how to use itself, and can install that knowledge into any agent that uses it.

What a skill is

A skill is a markdown file with a frontmatter description: field that matches natural language triggers. When an AI agent (like Claude Code) sees a task that matches the description, it loads the skill automatically before generating any commands.

The skill tells the agent:

• What commands exist and what they produce
• The exact jq selectors for each event type
• Which flags are required for which use cases
• What exit codes mean
• The verb-arbitrage rule (when to use research vs extract)

Without the skill, an agent working on a task that needs live web data has to discover all of this. With the skill loaded, it already knows.

How the skill gets selected

Claude Code reads the description field in the skill’s YAML frontmatter to decide whether the skill is relevant to the current task:

---
name: tabstack
description: Use when a task needs live web data in a script or pipeline —
  extracting structured JSON or clean markdown from any URL, web research
  with citations, transforming pages with AI, or natural-language browser
  automation.
---

The match is semantic. Claude Code doesn’t look for the word “tabstack” in the user’s message — it matches the intent. A few examples of what triggers it:

Once loaded, the skill body takes over — verb rules, jq selectors, exit codes, the extract-vs-research arbitrage. The description is the selector. The body is the instruction manual after selection.

Installing the skill

# Claude Code — all sessions (installs to ~/.claude/skills/tabstack/)
tabstack skill install

# Claude Code — this project only (.claude/skills/tabstack/)
tabstack skill install --project

# Codex, Cursor, Copilot, VS Code, any agent that reads AGENTS.md
tabstack skill agents >> AGENTS.md

# Print the raw skill markdown — pipe it anywhere
tabstack skill

After tabstack skill install, Claude Code knows about tabstack whenever it’s relevant. Before generating a command that needs live web data, it reads the cookbook. Before running research, it checks the extract-vs-research rule.

Install overwrites, not appends. Each run of tabstack skill install replaces the skill file completely — so upgrading tabstack and re-running the command always gets you the latest version. If you’ve manually edited ~/.claude/skills/tabstack/SKILL.md, those edits will be lost. The tabstack skill agents >> AGENTS.md variant is a plain shell append, so running it twice will duplicate the section.

tabstack skill install makes no network call. The skill content is embedded in the binary itself — it installs and upgrades fully offline.

The self-hosting trick

The skill is embedded in the binary itself — in src/skill.ts as a string constant called SKILL_MD. The tabstack skill install command writes that string to the skills directory. The tabstack skill agents command outputs the AGENTS.md section.

# These all produce the same content:
tabstack skill
cat ~/.claude/skills/tabstack/SKILL.md

A test in the suite enforces byte-identity between the embedded string and the file on disk. If someone edits one and not the other, bun test fails. This keeps the two sources of truth in sync automatically.

Why embed it in the binary

The alternative is a separate documentation URL that the agent fetches. That has problems:

1. The docs can be out of date relative to the installed version
2. The agent needs network access to load the skill
3. The skill isn’t discoverable without knowing the URL

An embedded skill is always at the right version. It installs offline. It’s discovered by running the tool the developer already installed.

The AGENTS.md standard

The AGENTS.md file in a repository root is read automatically by Codex, Cursor, GitHub Copilot, and other agents that use the repository as context. It’s a community convention for “here is how to use the tools in this repo.”

tabstack skill agents >> AGENTS.md

The output includes: the verb reference (what each command produces), the NDJSON event filter patterns, exit code meanings, safety flags, and the budget guidance. Everything an agent needs to drive tabstack correctly without trial-and-error.

The verb-arbitrage rule

One section of the skill encodes a rule that came from two controlled experiments run live with real credits:

Default to extract. If you can name the sources, extract them (~10 credits/page) and synthesize in-context. Two experiments found extract beats research on quality at 4–25× lower cost. One research call ≈ 25 extract calls. Buy it only when source discovery is the hard part.

This rule is in the skill, in AGENTS.md, and in the README’s usage section. The point is: an agent that knows this rule makes better decisions about when to spend credits. An agent that doesn’t might run a 250-credit research call for a question that a 10-credit extract would answer better.

See Cost Tracking for how the credit cost numbers were measured.