> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hostreach.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Skill

> Teach AI coding agents best practices for using the Hostreach API.

The Hostreach Agent Skill is a `SKILL.md` file that gives AI coding agents (Cursor, Claude Code, Codex, OpenCode) deep knowledge of Hostreach workflows, scopes, pagination, polling patterns, and error handling.

## Install via npx (no CLI needed)

```bash theme={null}
# Interactive — choose agent and scope
npx skills add Hostreach/agent-skills

# Global install for Cursor
npx skills add Hostreach/agent-skills -g -a cursor

# Global install for Claude Code
npx skills add Hostreach/agent-skills -g -a claude-code

# Global install for all supported agents
npx skills add Hostreach/agent-skills -g --all
```

Uses the [skills CLI](https://github.com/vercel-labs/skills) under the hood — no global install required.

## Install via Hostreach CLI

```bash theme={null}
npm install -g @hostreach/cli

hostreach skill install                      # Cursor (default), global
hostreach skill install --agent claude       # Claude Code, global
hostreach skill install --agent codex        # Codex, global
hostreach skill install --agent opencode     # OpenCode, global
hostreach skill install --all                # all agents, global
hostreach skill install --all --project      # all agents, project-level (cwd)
hostreach skill print                        # dump to stdout — paste anywhere
```

## What the skill teaches agents

* When to use the MCP server vs CLI vs direct REST API
* Authentication methods and priority order
* All CLI commands with flags and output options
* Lead statuses and valid enum values (`PENDING`, `CONTACTED`, `INTERESTED`, etc.)
* How to poll async extraction jobs without infinite loops
* Pagination patterns (`--page` / `--limit`)
* Error codes and recovery actions (`HTTP_401`, `HTTP_403`, `HTTP_429`)
* API key scopes and what a `403` response means
* Common workflows: lead extraction, campaign management, CRM updates, valuations, fichas, webhooks

## Update installed skills

```bash theme={null}
npx skills update Hostreach/agent-skills
```

## Use MCP + Skill together

For the best agent experience, combine both:

1. **MCP server** — gives the agent direct tool access to all Hostreach APIs
2. **Agent Skill** — teaches the agent how to use those tools effectively

```bash theme={null}
hostreach agent add cursor      # configure MCP server
hostreach skill install         # install the skill
```