Expand Skill

Verify it works by asking the agent:

The skill works on its own whenever your agent can run terminal commands. Add MCP when you want the agent to call Expand as native tools instead of shelling out. For Claude Code and OpenCode, the recommended full setup is a hook.

Install commands

Run the command from your project root when you use project scope, so the files land next to the code the agent works on.

Global variants make the skill available across every project:

Use project scope when the setup should travel with one repository. Use global scope when you want the same skill in every project on your machine.

Skill, MCP, and hooks

These three surfaces stack. The skill gives your agent instructions for using the Expand CLI from the shell. MCP gives it native Fetch tools. Hooks wire Expand into the host's own fetch behavior where the host supports it.

Skill alone is enough when your agent can run terminal commands. Add MCP when you want the agent to call Expand as native tools instead of shelling out. For Cursor and Codex, the full setup is Skill + MCP. For Claude Code and OpenCode, a hook is usually the best full setup because it upgrades the host's own fetch behavior. Cursor and Codex do not have an Expand hook path.

What the skill teaches

Fetch live pages

Use expandai fetch <url> when the agent needs rendered page content instead of raw HTML. Expand renders the live page, so it handles SPAs and bot-protected sites that plain curl cannot.

Inspect object-mode output

Use JSON output when the agent needs the page metadata, Main Markdown, and State JSON together.

In object-mode output, the reusable snapshot handle is meta.snapshotId.

Reuse snapshots

Use expandai search <snapshotId> "your query" to search a page that was already captured instead of fetching the same URL again. Expand calls this search experience Highlights.

Use expandai fetch <url> --search "query" only for a one-shot fetch and search of a URL you have not captured yet. Once the agent has a snapshotId, prefer expandai search, which reuses the existing capture.

Return citations

Search-backed claims should carry citation links. In text output, expandai search and expandai fetch --search print a public playground citation link above each snippet. MCP tool results expose citationUrl fields directly. The skill instructs the agent to return those links alongside any claim grounded in fetched content.

Ask for more context

Start with Markdown. Reach for JSON, snapshot search, and referenced artifacts only when the task needs more than the main document. This keeps the agent's first read cheap and lets it pull detail on demand.

Stay in the user's auth boundary

If Expand is not authenticated, the agent should ask the user to run expandai login rather than authenticating on the user's behalf.

Installed locations

Most users never need these paths. Reach for them when the agent does not see the skill or when project versus global scope looks wrong.

Codex uses .agents/skills/expandai/, not .codex/skills/expandai/.

Project-scoped skill files are written into the repository. Commit them only when the team wants Expand enabled for collaborators.

Update and uninstall

There is no separate expandai skill update command. Reinstall the skill to update it. The installer overwrites the existing Expand Skill directory for the selected host and scope.

Uninstall removes the skill directory for that host and scope:

Troubleshooting

My agent does not see the skill

• Confirm you installed for the right host.
• Confirm project versus global scope.
• Restart the agent if the host does not hot-reload skills.
• Confirm SKILL.md exists at the expected path from the table above.
• For project scope, confirm you ran the install command from the project root.

The skill runs but Fetch fails

Run expandai login in your terminal, then ask the agent to try again. A non-zero exit with Not authenticated means the CLI has no session.

I need tools, not just instructions

Install MCP for Cursor, Codex, or another MCP-compatible client when you want the agent to call Expand tools directly instead of relying on shell commands.

Read MCP Tools & Resources for the full tool list.

Next steps

• Agent Quickstarts overview
• Claude Code
• Cursor
• Codex
• OpenCode
• Skill-Based Agents
• CLI Commands