Developer Docs — Paperclip Skills

Getting started

Publisher setup

Before publishing, you need a publisher account and namespace. This takes about 30 seconds.

Connect your wallet

Go to the publisher dashboard and connect your Base wallet via RainbowKit. This creates your account.

Claim your namespace

Choose a unique namespace (e.g., @yourname). This is your publisher identity — all your skills are published under it.

Save your publish credential

After claiming, you receive a publish credential (psk_ns_*). Save it immediately — it is shown once and cannot be retrieved, only rotated.

For paid skills

Your connected wallet is automatically set as the payout address. When someone buys your skill, an 80/20 split contract is deployed on Base — you receive 80% in USDC, the platform receives 20%. Visit your publisher dashboard to distribute earnings.

Go to publisher dashboard

Recommended

Publish via agent

The fastest way to publish is to give your agent this one-liner. It loads the create-skill skill, which teaches the agent the full format, validation rules, and publish flow — your agent handles everything.

paste this to any agent

Use this skill to publish a new skill to the Paperclip marketplace:
https://www.paperclipskills.com/api/v1/skills/@paperclip-skills/create-skill

Works with Claude, GPT-4, Gemini, Codex, Cursor, Copilot — any agent that can load a Paperclip skill URL.

How it works

The agent handles it all

Once loaded, the skill gives your agent everything it needs to publish — no back and forth, no manual steps.

Load the skill

Your agent fetches the create-skill URL and reads the full publishing spec.

Agent formats & validates

It writes the skill.md, fills in required front-matter, and validates before submitting.

Skill is live

Your agent publishes directly to the registry. You get a public URL instantly.

AdvancedPublish without an agent

If you prefer to publish manually without an agent, you can write the skill file yourself and use the CLI to validate and publish.

Skill format

Starter template

A skill is a plain .md file with YAML front-matter followed by the instruction body.

---
name: "@your-namespace/my-skill"
version: "1.0.0"
author: "Your Name"
description: >
  One paragraph describing what your skill does and when
  an agent should invoke it. Max 500 characters.
tags:
  - your-tag
price: 0                            # USD cents; 0 = free, 2900 = $29
license: "MIT"
model_tier: "any"                   # any | haiku | sonnet | opus
type: "skill"                       # "skill" or "agent" (blueprint)
publisher_wallet: "0x..."           # required for paid skills — your Base wallet
# required_secrets:                 # env vars the skill needs
#   - MY_API_KEY
# references:                       # other skills to embed
#   - url: "https://www.paperclipskills.com/api/v1/skills/@ns/skill"
#     alias: "helper"
---

# My Skill

Brief description of what this skill does.

---

## When to Use

Trigger conditions — be specific about when agents
should invoke this skill.

## Steps / Procedure

1. Step one
2. Step two
3. Step three

## Reference

Quick-lookup tables, endpoint lists, config keys.

File structure

The instruction body (after the front-matter) should use clear section headers to guide agent behavior:

## When to UseSpecific trigger conditions — tells agents when to invoke this skill.

## Steps / ProcedureOrdered steps the agent should follow when the skill is active.

## ReferenceQuick-lookup tables, API endpoints, config keys, examples.

Required fields

All front-matter fields must be valid YAML. The name field must use a namespace you own — register one at /publisher.

Field	Required	Description
name	required	@namespace/skill-name — namespace must be registered
version	required	semver: 1.0.0
author	required	Display name (1–100 chars)
description	required	10–500 chars
price	required	USD cents (0 = free, 2900 = $29)
publisher_wallet	paid only	Your Base wallet (0x...). Required when price > 0
type	optional	"skill" (default) or "agent" (blueprint)
tags	optional	Max 10 lowercase tags
license	optional	MIT \| Apache-2.0 \| GPL-3.0 \| proprietary
model_tier	optional	any \| haiku \| sonnet \| opus
required_secrets	optional	SCREAMING_SNAKE_CASE env vars
references	optional	Skill URLs to embed (max 20)

CLI publish

When your skill file is ready, validate and publish with the CLI:

Step 0 — Get your publish credential

First-time publishers: connect your wallet at /publisher to create your publisher account and claim a namespace. Save your publish credential, then log in via the CLI:

npx paperclip-skills login --credential psk_ns_<your-credential>

Your publish credential is saved to ~/.paperclip-skills/config.json and used automatically by all subsequent CLI commands.

Validate (optional)

npx paperclip-skills validate ./skill.md

Publish to the registry

npx paperclip-skills publish ./skill.md

The CLI validates front-matter, resolves any references, and uploads to the registry. You'll receive a public URL at www.paperclipskills.com/api/v1/skills/@your-namespace/skill-name.

For paid skills, buyers pay via the purchase page using any wallet. An 80/20 split contract is deployed automatically. 80% goes to your wallet in USDC on Base, 20% to the platform. Distribution happens automatically after each purchase.

Any agent can publish.