paperclipai/paperclip / skills/paperclip
paperclip
VerifiedUse for Paperclip-managed tasks and heartbeats: reading task context, delivering task documents or files, updating completion or blockers, coordinating or delegating work, and following company governance. Includes control plane API operations for assignments, comments, approvals, and routines.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 81.5 KB |
| references/api-reference.md | markdown | 106.1 KB |
| references/artifacts.md | markdown | 7.6 KB |
| references/cases.md | markdown | 25.3 KB |
| references/company-skills.md | markdown | 10.0 KB |
| references/issue-documents.md | markdown | 2.2 KB |
| references/issue-workspaces.md | markdown | 5.0 KB |
| references/routines.md | markdown | 9.5 KB |
| references/run-diagnostics.md | markdown | 1.9 KB |
| references/workflows.md | markdown | 4.8 KB |
| scripts/paperclip-issue-update.shexecutable | script | 4.4 KB |
| scripts/paperclip-upload-artifact.shexecutable | script | 17.8 KB |
| scripts/submit-agent-commentary.mjsexecutable | script | 2.4 KB |
scripts/paperclip-upload-artifact.sh
View on GitHub#!/usr/bin/env bash
set -euo pipefail
usage() {
cat <<'EOF'
Usage:
paperclip-upload-artifact.sh FILE [options]
Uploads a generated file from the current workspace to the current Paperclip
issue, then creates an attachment-backed artifact work product by default.
Required environment for live uploads:
PAPERCLIP_API_URL, PAPERCLIP_API_KEY, PAPERCLIP_COMPANY_ID, PAPERCLIP_TASK_ID, PAPERCLIP_RUN_ID
Options:
--issue-id ID Issue id to attach to (default: PAPERCLIP_TASK_ID)
--company-id ID Company id (default: PAPERCLIP_COMPANY_ID)
--title TEXT Work product title (default: file basename)
--summary TEXT Work product summary
--content-type TYPE Override detected upload content type
--status STATUS Work product status (default: ready_for_review)
--chat-comment TEXT Bind this file to an explicit external-chat response
--retry-unknown-upload Retry after an unresolved transport failure (duplicate risk)
--no-work-product Only upload the issue attachment
--no-primary Do not mark the artifact work product primary for its type
--output FORMAT markdown or json (default: markdown)
--dry-run Print resolved upload settings without calling the API
--help, -h Show this help
Examples:
bash scripts/paperclip-upload-artifact.sh dist/demo.mp4 \
--title "Demo video render" \
--summary "MP4 render for board review"
bash scripts/paperclip-upload-artifact.sh out/walkthrough.webm \
--title "Walkthrough video" \
--content-type video/webm
bash scripts/paperclip-upload-artifact.sh out/result.png \
--title "Generated image" \
--chat-comment "Here is the requested image."
EOF
}
require_command() {
if ! command -v "$1" >/dev/null 2>&1; then
printf 'Missing required command: %s\n' "$1" >&2
exit 1
fi
}
json_bool() {
if [[ "${1:-0}" == "1" ]]; then
printf 'true'
else
printf 'false'
fi
}
detect_content_type() {
local path="$1"
local lower
lower="$(printf '%s' "$path" | tr '[:upper:]' '[:lower:]')"
case "$lower" in
*.mp4|*.m4v) printf 'video/mp4' ;;
*.webm) printf 'video/webm' ;;
*.mov|*.qt) printf 'video/quicktime' ;;
*.png) printf 'image/png' ;;
*.jpg|*.jpeg) printf 'image/jpeg' ;;
*.gif) printf 'image/gif' ;;
*.webp) printf 'image/webp' ;;
*.svg) printf 'image/svg+xml' ;;
*.pdf) printf 'application/pdf' ;;
*.txt|*.log) printf 'text/plain' ;;
*.md|*.markdown) printf 'text/markdown' ;;
*.json) printf 'application/json' ;;
*.csv) printf 'text/csv' ;;
*.html|*.htm) printf 'text/html' ;;
*.zip) printf 'application/zip' ;;
*)
if command -v file >/dev/null 2>&1; then
file --brief --mime-type "$path"
else
printf 'application/octet-stream'
fi
;;
esac
}
sha256_file() {
local path="$1"
if command -v sha256sum >/dev/null 2>&1; then
sha256sum -- "$path" | awk '{print tolower($1)}'
elif command -v shasum >/dev/null 2>&1; then
shasum -a 256 -- "$path" | awk '{print tolower($1)}'
else
printf 'Missing required command: sha256sum or shasum\n' >&2
exit 1
fi
}
sha256_text() {
local value="$1"
if command -v sha256sum >/dev/null 2>&1; then
printf '%s' "$value" | sha256sum | awk '{print tolower($1)}'
elif command -v shasum >/dev/null 2>&1; then
printf '%s' "$value" | shasum -a 256 | awk '{print tolower($1)}'
else
printf 'Missing required command: sha256sum or shasum\n' >&2
exit 1
fi
}
helper_state_directory() {
printf '%s' "${PAPERCLIP_HELPER_STATE_DIR:-${PAPERCLIP_WORKSPACE_CWD:-$PWD}/.paperclip/artifact-helper}"
}
helper_response_file() {
local directory
directory="$(helper_state_directory)"
# TMPDIR can name a controller-owned directory outside a CLI sandbox.
(umask 077; mkdir -p "$directory" && mktemp "$directory/response.XXXXXX")
}
request_json() {
local method="$1"
local url="$2"
local body="${3:-}"
local response_file
local status_code
response_file="$(helper_response_file)"
if [[ -n "$body" ]]; then
status_code="$(
curl -sS -X "$method" -w '%{http_code}' -o "$response_file" \
"$url" \
-H "Authorization: Bearer $PAPERCLIP_API_KEY" \
-H "X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID" \
-H 'Content-Type: application/json' \
--data-binary "$body"
)"
else
status_code="$(
curl -sS -X "$method" -w '%{http_code}' -o "$response_file" \
"$url" \
-H "Authorization: Bearer $PAPERCLIP_API_KEY" \
-H "X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID"
)"
fi
if [[ "$status_code" -lt 200 || "$status_code" -ge 300 ]]; then
printf 'Request failed (%s): %s\n' "$status_code" "$url" >&2
cat "$response_file" >&2
printf '\n' >&2
rm -f "$response_file"
exit 1
fi
cat "$response_file"
rm -f "$response_file"
}
upload_file() {
local url="$1"
local path="$2"
local content_type="$3"
local escaped_path
local response_file
local status_code
local curl_status=0
local indeterminate=0
escaped_path="${path//\\/\\\\}"
escaped_path="${escaped_path//\"/\\\"}"
response_file="$(helper_response_file)"
status_code="$(
curl -sS -X POST -w '%{http_code}' -o "$response_file" \
"$url" \
-H "Authorization: Bearer $PAPERCLIP_API_KEY" \
-H "X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID" \
-F "file=@\"${escaped_path}\";type=${content_type}"
)" || curl_status=$?
if [[ "$curl_status" -ne 0 ]]; then
rm -f "$response_file"
return 75
fi
if [[ "$status_code" -lt 200 || "$status_code" -ge 300 ]]; then
printf 'Upload failed (%s): %s\n' "$status_code" "$url" >&2
cat "$response_file" >&2
printf '\n' >&2
# The bridge uses a structured 409 outcome after a possibly committed
# mutation. Keep the marker so the next invocation reconciles by listing.
if [[ "$status_code" == "409" ]] && jq -e '.outcome == "indeterminate"' "$response_file" >/dev/null 2>&1; then
indeterminate=1
fi
rm -f "$response_file"
if [[ "$status_code" == "408" || "$status_code" -ge 500 || "$indeterminate" == "1" ]]; then
return 75
fi
return 1
fi
cat "$response_file"
rm -f "$response_file"
}
operation_lock_path=""
operation_lock_owner=""
operation_lock_held=0
operation_state_root=""
process_start_identity() {
local pid="$1"
ps -p "$pid" -o lstart= 2>/dev/null | tr -s '[:space:]' ' ' | sed 's/^ //;s/ $//'
}
release_operation_lock() {
if [[ "$operation_lock_held" == "1" && -n "$operation_lock_path" ]]; then
local current_owner=""
current_owner="$(readlink "$operation_lock_path" 2>/dev/null || true)"
if [[ "$current_owner" == "$operation_lock_owner" ]]; then
rm -f "$operation_lock_path"
fi
operation_lock_held=0
fi
}
acquire_operation_lock() {
local operation_key="$1"
local attempts=0
umask 077
operation_state_root="$(helper_state_directory)"
mkdir -p "$operation_state_root"
operation_lock_path="$operation_state_root/$operation_key.lock"
operation_lock_owner="$$|$(process_start_identity "$$" || true)"
while ! ln -s "$operation_lock_owner" "$operation_lock_path" 2>/dev/null; do
local owner_pid=""
local owner_start=""
local current_lock_owner=""
current_lock_owner="$(readlink "$operation_lock_path" 2>/dev/null || true)"
IFS='|' read -r owner_pid owner_start <<<"$current_lock_owner"
if [[ "$owner_pid" =~ ^[0-9]+$ ]]; then
local current_owner_start=""
current_owner_start="$(process_start_identity "$owner_pid" || true)"
if ! kill -0 "$owner_pid" 2>/dev/null ||
[[ -n "$owner_start" && -n "$current_owner_start" && "$owner_start" != "$current_owner_start" ]]; then
# Serialize stale-lock reclamation separately. Without this guard, two
# contenders can both observe the old owner and the slower one can
# delete the faster contender's newly acquired live lock.
local reclaim_lock_path="$operation_lock_path.reclaim"
if mkdir "$reclaim_lock_path" 2>/dev/null; then
local guarded_owner=""
guarded_owner="$(readlink "$operation_lock_path" 2>/dev/null || true)"
if [[ "$guarded_owner" == "$current_lock_owner" ]]; then
rm -f "$operation_lock_path"
fi
rmdir "$reclaim_lock_path" 2>/dev/null || true
continue
fi
fi
fi
attempts=$((attempts + 1))
if [[ "$attempts" -ge 400 ]]; then
printf 'Another matching artifact upload is still in progress; retry after it finishes.\n' >&2
exit 1
fi
sleep 0.05
done
operation_lock_held=1
}
file_path=""
issue_id="${PAPERCLIP_TASK_ID:-}"
company_id="${PAPERCLIP_COMPANY_ID:-}"
title=""
summary=""
content_type=""
status="ready_for_review"
chat_comment=""
create_work_product=1
is_primary=1
output_format="markdown"
dry_run=0
retry_unknown_upload=0
while [[ $# -gt 0 ]]; do
case "$1" in
--issue-id)
issue_id="${2:-}"
shift 2
;;
--company-id)
company_id="${2:-}"
shift 2
;;
--title)
title="${2:-}"
shift 2
;;
--summary)
summary="${2:-}"
shift 2
;;
--content-type)
content_type="${2:-}"
shift 2
;;
--status)
status="${2:-}"
shift 2
;;
--chat-comment)
chat_comment="${2:-}"
shift 2
;;
--no-work-product)
create_work_product=0
shift
;;
--retry-unknown-upload)
retry_unknown_upload=1
shift
;;
--no-primary)
is_primary=0
shift
;;
--output)
output_format="${2:-}"
shift 2
;;
--dry-run)
dry_run=1
shift
;;
--help|-h)
usage
exit 0
;;
--*)
printf 'Unknown argument: %s\n' "$1" >&2
usage >&2
exit 1
;;
*)
if [[ -n "$file_path" ]]; then
printf 'Unexpected positional argument: %s\n' "$1" >&2
usage >&2
exit 1
fi
file_path="$1"
shift
;;
esac
done
if [[ -z "$file_path" ]]; then
printf 'Missing file path.\n' >&2
usage >&2
exit 1
fi
if [[ ! -f "$file_path" ]]; then
printf 'Artifact file does not exist: %s\n' "$file_path" >&2
exit 1
fi
if [[ "$output_format" != "markdown" && "$output_format" != "json" ]]; then
printf 'Unsupported output format: %s\n' "$output_format" >&2
exit 1
fi
if [[ -n "$chat_comment" && "$create_work_product" != "1" ]]; then
printf '%s\n' '--chat-comment requires the attachment-backed work product created by this helper.' >&2
exit 1
fi
require_command curl
require_command jq
if [[ -z "$title" ]]; then
title="$(basename "$file_path")"
fi
if [[ -z "$content_type" ]]; then
content_type="$(detect_content_type "$file_path")"
fi
if [[ "$dry_run" == "1" ]]; then
create_work_product_json="$(json_bool "$create_work_product")"
is_primary_json="$(json_bool "$is_primary")"
jq -n \
--arg file "$file_path" \
--arg issueId "$issue_id" \
--arg companyId "$company_id" \
--arg title "$title" \
--arg summary "$summary" \
--arg contentType "$content_type" \
--arg status "$status" \
--arg chatComment "$chat_comment" \
--argjson createWorkProduct "$create_work_product_json" \
--argjson isPrimary "$is_primary_json" \
'{file: $file, issueId: $issueId, companyId: $companyId, title: $title, summary: $summary, contentType: $contentType, status: $status, chatComment: (if $chatComment == "" then null else $chatComment end), createWorkProduct: $createWorkProduct, isPrimary: $isPrimary}'
exit 0
fi
if [[ -z "${PAPERCLIP_API_URL:-}" || -z "${PAPERCLIP_API_KEY:-}" || -z "${PAPERCLIP_RUN_ID:-}" ]]; then
printf 'Missing PAPERCLIP_API_URL, PAPERCLIP_API_KEY, or PAPERCLIP_RUN_ID.\n' >&2
exit 1
fi
if [[ -z "$issue_id" || -z "$company_id" ]]; then
printf 'Missing issue or company id. Pass --issue-id/--company-id or set PAPERCLIP_TASK_ID/PAPERCLIP_COMPANY_ID.\n' >&2
exit 1
fi
api_root="${PAPERCLIP_API_URL%/}"
case "$api_root" in
*/api) api_base="$api_root" ;;
*) api_base="$api_root/api" ;;
esac
file_sha256="$(sha256_file "$file_path")"
original_filename="$(basename "$file_path")"
operation_key="$(
sha256_text "$api_base|$company_id|$issue_id|$PAPERCLIP_RUN_ID|$original_filename|$file_sha256|$content_type"
)"
acquire_operation_lock "$operation_key"
trap release_operation_lock EXIT
attachment=""
reused_attachment=0
unknown_upload_marker="$operation_state_root/$operation_key.uncertain"
lookup_attempts=1
if [[ -f "$unknown_upload_marker" && "$retry_unknown_upload" != "1" ]]; then
lookup_attempts=20
fi
for ((lookup_attempt = 1; lookup_attempt <= lookup_attempts; lookup_attempt++)); do
existing_attachments="$(request_json GET "$api_base/issues/$issue_id/attachments")"
attachment="$(
jq -nc \
--argjson attachments "$existing_attachments" \
--arg runId "$PAPERCLIP_RUN_ID" \
--arg sha256 "$file_sha256" \
--arg originalFilename "$original_filename" \
--arg contentType "$content_type" \
'first(
$attachments[]
| select(
.originatingRunId == $runId
and ((.sha256 // "") | ascii_downcase) == ($sha256 | ascii_downcase)
and (.originalFilename // "") == $originalFilename
and ((.contentType // "") | ascii_downcase) == ($contentType | ascii_downcase)
)
) // empty'
)"
if [[ -n "$attachment" ]]; then
reused_attachment=1
rm -f "$unknown_upload_marker"
break
fi
if [[ "$lookup_attempt" -lt "$lookup_attempts" ]]; then
sleep 0.25
fi
done
if [[ -z "$attachment" && -f "$unknown_upload_marker" && "$retry_unknown_upload" != "1" ]]; then
printf '%s\n' 'A previous matching upload ended without a definitive response, and Paperclip has not exposed its durable attachment yet.' >&2
printf '%s\n' 'Retry this command later. If the upload definitely did not commit, pass --retry-unknown-upload to accept the duplicate-file risk.' >&2
exit 1
fi
if [[ -z "$attachment" ]]; then
rm -f "$unknown_upload_marker"
: >"$unknown_upload_marker"
upload_status=0
attachment="$(
upload_file \
"$api_base/companies/$company_id/issues/$issue_id/attachments" \
"$file_path" \
"$content_type"
)" || upload_status=$?
if [[ "$upload_status" -ne 0 ]]; then
if [[ "$upload_status" -ne 75 ]]; then
rm -f "$unknown_upload_marker"
fi
exit 1
fi
fi
attachment_id="$(jq -r '.id // empty' <<<"$attachment")"
content_path="$(jq -r '.contentPath // empty' <<<"$attachment")"
download_path="$(jq -r '.downloadPath // (if .contentPath then (.contentPath + "?download=1") else "" end)' <<<"$attachment")"
if [[ -z "$attachment_id" || -z "$content_path" || -z "$download_path" ]]; then
printf 'Upload response did not include attachment path metadata.\n' >&2
printf '%s\n' "$attachment" >&2
exit 1
fi
rm -f "$unknown_upload_marker"
work_product="null"
if [[ "$create_work_product" == "1" ]]; then
is_primary_json="$(json_bool "$is_primary")"
byte_size="$(jq -r '.byteSize // 0' <<<"$attachment")"
open_path="$(jq -r '.openPath // .contentPath // empty' <<<"$attachment")"
original_filename="$(jq -r '.originalFilename // empty' <<<"$attachment")"
work_product_payload="$(
jq -nc \
--arg title "$title" \
--arg summary "$summary" \
--arg status "$status" \
--arg runId "$PAPERCLIP_RUN_ID" \
--arg attachmentId "$attachment_id" \
--arg contentType "$content_type" \
--argjson byteSize "$byte_size" \
--arg contentPath "$content_path" \
--arg openPath "$open_path" \
--arg downloadPath "$download_path" \
--arg originalFilename "$original_filename" \
--argjson isPrimary "$is_primary_json" \
'{
type: "artifact",
provider: "paperclip",
title: $title,
status: $status,
reviewState: "none",
isPrimary: $isPrimary,
healthStatus: "unknown",
summary: (if $summary == "" then null else $summary end),
createdByRunId: $runId,
metadata: {
attachmentId: $attachmentId,
contentType: $contentType,
byteSize: $byteSize,
contentPath: $contentPath,
openPath: $openPath,
downloadPath: $downloadPath,
originalFilename: (if $originalFilename == "" then null else $originalFilename end)
}
}'
)"
work_product="$(
request_json \
POST \
"$api_base/issues/$issue_id/work-products" \
"$work_product_payload"
)"
fi
chat_response="null"
if [[ -n "$chat_comment" ]]; then
chat_comment_payload="$(
jq -nc \
--arg body "$chat_comment" \
--arg attachmentId "$attachment_id" \
'{body: $body, attachmentIds: [$attachmentId]}'
)"
chat_response="$(
request_json \
POST \
"$api_base/issues/$issue_id/comments" \
"$chat_comment_payload"
)"
chat_comment_id="$(jq -r '.id // empty' <<<"$chat_response")"
if [[ -z "$chat_comment_id" ]]; then
printf 'Chat attachment response did not include a comment id.\n' >&2
exit 1
fi
fi
if [[ "$output_format" == "json" ]]; then
jq -n \
--argjson attachment "$attachment" \
--argjson workProduct "$work_product" \
--argjson chatComment "$chat_response" \
'{attachment: $attachment, workProduct: $workProduct, chatComment: $chatComment}'
exit 0
fi
work_product_id="$(jq -r '.id // empty' <<<"$work_product")"
if [[ "$reused_attachment" == "1" ]]; then
printf 'Reused matching artifact from this run\n\n'
else
printf 'Uploaded artifact\n\n'
fi
printf -- '- Attachment: [%s](%s)\n' "$title" "$content_path"
printf -- '- Download: [%s](%s)\n' "$title" "$download_path"
printf -- '- Attachment ID: `%s`\n' "$attachment_id"
if [[ -n "$work_product_id" ]]; then
printf -- '- Work product ID: `%s`\n' "$work_product_id"
fi
if [[ -n "$chat_comment" ]]; then
printf -- '- Paperclip comment binding: saved. External publication requires an authorized active chat origin; this helper does not confirm provider delivery.\n'
fi
printf '\nFinal comment snippet:\n\n'
printf -- '- Artifact: [%s](%s)\n' "$title" "$content_path"
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| add-product-e2e-evalpaperclipai/paperclipAdd or extend a Paperclip full-stack runner E2E workflow, fixture, matcher, or report evidence path for local or Daytona execution. | Stars: 115k | Updated | Claude CodeCodex | Verified | Install |
| add-runner-evalpaperclipai/paperclipAdd or extend a Paperclip Runner protocol evaluation definition, roster, assertion, or report fixture with provenance and narrow validation. | Stars: 115k | Updated | Claude CodeCodex | Verified | Install |
| diagnose-why-work-stoppedpaperclipai/paperclipCompatibility entry point for failed, stalled, looping, or over-recovered Paperclip work. Use fix-failed-paperclip-run for the full diagnosis, regression, repair, real verification, and green-PR workflow; honor an explicitly requested diagnosis-only scope. | Stars: 115k | Updated | Claude CodeCodex | Verified | Install |
| fix-failed-paperclip-runpaperclipai/paperclipDiagnose and fix failed, stuck, slow, or incorrectly blocked Paperclip tasks and runs. Use with a task/run URL or failure report to trace the root cause, prove a regression red then green, check second-order effects, verify the real workflow, and deliver a PR with passing checks. | Stars: 115k | Updated | Claude CodeCodex | Verified | Install |