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

# Buying Skills

> How to discover, purchase, and install skills from the marketplace

## Browsing the Marketplace

### Search

Find skills by keyword:

```bash theme={null}
ap search "python testing"
```

Or via the API:

```bash theme={null}
curl "https://api.agentpowers.ai/v1/search?q=python+testing"
```

The search endpoint returns **sectioned results** -- AgentPowers native skills first, then external sources (like ClawHub):

```json theme={null}
{
  "agentpowers": {
    "items": [
      {
        "slug": "py-test-pro",
        "title": "Python Test Pro",
        "price_cents": 500,
        "security_status": "pass",
        "download_count": 120
      }
    ],
    "total": 1,
    "limit": 20,
    "offset": 0
  },
  "clawhub": {
    "items": [
      {
        "slug": "pytest-helper",
        "title": "Pytest Helper",
        "source": "clawhub",
        "source_url": "https://clawhub.ai/skills/pytest-helper",
        "source_installs": 89,
        "ap_security_status": "pass"
      }
    ],
    "total": 1
  }
}
```

### Skill Detail

Get full details for any skill (native or external) via the unified detail endpoint:

```bash theme={null}
curl "https://api.agentpowers.ai/v1/detail/my-skill"
```

Add `?source=clawhub` to target a specific source:

```bash theme={null}
curl "https://api.agentpowers.ai/v1/detail/my-skill?source=clawhub"
```

### Filter and Sort

The `GET /v1/skills` endpoint supports filtering and sorting:

| Parameter         | Values                                           | Description               |
| ----------------- | ------------------------------------------------ | ------------------------- |
| `category`        | Any category slug                                | Filter by category        |
| `type`            | `skill`, `agent`                                 | Filter by type            |
| `sort`            | `newest`, `price_asc`, `price_desc`, `downloads` | Sort order                |
| `price_filter`    | `free`, `paid`                                   | Filter by price           |
| `security_status` | `pass`, `warn`                                   | Filter by security status |

```bash theme={null}
curl "https://api.agentpowers.ai/v1/search?q=&sort=downloads&price_filter=free&type=skill"
```

### Categories

There are 7 canonical categories. All always appear in the response even when empty:

| Slug           | Name         | Icon        |
| -------------- | ------------ | ----------- |
| `marketing`    | Marketing    | megaphone   |
| `development`  | Development  | code        |
| `productivity` | Productivity | zap         |
| `design`       | Design       | palette     |
| `sales`        | Sales        | trending-up |
| `data`         | Data         | bar-chart   |
| `security`     | Security     | shield      |

```bash theme={null}
# List all categories with live skill counts
curl "https://api.agentpowers.ai/v1/categories"

# Get a specific category with its skills
curl "https://api.agentpowers.ai/v1/categories/development"
```

Each category object includes `name`, `description`, `icon`, `sample_keywords`, and `count`.

## Installing Free Skills

Free skills require no authentication:

```bash theme={null}
ap install skill-slug
```

The CLI downloads and extracts the package to `~/.claude/skills/skill-slug/`.

## Purchasing Paid Skills

1. Run `ap install paid-skill-slug`
2. The CLI opens Stripe Checkout in your browser
3. Complete payment
4. The skill installs automatically

### Post-Checkout Confirmation

After Stripe redirects back, the purchase is confirmed via:

```text theme={null}
GET /v1/purchases/confirm?session_id=cs_live_...
```

This endpoint verifies the Stripe session and returns the purchase record with license code.

### Direct Download

After checkout is confirmed, the success page shows a **Download files** button. You can also fetch the package directly:

```text theme={null}
GET /v1/purchases/download?session_id=cs_live_...
```

Returns `{ url, slug, license_code }` where `url` is an R2 presigned download link (valid
for 1 hour) and `license_code` is the purchase license code. No auth header required —
the Stripe session ID acts as the bearer token.

Returns `403` if the session is not yet paid (e.g., payment is processing or the checkout expired).

### License Codes

Each purchase generates a license code (`XXXXXXXX-XXXXXXXX-XXXXXXXX` format, 26 characters).
Use it to install on another machine:

```bash theme={null}
ap install paid-skill --code A1B2C3D4-E5F6A7B8-C9D0E1F2
```

Or redeem via the API:

```bash theme={null}
curl -X POST "https://api.agentpowers.ai/v1/purchases/redeem" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"license_code": "A1B2C3D4-E5F6A7B8-C9D0E1F2"}'
```

## Checking Purchases

View your purchase history:

```bash theme={null}
curl -H "Authorization: Bearer TOKEN" \
  "https://api.agentpowers.ai/v1/purchases"
```

## Updating Installed Skills

When new versions are available, update your installed skills:

```bash theme={null}
ap update my-skill          # Update a single skill
ap update                   # Check all installed skills for updates
ap update --force           # Skip the confirmation prompt
```

The update command works for **both native AgentPowers skills and external skills** (e.g., ClawHub):

1. Compares your installed version against the latest version on the API
2. Downloads and installs the new version if one is available
3. Updates the version pin

For external skills, updates go through the same sandboxed security pipeline as the initial install -- the new version is downloaded to a sandbox, scanned, and only installed if it passes.

**Locally edited skills are protected.** If you've modified an installed skill's files, `ap update` detects the change via content hash and prompts before overwriting:

```text theme={null}
# When a newer version is available:
my-skill has been locally edited.
Update my-skill anyway? Local changes will be overwritten [y/N]:

# When already at the latest version:
my-skill has been locally edited.
Restore my-skill to original? Local changes will be overwritten [y/N]:
```

The default is **No** -- pressing Enter skips the update. Use `--force` to bypass the prompt entirely. This applies to both native and external skills.

When running `ap update` (all), each edited skill with an available update is prompted individually during the download phase, giving you per-skill control over which edits to keep.

**Paid skills update for free.** If you purchased a skill, all future versions are included -- no additional payment required.

### Checking Edit Status

The `ap search` command shows whether installed skills have been locally modified:

* **Yes** (green) -- installed, unmodified
* **Edited** (yellow) -- installed, locally modified (hash mismatch)

## Reviews

### Viewing Reviews

See what other users think before you buy or install:

```bash theme={null}
curl "https://api.agentpowers.ai/v1/skills/my-skill/reviews"
```

Returns a list of reviews with individual ratings and an overall average:

```json theme={null}
{
  "items": [
    {
      "id": "review-1",
      "rating": 5,
      "text": "Excellent skill, saved me hours of work.",
      "user_id": "user_abc",
      "created_at": "2026-03-01T12:00:00Z"
    }
  ],
  "total": 1,
  "skill_slug": "my-skill",
  "average_rating": 5.0
}
```

The `GET /v1/detail/{slug}` endpoint also includes `rating_average` and `rating_count` fields, so you can see the overall rating without fetching individual reviews.

The CLI shows star ratings in `ap detail`:

```bash theme={null}
ap detail my-skill
# Rating: ★★★★★ (4.8 avg, 23 reviews)
```

### Leaving a Review

After installing or purchasing a skill, leave a review (requires authentication):

```bash theme={null}
curl -X POST "https://api.agentpowers.ai/v1/skills/my-skill/reviews" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"rating": 5, "text": "Great skill!"}'
```

* **Rating** is required (1-5 stars)
* **Text** is optional but encouraged
* You cannot review your own skills (returns 400)
* One review per user per skill (duplicate returns 409)
* Archived skills cannot be reviewed (returns 404)

## Managing Billing

After your first purchase, you can manage payment methods, view invoices, and update billing details through the Stripe Customer Portal.

### Via the Dashboard

Navigate to **Dashboard > Settings > Billing** and click **Manage in Stripe**. This opens the Stripe Customer Portal where you can:

* Update or remove payment methods
* View and download invoices
* Update billing information

### Via the API

Create a portal session programmatically:

```bash theme={null}
curl -X POST "https://api.agentpowers.ai/v1/billing/portal" \
  -H "Authorization: Bearer TOKEN"
```

Returns a redirect URL:

```json theme={null}
{
  "url": "https://billing.stripe.com/p/session/..."
}
```

<Note>
  The billing portal is only available after your first purchase. If you haven't purchased anything yet, the endpoint returns a 404.
</Note>

## ZIP Downloads (claude.ai Web)

For claude.ai web users who cannot use the CLI, skills are available as ZIP downloads:

```text theme={null}
GET /v1/skills/{slug}/download/zip
```

This returns the package as a ZIP file with `Content-Disposition: attachment`.

## Need Help?

<CardGroup cols={2}>
  <Card title="Email Support" icon="envelope" href="mailto:support@agentpowers.ai">
    Reach us at **[support@agentpowers.ai](mailto:support@agentpowers.ai)** for account issues, billing questions, or technical help.
  </Card>

  <Card title="Discord Community" icon="discord" href="https://discord.gg/ECAzvrvHA">
    Join the **AgentPowers Discord** to get help from the team and other creators in real time.
  </Card>
</CardGroup>