# Agent skill

> What the Haszno agent skill is, how to install it, and how to use it with workflow recipes and safety rules.

## Overview

The Haszno agent skill is a set of guidance files that teach an AI agent (Claude Code, Claude Desktop) how to use the Haszno [MCP server](mcp.md) and [CLI](cli.md) safely. It is not a binary — it has no server or daemon. Claude Code loads it into the agent's context when the conversation matches the skill's description.

The skill covers:

- which tool surface to use (MCP vs CLI) in a given context,
- the full safety rules that govern write operations,
- step-by-step workflow recipes for common dropshipping tasks,
- domain-to-endpoint and domain-to-command mapping tables.

---

## What the skill contains

After installation the skill lives at `~/.claude/skills/haszno/`.

| File | Purpose |
|---|---|
| `SKILL.md` | Main definition: frontmatter (description and trigger keywords), quick-start, MCP vs CLI decision table, safety rules, workflow recipes, domain → endpoint map. |
| `AGENTS.md` | Headless-agent guide: environment setup, CLI usage patterns, TypeScript integration, Codex/Cursor `AGENTS.md` snippet, MCP server config. |
| `references/tools.md` | MCP tool catalogue with parameter schemas and return types. |
| `references/commands.md` | CLI command reference with flags, examples, and jq one-liners. |
| `references/recipes.md` | 9 step-by-step workflow recipes (numbered 1–8, with two recipes labelled 6) and a jq cheatsheet. |

> [!WARNING]
> Some details in the skill files (version 0.1.0) do not match the CLI and MCP server source: they describe the API key as a Bearer token (both tools send it as `x-api-key`), and they use CLI commands that do not exist in CLI 0.1.0, such as `haszno catalog …` and `haszno products list-cmd`. The [CLI reference](cli.md) and the recipes on this page follow the source code.

---

## Installation

### Recommended: unified installer

The installer in the skill repo installs the skill, the MCP server, and the CLI together:

```bash
curl -fsSL https://raw.githubusercontent.com/haszno-labs/haszno-skill/main/install.sh | bash
```

What the script does:

1. Clones `haszno-cli`, `haszno-mcp`, and `haszno-skill` into `~/.haszno/` (with `gh repo clone` when the GitHub CLI is logged in, otherwise `git clone` over HTTPS).
2. Builds the CLI and MCP server (`npm install && npm run build`).
3. Links the `haszno` binary globally with `npm link` (falls back to a `~/.local/bin/haszno` symlink).
4. Registers the MCP server with Claude Code: `claude mcp add haszno --scope user -- node ~/.haszno/haszno-mcp/dist/index.js`.
5. Copies `skills/haszno/` to `~/.claude/skills/haszno/`.

Step 4 is skipped if the `claude` command is not found (the installer prints the command to run by hand) or if `haszno` is already registered. Step 5 always runs.

### Manual: skill only

If you already have the MCP server or CLI installed and only want the skill files:

```bash
git clone https://github.com/haszno-labs/haszno-skill /tmp/haszno-skill-install
cp -a /tmp/haszno-skill-install/skills/haszno ~/.claude/skills/haszno
```

Claude Code can then load the skill in its sessions (see [Trigger keywords](#triggers)).

### Local development override

If you have the repos checked out locally:

```bash
HASZNO_SRC_DIR=~/Documents/haszno-labs bash ~/.haszno/haszno-skill/install.sh
```

---

## Where files land

| Path | Contents |
|---|---|
| `~/.claude/skills/haszno/SKILL.md` | Main skill definition. |
| `~/.claude/skills/haszno/AGENTS.md` | Headless-agent guide. |
| `~/.claude/skills/haszno/references/tools.md` | MCP tool catalogue. |
| `~/.claude/skills/haszno/references/commands.md` | CLI command reference. |
| `~/.claude/skills/haszno/references/recipes.md` | Workflow recipes. |
| `~/.haszno/haszno-mcp/` | MCP server source and build. |
| `~/.haszno/haszno-cli/` | CLI source and build. |
| `~/.config/haszno/config.json` | API credentials for the CLI and the MCP server, written by `haszno login` (not by the installer). Environment variables take precedence over it. |

---

## Trigger keywords

Claude Code decides when to load a skill from the skill's description. The Haszno skill's description covers Haszno, dropshipping pricing, price proposals, automation rules, catalogues, webshop connections, the import list, partner invites and the market blog, and its frontmatter also lists these trigger keywords:

`haszno`, `haszno.com`, `dropshipping`, `price proposal`, `árajánlat`, `automatika`, `partnerkatekógus`, `veszteséges termékek`, `margin check`, `árukereső feed`, `termékötlet`, `dropshipping check`, `pricing rules`, `árazás`, `bolt-bekötés`, `import lista`, `termékek kiküldése`, `meghívó`, `partner kapcsolat`, `heti összefoglaló`, `havi összefoglaló`.

You can also invoke it explicitly:

```bash
/haszno
```

---

## How an agent uses the skill

When the skill loads, the agent follows this sequence for any Haszno-related task:

1. **Check the MCP vs CLI table** in `SKILL.md` to decide which tool surface to use.
2. **Look up the domain** in the domain → endpoint map to find the right tool or command.
3. **For parameter details**, open `references/tools.md` (MCP) or `references/commands.md` (CLI).
4. **For multi-step workflows**, open `references/recipes.md`.
5. **Apply the safety rules** before every write call.

### MCP vs CLI decision table

| Situation | Prefer |
|---|---|
| Interactive Claude Code or Claude Desktop conversation with MCP connected | **MCP** (`haszno_*` tools) |
| Shell script, cron job, Codex agent, Cursor terminal | **CLI** (`haszno <domain> <cmd>`) |
| Programmatic TypeScript / Node integration | Direct HTTP client |
| Batch write (approve many proposals at once) | Either — the MCP tool needs `confirm: true`, the CLI command needs `--yes` |

---

## Safety rules

The skill enforces seven non-negotiable rules. The agent must apply them on every Haszno task.

**Rule 1 — Read-only by default.** Use read tools and list commands freely, without asking for user confirmation.

**Rule 2 — Every write requires explicit user confirmation.** The following operations are writes. Ask the user first, then pass `confirm: true` in the MCP tool call or `--yes` to the CLI command: approve proposals, reject proposals, rollback a batch, run a rule, list or unlist a product, apply prices, import a feed, update settings, ship an order, push an import list, create a peer invite, accept a peer invite.

**Rule 3 — Check the automation kill switch before any bulk write.** Call `haszno_automation_get` (MCP) or `haszno rules automation --json` (CLI). If `paused: true`, do not approve proposals or run rules — report the status to the user and wait for their instruction.

**Rule 4 — Rollback before escalating.** If an approved proposal batch looks wrong, call `haszno_proposals_rollback` with the `batchId` before doing anything else.

**Rule 5 — Never pass negative prices.** All prices are positive whole forints (gross HUF). There is no concept of a negative price.

**Rule 6 — Partner catalogue is aggregated.** `haszno_catalog_supplier_view` (MCP) returns aggregated reseller statistics only. The agent must not expose individual shop margins from this data.

**Rule 7 — Demo environment is read-mostly.** Read-only GETs against `https://haszno.com` are fine for smoke tests. Never POST writes to the demo unless the user explicitly confirms the intent.

---

## Recipes

These recipes follow `references/recipes.md`, with commands and tool calls corrected to the ones that exist in CLI 0.1.0 and the MCP server.

### Recipe 1 — Daily dropshipping health check

**Goal:** surface the most important issues in one pass, without changing anything.

**User prompt:** "Give me a quick overview of my Haszno account."

**Steps:**

1. Call `haszno_account_get_stats` — note `products`, `losing`, `overMarket`, `toFix`, `orders`.

   ```bash
   # CLI equivalent:
   haszno account stats --json
   ```

2. Call `haszno_automation_get` — confirm automation is not paused.

   ```bash
   haszno rules automation --json
   ```

3. Call `haszno_proposals_list` with `status: "pending"` — count pending proposals.

   ```bash
   haszno proposals list --status pending --json | jq 'length'
   ```

4. Call `haszno_orders_list` — flag any orders with `status: "error"`.

   ```bash
   haszno orders list --status error --json
   ```

5. Call `haszno_account_get_impact` with `days: 7` — show the week's profit impact.

   ```bash
   haszno account impact --days 7 --json
   ```

Report a brief summary: overall health, pending proposal count, any stuck orders, 7-day profit impact. Ask the user which item to drill into. Do not write anything.

---

### Recipe 2 — Find and fix loss-making products

**Goal:** identify products below the minimum margin and apply the recommended prices after user confirmation.

**User prompt:** "Which products are losing money? Fix them."

**Steps:**

1. Call `haszno_account_get_settings` — read `minMarginPct`.

   ```bash
   haszno account settings --json
   ```

2. Use `haszno_account_get_stats` — the `losing` field gives the count without full detail.

3. For the full list, use the CLI (the MCP server has no products tools yet — **Planned**):

   ```bash
   haszno products list --all --json \
     | jq '[.[] | select(.current.marginPct < 10) | {id, name, sku, margin: .current.marginPct, recommended: .recommended.priceGross}]'
   ```

4. Present the list to the user: `id`, `name`, `sku`, `current.marginPct`, `recommended.priceGross`. Never auto-fix.

5. Wait for explicit user confirmation of which products to fix.

6. Apply recommended prices (CLI only until the MCP products tools are available):

   ```bash
   haszno products apply-prices --ids 12,15,22 --yes
   ```

---

### Recipe 3 — Review and batch-approve price proposals

**Goal:** review pending price proposals, confirm with the user, then approve or reject.

**User prompt:** "Approve the pending price proposals."

**Steps:**

1. Check the kill switch — `haszno_automation_get`. Stop if `paused: true`.

   ```bash
   haszno rules automation --json
   ```

2. List proposals:

   ```bash
   # MCP:
   haszno_proposals_list(status="pending")
   # CLI:
   haszno proposals list --status pending --json
   ```

3. Show the user a summary: count, average price change, largest increase and largest decrease, and any proposal that would push the margin below `minMarginPct`.

4. Wait for explicit user confirmation before proceeding.

5. Approve:

   ```bash
   # MCP (save the returned batchId):
   haszno_proposals_approve(ids=[...], confirm=true)
   # CLI:
   haszno proposals approve --ids 42,43,44 --yes
   ```

6. Save the `batchId` from the approve response. If the user spots a problem, roll back:

   ```bash
   # MCP:
   haszno_proposals_rollback(batchId="<batchId>", confirm=true)
   # CLI:
   haszno proposals rollback --batch <batchId> --yes
   ```

---

### Recipe 4 — Discover new products from a supplier

**Goal:** browse a supplier's catalogue, find products worth listing, and add them to the import list after user confirmation.

**User prompt:** "Find me good products to list from supplier 3."

**Steps:**

1. Get the supplier's catalogue:

   ```bash
   # MCP:
   haszno_catalog_supplier_products(supplier_id=3)
   # CLI:
   haszno catalogue search --partner 3 --in-stock --sort margin_desc --json
   ```

2. Filter: in stock, margin at least `minMarginPct` (MCP: `potentialMargin.marginPct`; CLI: `marginPct`). In the CLI output, skip items with `inShop` or `inImportList` set to `true`.

   ```bash
   haszno catalogue search --partner 3 --in-stock --min-margin 10 --json \
     | jq '[.items[] | select(.inShop == false and .inImportList == false) | {id, name, marginPct, stock}]'
   ```

3. Present the shortlist to the user. Do not add anything automatically.

4. After user confirmation, add the selected catalogue products to the import list:

   ```bash
   # MCP:
   haszno_import_list_add(networkProductIds=[101, 102, 103])
   # CLI:
   haszno import add 101 102 103
   ```

5. Optionally push them to a connected webshop. Take the import list item IDs from `haszno import list --status varakozik --json` and the connection ID from `haszno connections list --status kapcsolva --json`:

   ```bash
   # MCP:
   haszno_import_list_push(ids=[5, 6, 7], targetConnectionId=1, confirm=true)
   # CLI:
   haszno import push --ids 5,6,7 --target 1 --yes
   ```

---

### Recipe 5 — Create a margin-guard automation rule

**Goal:** set up a rule that creates a price proposal whenever a product's margin drops below 8%.

**User prompt:** "Create a rule to flag products when their margin drops below 8%."

**Steps:**

1. Browse templates:

   ```bash
   # MCP:
   haszno_rules_list_templates()
   # CLI:
   haszno rules templates --json
   ```

2. Create the rule. A custom condition needs the MCP tool; the CLI can only create rules from the built-in templates (`keszlet_or`, `arjavaslat`, `felar_savok`, `veszteseg_riasztas`), none of which uses an 8% threshold:

   ```bash
   # MCP:
   haszno_rules_create(
     name="Margin guard",
     trigger="market_price",
     conditions=[{ "field": "marginPct", "op": "lt", "value": 8 }],
     actions=[{ "type": "propose_price" }],
     confirm=true
   )
   # CLI (template only, e.g. the proposal template):
   haszno rules create --template arjavaslat --name "Margin guard" --yes
   ```

3. Verify the rule was created:

   ```bash
   haszno rules list --json
   ```

4. Optionally run it once. This is a real run, not a dry run: it can create proposals, so ask the user first, then check `haszno proposals list --status pending --json`.

   ```bash
   haszno rules run <id> --yes
   ```

---

### Recipe 6 — Weekly product idea review

**Goal:** find products worth listing in your shop based on trend data.

**User prompt:** "What new products should I list this week?"

**Steps:**

1. Get the product ideas (they come from your own products):

   ```bash
   # MCP:
   haszno_ideas_list()
   # CLI:
   haszno ideas list --limit 10 --json
   ```

2. If many ideas have no trend keywords, fill them (AI batch, ask the user first):

   ```bash
   # MCP:
   haszno_ideas_fill_keywords(confirm=true)
   # CLI:
   haszno ideas fill-keywords --yes
   ```

3. For top candidates, check market saturation with the MCP tool `haszno_catalog_supplier_view(supplier_id=<id>)` (no CLI equivalent).

4. Present a ranked shortlist to the user (trend score, margin, saturation). Do not list anything automatically.

5. After user confirmation, list the chosen products (CLI only until the MCP products tools are available):

   ```bash
   haszno products listing <id> --on --yes
   ```

---

## Uninstall

```bash
bash ~/.haszno/haszno-skill/install.sh --uninstall
```

This removes:

- `~/.haszno/` (MCP server, CLI, and skill source).
- `~/.local/bin/haszno` symlink.
- `~/.claude/skills/haszno/`.
- MCP registration: `claude mcp remove haszno --scope user`.
- npm global link (best-effort).

It does **not** remove `~/.config/haszno/config.json`. Delete that file manually if you want to remove stored credentials.

---

## Troubleshooting

### The skill does not load automatically

If the skill is not loading:

- Check that `~/.claude/skills/haszno/SKILL.md` exists.
- Mention Haszno or one of the [trigger keywords](#triggers) in your message.
- Run `/haszno` to invoke it explicitly.

### The MCP server is not found after install

```bash
# Verify the registration:
claude mcp list

# If haszno is missing, re-register:
claude mcp add haszno --scope user -- node ~/.haszno/haszno-mcp/dist/index.js
```

### `haszno` command not found

```bash
# Check the symlink:
ls -la ~/.local/bin/haszno

# If missing, re-link:
cd ~/.haszno/haszno-cli && npm link
# or symlink ~/.haszno/haszno-cli/dist/index.js into a directory on your PATH
```

### `haszno_products_list` tool not found

This tool is **Planned** and not yet implemented in the MCP server. Use the CLI instead:

```bash
haszno products list --all --json
```

See the [Planned tools](mcp.md#planned) section of the MCP reference for the full list of tools that are not yet available.

### Write operations return 401

The demo at `https://haszno.com` does not accept write operations without credentials. See [Authentication](authentication.md) to learn what credentials are available today. If you have credentials and only the CLI gets `401`, export `HASZNO_API_KEY` (or `HASZNO_BASIC`): the CLI does not read `~/.config/haszno/config.json`.

---

## See also

- [MCP server reference](mcp.md) — full tool catalogue with input schemas.
- [CLI reference](cli.md) — all CLI commands with flags and examples.
- [Authentication](authentication.md) — API key and demo credential details.
- [Agents overview](agents.md) — when to use MCP, CLI, or the skill.