# NeoSpark Agent Install Guide

Source: <https://useneospark.com/install/agent.md>

You are an AI agent. This page tells you how to connect to NeoSpark, find the right Skill for the user's task, and run it. Follow the steps in order, and stop to ask the user whenever a step needs their browser, their sign-in or a paid decision.

NeoSpark is a marketplace of hosted Agent Skills. A Skill is a `SKILL.md` package with instructions, templates and optional Python tools that runs on NeoSpark's runtime. Skills are executed on the platform: you connect once, then call the Skill and hand its output back to the user. If a page says "connect the official CLI", this connection is what it refers to.

## 1. Connect

Use path A unless the user already has an API key they want you to use.

### A. Skill package (recommended)

1. Ask the user to sign in at <https://useneospark.com> and open the Skill page they want.
2. On that page, choose **Download**. It returns `neospark-<skill-id>-skill.zip`, containing:
   - `skill/SKILL.md` — a native Claude Code / Codex skill that calls this Skill's MCP tool,
   - `install.sh` / `install.ps1` — installers (they copy the skill, write the MCP config and run a self-check),
   - `verify_install.py`,
   - `claude.mcp.json` and `codex-config.toml` for manual configuration,
   - `README.md`,
   - an `nsk_` key scoped to that one Skill.
3. Run `./install.sh` (or `.\install.ps1`) inside the unzipped folder, then restart the client. The user can now invoke `/<skill-name> <request>`, and the skill calls the MCP tool.
4. Verify with `claude mcp list` (or `codex mcp list`): the Skill's server must be listed as connected.

**Key rules:**

- The key is `nsk_...` and only works against the MCP endpoint, as `Authorization: Bearer nsk_...` or `X-Skill-Key: nsk_...`. It is **not** an API key — never send it as `X-API-Key` to the REST endpoints.
- The key is rotated on every download. Only the newest download works, and the plaintext key is returned once. **Reinstall from the newest package**; never reuse an older archive or an older config block.
- If the MCP tool reports `401`, the key was rotated or revoked. Ask the user to download the newest package and reinstall it; do not retry with the same key.
- Never write the key into the user's project, a repository or a log.

### B. MCP-only bundle

`GET /api/v1/agents/skills/{skill_id}/mcp-bundle?format=mcp` returns `neospark-<skill-id>-mcp.zip` with `.mcp.json`, `codex-config.toml` and a README. Use it when the client only needs the MCP configuration and the user installs skills by hand.

### C. API key (direct REST)

Ask the user for an `np_` API key created from their NeoSpark account, then send it on every REST request:

```http
X-API-Key: np_xxxxxxxx
```

`Authorization: ApiKey np_xxxxxxxx` is accepted as well. A browser session cookie also works when you are running inside the signed-in chat app.

The base URL is `https://api.useneospark.com/api/v1`.

## 2. Find the Skill

List the catalogue (no key required for the listing):

```http
GET https://api.useneospark.com/api/v1/agents/skills
```

Each entry carries `id`, `name`, `description`, `version`, `model`, `output`, `category`, `price`, `price_points`, `rating`, `installs`, `execution_mode`, `has_code`, `code_functions` and preview images. Match them against the user's request and show the user the Skill's name, what it makes and its price before you run anything.

Get one Skill and its callable tools:

```http
GET https://api.useneospark.com/api/v1/agents/skills/{skill_id}
GET https://api.useneospark.com/api/v1/agents/skills/{skill_id}/functions
```

## 3. Run the Skill

Through the skill package, call the MCP tool. For direct REST use:

```http
POST https://api.useneospark.com/api/v1/agents/skills/{skill_id}/invoke
X-API-Key: np_xxxxxxxx
Content-Type: application/json

{
  "message": "the task, in the user's words",
  "model_override": null,
  "session_id": null,
  "thinking_depth": "medium"
}
```

- `message` is required. `model_override`, `session_id` and `thinking_depth` (`low`, `medium`, `high`) are optional.
- Pass the returned `session_id` back in to continue the same conversation.
- For streaming output, use `POST /agents/skills/{skill_id}/invoke/stream`.
- The response contains `content`, `skill_id`, `model`, `session_id`, optional structured `blocks` and `usage` — the token count and the credits the run cost. Report that cost to the user.

Handle the documented error codes: `401` means the key or session is invalid, `402` means the balance is too low, `404` means the Skill does not exist. On `402`, stop and ask the user to top up or choose a free Skill; never retry a paid call on your own.

## 4. Rules

- Show the price and get the user's explicit approval before any paid run.
- Never write API keys, bundle keys or Skill source into a repository, a project file or a log.
- Do not call a Skill the user did not ask for, and do not chain paid runs without asking.
