> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/wevm/incur/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Discovery

> Built-in mechanisms for agents to discover your CLI automatically

Agents can only use your CLI if they know it exists. incur solves this with three built-in discovery mechanisms—no manual config, no copy-pasting tool definitions.

## Three Discovery Mechanisms

incur provides three ways for agents to discover and use your CLI:

1. **Skills** (recommended – lighter on tokens)
2. **MCP server** (Model Context Protocol)
3. **`--llms` flag** for direct manifest inspection

## Skills

Skills provide the most token-efficient discovery mechanism. They load command metadata on-demand rather than injecting everything at session start.

### Add Skills

```sh theme={null}
my-cli skills add
```

This command:

* Auto-generates skill files from your commands
* Installs them to the agent's skills directory
* Splits by command group for on-demand loading

### How It Works

Skills use a two-phase loading strategy:

**Session start** — Only frontmatter (name + description) is loaded

**On demand** — Full command details load when the agent needs them

This approach uses **up to 29.7× fewer tokens** during discovery compared to loading a monolithic skill file.

### Agent Quickprompt

Tell your agent:

```txt theme={null}
Run `npx incur skills add`, then show me how to build CLIs with incur.
```

## MCP Server

Register your CLI as an MCP (Model Context Protocol) server so agents can invoke commands as tools.

### Add MCP

```sh theme={null}
my-cli mcp add
```

This registers your CLI with supported agents:

* Claude Code
* Cursor
* Windsurf
* Amp
* Cline
* And more

### MCP Quickprompt

Tell your agent:

```txt theme={null}
Run `npx incur mcp add`, then show me how to build CLIs with incur.
```

### MCP vs Skills

MCP injects all tool schemas into every turn, making it heavier on tokens:

```
┌─────────────────┬────────────┬─────────┬───────────────┐
│                 │ MCP + JSON │   incur │ vs. incur     │
├─────────────────┼────────────┼─────────┼───────────────┤
│ Session start   │      6,747 │     805 │         ↓8.4× │
│ Discovery       │          0 │     387 │        ↓29.7× │
│ Invocation (×5) │        110 │      65 │         ↓1.7× │
│ Response (×5)   │     10,940 │   5,790 │         ↓1.9× │
├─────────────────┼────────────┼─────────┼───────────────┤
│ Cost            │    $0.0325 │ $0.0131 │         ↓3.1× │
└─────────────────┴────────────┴─────────┴───────────────┘
```

<Note>**Skills are recommended** for most use cases due to significantly lower token usage.</Note>

## LLMs Flag

Output a machine-readable manifest of all commands for direct inspection or custom integrations.

### Markdown Format

```sh theme={null}
my-cli --llms
```

Outputs a token-efficient Markdown manifest:

```
# my-cli

## install

Install a package

**Usage:** `my-cli install [package]`

**Arguments:**
- `package` (string, optional) – Package name

**Options:**
- `--saveDev` (boolean) – Save as dev dependency
```

### JSON Schema Format

```sh theme={null}
my-cli --llms json
```

Outputs JSON Schema for programmatic consumption:

```json theme={null}
{
  "tools": [
    {
      "name": "install",
      "description": "Install a package",
      "inputSchema": {
        "type": "object",
        "properties": {
          "package": {
            "type": "string",
            "description": "Package name"
          },
          "saveDev": {
            "type": "boolean",
            "description": "Save as dev dependency"
          }
        }
      }
    }
  ]
}
```

## Implementation

All discovery mechanisms are automatically available on every incur CLI:

```ts theme={null}
import { Cli, z } from 'incur'

Cli.create('my-cli', {
  description: 'My CLI',
})
  .command('status', {
    description: 'Show repo status',
    run() {
      return { clean: true }
    },
  })
  .serve()
```

No additional configuration needed. Every CLI gets:

* `my-cli skills add`
* `my-cli mcp add`
* `my-cli --llms`
* `my-cli --llms json`

## Session Savings

Combining on-demand skill loading with TOON output, incur cuts token usage across the entire session—from discovery through invocation and response.

In a typical session with a 20-command CLI:

* **3.1× lower cost** vs MCP + JSON
* **3.1× lower cost** vs monolithic skill + JSON
* **8.4× fewer tokens** at session start vs MCP
* **29.7× fewer tokens** during discovery vs monolithic skill

<Tip>Use `my-cli skills add` for the best token efficiency and agent experience.</Tip>