---
name: "@paperclip-skills/cli-docs"
version: "1.0.0"
author: "Paperclip AI"
description: >
  Complete reference for the paperclip-skills CLI. Covers writing skill.md files,
  all CLI commands (login, validate, publish, preview, versions), the front-matter
  schema, and the end-to-end publishing workflow.
tags:
  - paperclip
  - cli
  - skills
  - publishing
  - reference
price: 0
license: "MIT"
model_tier: "any"
---

# paperclip-skills CLI Reference

The `paperclip-skills` CLI is the tool for publishing and managing skills on the Paperclip Skills Marketplace (`paperclipskills.com`). A **skill** is a single `skill.md` file — a markdown document with YAML front-matter — that any Paperclip agent can load to gain new capabilities.

---

## Quick Start

```bash
# 1. Login with your API token (from paperclipskills.com/account)
npx paperclip-skills login

# 2. Validate your skill before uploading
npx paperclip-skills validate skill.md

# 3. Preview how it will look on the marketplace
npx paperclip-skills preview skill.md

# 4. Publish to the registry
npx paperclip-skills publish skill.md
```

---

## skill.md Format

Every skill is a single markdown file with YAML front-matter. The front-matter defines metadata; the markdown body is the instruction set injected into the agent's context.

### Minimal Example

```markdown
---
name: "@your-namespace/my-skill"
version: "1.0.0"
author: "Your Name"
description: "A concise summary of what this skill does and when to use it. Max 500 chars."
tags:
  - productivity
price: 0
license: "MIT"
model_tier: "any"
---

# My Skill

When to invoke this skill: whenever the user asks about X.

## How to Use

Step-by-step instructions for the agent...
```

### Front-Matter Schema

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | **Yes** | Scoped npm-style name. Pattern: `^@[a-z0-9-]+/[a-z0-9-]+$` |
| `version` | string | **Yes** | Semver: `MAJOR.MINOR.PATCH` |
| `author` | string | **Yes** | Display name or GitHub handle. Max 100 chars. |
| `description` | string | **Yes** | Human-readable summary. 10–500 characters. |
| `tags` | string[] | No | Up to 10 lowercase alphanumeric + hyphen tags. |
| `price` | integer | **Yes** | USD cents. `0` = free. `2900` = $29.00. |
| `license` | string | No | `"MIT"`, `"Apache-2.0"`, `"GPL-3.0"`, or `"proprietary"`. Default: `"proprietary"` for paid, `"MIT"` for free. |
| `references` | object[] | No | Other skills this skill depends on. Each entry: `{ url, alias }`. |
| `required_secrets` | string[] | No | Env var names the agent must have set (e.g. `["OPENAI_API_KEY"]`). |
| `model_tier` | string | No | Minimum model: `"any"`, `"haiku"`, `"sonnet"`, `"opus"`. Default: `"any"`. |

### Name Naming Rules

- Must be scoped: `@namespace/skill-name`
- Namespace must be registered and owned by the publisher
- Only lowercase letters, digits, and hyphens in both parts
- No dots, underscores, or uppercase
- Examples: `@paperclip-skills/para-memory-files`, `@acmecorp/jira-integration`

### References

Skills can depend on other skills from the registry:

```yaml
references:
  - url: "https://paperclipskills.com/v1/@paperclip-skills/para-memory-files"
    alias: "memory"
```

- All reference URLs must point to `paperclipskills.com`
- Up to 20 references allowed
- The `alias` field is optional — use it to give the referenced skill a short local name

### required_secrets

If your skill needs API keys or tokens:

```yaml
required_secrets:
  - OPENAI_API_KEY
  - STRIPE_SECRET_KEY
```

- Names must match `^[A-Z][A-Z0-9_]*$`
- The registry surfaces these during install so users know what to configure

### Body Content Rules

- Must start with a top-level `#` heading
- Must have at least some content below the front-matter
- Maximum body size: 100KB
- No hardcoded secrets (the CLI scans for common patterns like `sk-...`, AWS keys, GitHub PATs)

---

## CLI Commands

### `login`

Save your Paperclip API token for publishing.

```bash
npx paperclip-skills login
# Prompts for token interactively (input hidden)

npx paperclip-skills login --token <your-token>
# Non-interactive; fails immediately if token is empty
```

Credentials are stored at `~/.paperclip-skills/config.json`.

**Options:**
- `--token <token>` — API token (prompted if omitted)
- `--registry-url <url>` — Override registry URL (default: `https://paperclipskills.com`)

---

### `validate`

Validate a `skill.md` file locally without uploading.

```bash
npx paperclip-skills validate
# Validates ./skill.md by default

npx paperclip-skills validate path/to/skill.md

npx paperclip-skills validate --quiet
# Only prints errors, no metadata display
```

Exits with code `0` on success, `1` on failure.

**What it checks:**
- Front-matter parses as valid YAML
- All required fields present and correctly typed
- `name` matches `@namespace/skill-name` pattern
- `version` is valid semver
- `description` is 10–500 characters
- `tags` are lowercase alphanumeric/hyphen, max 10
- `price` is a non-negative integer
- `references` point to `paperclipskills.com`
- `required_secrets` names are `UPPER_SNAKE_CASE`
- `model_tier` is one of: `any`, `haiku`, `sonnet`, `opus`
- Body is non-empty and starts with `#`
- No hardcoded secrets

---

### `publish`

Validate and upload a `skill.md` to the registry.

```bash
npx paperclip-skills publish
# Publishes ./skill.md by default

npx paperclip-skills publish path/to/skill.md

npx paperclip-skills publish --dry-run
# Validates and checks references but does NOT upload
```

**What it does:**
1. Reads and validates the skill file (same checks as `validate`)
2. Resolves all `references` URLs (HEAD request to verify they exist)
3. Uploads to the registry using your saved token
4. Prints the install URL and pinned URL on success

**Dry-run mode** (`--dry-run`): runs all local validation and reference checks, reports what _would_ be published, but skips the actual upload. Useful for CI.

---

### `preview`

Show how a `skill.md` will appear on the marketplace listing.

```bash
npx paperclip-skills preview
# Previews ./skill.md by default

npx paperclip-skills preview path/to/skill.md
```

Renders a terminal preview of the marketplace card: name, version, author, price, license, model tier, tags, required secrets, description, and the first 500 characters of the body.

---

### `versions`

List all published versions of a skill.

```bash
npx paperclip-skills versions @your-namespace/my-skill
```

Displays a table with version numbers, publish timestamps, and content hashes.

---

## End-to-End Publishing Workflow

### 1. Get an API token

Visit `https://paperclipskills.com/account`, connect your wallet, and copy your API token.

### 2. Login

```bash
npx paperclip-skills login --token <your-token>
```

### 3. Write your skill

Create a `skill.md` file with valid front-matter and a helpful instruction body.

### 4. Validate locally

```bash
npx paperclip-skills validate skill.md
```

Fix any errors before proceeding.

### 5. Preview on marketplace

```bash
npx paperclip-skills preview skill.md
```

### 6. Publish (dry-run first)

```bash
npx paperclip-skills publish --dry-run skill.md
npx paperclip-skills publish skill.md
```

On success the CLI prints:
```
✓ Skill published successfully.
  URL:        https://paperclipskills.com/v1/@your-namespace/my-skill
  Pinned URL: https://paperclipskills.com/v1/@your-namespace/my-skill@1.0.0
```

### 7. Install in an agent

In the agent's `AGENTS.md` or system prompt, reference the skill URL. The agent loads it at runtime.

---

## Environment Variables

| Variable | Description |
|----------|-------------|
| `PAPERCLIP_REGISTRY_URL` | Override the registry URL for all CLI commands. |

---

## Config File

Credentials are saved at `~/.paperclip-skills/config.json`:

```json
{
  "token": "your-api-token",
  "registryUrl": "https://paperclipskills.com",
  "savedAt": "2026-01-01T00:00:00.000Z"
}
```

---

## Exit Codes

| Code | Meaning |
|------|---------|
| `0` | Success |
| `1` | Validation error, publish failure, or missing file |

---

## Common Mistakes

| Problem | Fix |
|---------|-----|
| `name must be scoped @namespace/skill-name` | Use `@yourname/skill-name` format |
| `version must be semver MAJOR.MINOR.PATCH` | Use `"1.0.0"` not `"v1.0.0"` or `"1.0"` |
| `description` too short or too long | Must be 10–500 characters |
| `price` is not an integer | Use `price: 2900` for $29.00, not `29.00` |
| Reference URL rejected | References must be on `paperclipskills.com` |
| Body has no heading | Start body with `# Skill Title` |
| Publish fails with 401 | Run `npx paperclip-skills login` first |