npm package: @obul.ai/skills
Description: Install x402 skills into your AI coding agent
Latest version: 0.4.0

# @obul.ai/skills

Install paid API skills into your AI coding agent. Skills are pay-per-use tools that your agent can call — search the
marketplace, install with one command, and your agent gets new capabilities instantly.

## Quick start

```bash
npx @obul.ai/skills search "image generation"
npx @obul.ai/skills add <skill-id>
```

That's it. The CLI auto-detects which coding agents you have and installs the skill into all of them.

## Supported agents

| Agent          | Project dir  | Global dir                  |
|----------------|--------------|-----------------------------|
| Claude Code    | `.claude/`   | `~/.claude/`                |
| Cursor         | `.cursor/`   | `~/.cursor/`                |
| Windsurf       | `.windsurf/` | `~/.codeium/windsurf/`      |
| Codex          | `.codex/`    | `~/.codex/`                 |
| GitHub Copilot | `.github/`   | `~/.config/github-copilot/` |
| Gemini CLI     | `.gemini/`   | `~/.gemini/`                |
| Amp            | `.amp/`      | `~/.config/amp/`            |
| Goose          | `.goose/`    | `~/.config/goose/`          |
| Cline          | `.cline/`    | `~/.cline/`                 |
| Roo            | `.roo/`      | `~/.roo/`                   |
| OpenCode       | `.agents/`   | `~/.config/opencode/`       |
| Continue       | `.continue/` | `~/.continue/`              |
| Kiro           | `.kiro/`     | `~/.kiro/`                  |
| Trae           | `.trae/`     | `~/.trae/`                  |

## Commands

### `search [query]`

Browse the skills marketplace.

```bash
npx @obul.ai/skills search                          # list all skills
npx @obul.ai/skills search "web scraping"            # search by keyword
npx @obul.ai/skills search --sort top-rated --limit 5
```

### `info <skill-id>`

Show details for a skill — description, endpoints, pricing, and health status.

```bash
npx @obul.ai/skills info my-skill
```

### `add <skill-id>`

Install a skill. Detects your coding agents and writes a `SKILL.md` file into each one.

```bash
npx @obul.ai/skills add my-skill                    # project-level install
npx @obul.ai/skills add my-skill --global            # global install
npx @obul.ai/skills add my-skill --harness claude-code  # target specific agent
```

### `remove <skill-id>`

Remove an installed skill from all harnesses.

```bash
npx @obul.ai/skills remove my-skill
```

### `update [skill-id]`

Update installed skills to the latest version. Omit the skill ID to update all.

```bash
npx @obul.ai/skills update              # update all
npx @obul.ai/skills update my-skill     # update one
```

### `list`

List installed skills.

```bash
npx @obul.ai/skills list                # project-level
npx @obul.ai/skills list --global       # global
```

## Options

| Flag               | Short | Description                                      |
|--------------------|-------|--------------------------------------------------|
| `--global`         | `-g`  | Install/list globally (home directory)           |
| `--harness <name>` | `-a`  | Target a specific agent harness                  |
| `--sort <method>`  |       | Sort search results (e.g. `newest`, `top-rated`) |
| `--limit <n>`      |       | Max search results to return                     |
| `--api <url>`      |       | Override API base URL (env: `X402_API_BASE`)     |
| `--help`           | `-h`  | Show help                                        |
| `--version`        | `-v`  | Show version                                     |

## How it works

1. You run `npx @obul.ai/skills add <skill-id>`
2. The CLI fetches the skill's `SKILL.md` from the Obul marketplace API
3. It detects which coding agents are present in your project (or globally with `-g`)
4. It writes the `SKILL.md` into each agent's skills directory (e.g. `.claude/skills/<skill-id>/SKILL.md`)
5. A lockfile (`.agent-skills.lock.json`) tracks what's installed for updates and removal

Your coding agent reads the `SKILL.md` at startup and gains the ability to call the skill's API endpoints, paying per
use.

## License

MIT