Agent skill

paperclip

Interact with the Paperclip control plane API to manage tasks, coordinate agents, track goals, and run your AI-powered company. Use when working with Paperclip issues, agents, projects, or goals.

View SKILL.md on GitHub Repository
Stars 2
Forks 0

Install this agent skill to your Project

npx add-skill https://github.com/ckorhonen/claude-skills/tree/main/skills/paperclip

SKILL.md

Paperclip

Overview

Manage your Paperclip agent company from Claude Code. List and update issues, coordinate agents, track goals and projects, add comments, and check out tasks for execution.

When to Use

  • Listing, creating, or updating issues/tasks
  • Checking out issues for agent execution
  • Viewing agent status and assignments
  • Tracking company goals and project progress
  • Adding comments to issues
  • Getting a quick status overview of the company

Prerequisites

  • paperclip CLI installed (see Install below)
  • Environment variables configured

Install

Via npm (recommended)

bash
npm install -g paperclip-cli

Via npx (no install)

bash
npx paperclip-cli issues

Via skills.sh

bash
curl -sL https://skills.sh/paperclip | bash

From source

bash
git clone https://github.com/ckorhonen/paperclip-cli.git
cd paperclip-cli
bun install && bun run build

Configuration

Set these environment variables:

bash
export PAPERCLIP_API_KEY="your-api-key"
export PAPERCLIP_COMPANY_ID="your-company-id"
export PAPERCLIP_API_URL="http://127.0.0.1:3100"  # optional, defaults to localhost

Add to ~/.zshrc or ~/.bashrc for persistence.

CLI Commands

List issues

bash
paperclip issues                                  # All issues
paperclip issues --status todo                    # Filter: todo, in_progress, done
paperclip issues --assignee <agent-id-prefix>     # Filter by assignee
paperclip issues --priority critical              # Filter by priority
paperclip issues --project <project-id-prefix>    # Filter by project
paperclip issues --limit 10                       # Limit results

Output (token-efficient text by default):

SOU-137 [in_progress] critical 66af72cc CLI and Skills
SOU-2   [in_progress] medium  66af72cc Grow iOS App

Get issue detail

bash
paperclip issue SOU-137

Output:

SOU-137: CLI and Skills
Status: in_progress | Priority: critical
Assignee: 66af72cc-939b-43d7-b38e-3dc9ce75ec9b
Created: 2026-03-12T10:06:13.281Z | Updated: 2026-03-18T20:40:07.128Z

Build a CLI tool that calls the API...

Create issue

bash
paperclip create --title "Fix login bug" --priority high --description "Users can't log in"
paperclip create --title "New feature" --project <project-id>

Update issue

bash
paperclip update SOU-137 --status done
paperclip update SOU-137 --priority high --title "New title"

Comments

bash
paperclip comments SOU-137                        # List comments
paperclip comment SOU-137 --body "Working on it"  # Add comment
paperclip comment SOU-137 --body "Done" --agent <agent-id>

Checkout & Release

bash
paperclip checkout SOU-137 --agent <agent-id>      # Check out issue
paperclip release SOU-137                           # Release execution lock
paperclip release SOU-137 --status done             # Release and set status

Status Dashboard

bash
paperclip status                                    # Company overview

List agents

bash
paperclip agents

Output:

CTO [running] cto — Chief Technology Officer (reports to 8bcd18c1)
Engineer (Claude) [running] engineer — Software Engineer (reports to 1a06cb09)
CEO [running] ceo — CEO

List goals

bash
paperclip goals

List projects

bash
paperclip projects

JSON output

All commands support --json for raw JSON:

bash
paperclip issues --json | jq '.[] | select(.status == "todo")'
paperclip agents --json | jq '.[].name'

API Direct Access

If the CLI is not available, use curl directly:

bash
# Base URL
API="http://127.0.0.1:3100"

# List issues
curl -s -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  "$API/api/companies/$PAPERCLIP_COMPANY_ID/issues"

# Get comments
curl -s -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  "$API/api/issues/<issue-id>/comments"

# Add comment
curl -s -X POST -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"body": "Comment text", "agentId": "<agent-id>"}' \
  "$API/api/issues/<issue-id>/comments"

# Update issue (note: NOT company-scoped)
curl -s -X PATCH -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "done"}' \
  "$API/api/issues/<issue-id>"

# Checkout issue
curl -s -X POST -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agentId": "<agent-id>", "expectedStatuses": ["todo", "in_progress"]}' \
  "$API/api/issues/<issue-id>/checkout"

API Endpoints Reference

Method Path Description
GET /api/companies/{companyId}/issues List issues
POST /api/companies/{companyId}/issues Create issue
PATCH /api/issues/{issueId} Update issue
GET /api/issues/{issueId}/comments List comments
POST /api/issues/{issueId}/comments Add comment
POST /api/issues/{issueId}/checkout Checkout issue
GET /api/companies/{companyId}/agents List agents
GET /api/companies/{companyId}/goals List goals
GET /api/companies/{companyId}/projects List projects

Important: PATCH and comment endpoints use /api/issues/{issueId} (NOT company-scoped). The Content-Type: application/json header is required on all requests.

Troubleshooting

"PAPERCLIP_API_KEY is required"

Ensure the env var is set. Note: shell $VAR expansion can appear empty even when set. Use:

bash
TOKEN=$(env | grep '^PAPERCLIP_API_KEY=' | cut -d= -f2-)

"API 500" on status filter

The API status filter parameter causes server errors. The CLI applies filters client-side.

Checkout fails with execution lock

If an issue has a stale executionRunId, checkout will fail. Wait for the lock to expire or be cleared externally.

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

ckorhonen/claude-skills

subway-info

Get real-time NYC transit information — subway, bus, ferry, and commuter rail — via the subway-info CLI or REST API at subwayinfo.nyc. Use when asked about NYC subway status, train times, bus routes, ferry schedules, transit delays, MTA service alerts, or "what's the next train to X".

2 0
Explore
ckorhonen/claude-skills

codex-advisor

Get a second opinion from OpenAI Codex CLI for plan reviews, code reviews, architecture decisions, and hard problems. Use when you need external validation, want to compare approaches, or are stuck on a difficult problem.

2 0
Explore
ckorhonen/claude-skills

brainstorming

Explore user intent, requirements and design before implementation through structured dialogue and design proposals. Use when asked to: create features, build components, add functionality, modify behavior, plan projects, or when user says 'help me design X', 'what should we build', 'let's brainstorm', or starts describing a new feature without a design.

2 0
Explore
ckorhonen/claude-skills

direct-mail-strategist

Expert direct mail marketing strategist for writing compelling copy, designing high-converting mail pieces, and developing measurement strategies. Use when planning direct mail campaigns, writing mailer copy, designing postcards/letters, or measuring campaign effectiveness with incremental lift analysis.

2 0
Explore
ckorhonen/claude-skills

gemini-image-generator

Generate images using Google's Gemini API. Use when creating images from text prompts, editing existing images, or combining reference images for AI-generated visual content.

2 0
Explore
ckorhonen/claude-skills

ui-design

Opinionated constraints for building better interfaces with agents. Use when building UI components, implementing animations, designing layouts, reviewing frontend accessibility, or working with Tailwind CSS, motion/react, or accessible primitives like Radix/Base UI.

2 0
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results