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 |
references/issue-documents.md
View on GitHub# Issue documents through the API
Use this procedure for requested Paperclip task documents in API-based runtimes.
Honor a destination explicitly chosen by the requester. Native Runner runtimes
use their document tool and its contract. Downloadable files follow
[artifacts.md](artifacts.md).
## Create a document
Use the injected `PAPERCLIP_API_URL` and bearer `PAPERCLIP_API_KEY`. Include
`X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID` on the write and send JSON with
`Content-Type: application/json`.
Choose a descriptive document key such as `report`; keys use lowercase letters,
numbers, underscores, or hyphens and are at most 64 characters. Plans use `plan`.
```text
PUT /api/issues/{issueId}/documents/{key}
```
```json
{
"title": "Task report",
"format": "markdown",
"body": "# Task report\n\nThe requested findings.",
"baseRevisionId": null
}
```
A successful write returns HTTP `201` for creation or `200` for an update,
with the saved document JSON. Check its `key`, `body`, and `latestRevisionId`
before claiming delivery. This receipt is sufficient; another GET is unnecessary
when it confirms the intended content and a saved revision.
Construct a clickable Markdown link from the current issue and successful write
receipt, then add it to the completion comment or response:
```javascript
const issuePath = issue.identifier
? `/${issue.identifier.split("-")[0]}/issues/${issue.identifier}`
: `/issues/${issue.id}`;
const documentUrl = `${issuePath}#document-${saved.key}`;
const comment = `Saved [Task report](${documentUrl}).`;
```
Use the returned key: a locked document can redirect an agent's write to a new
document. Unnumbered issues use their ID; the board resolves their company.
## Update or resolve an unclear write
For an existing document, first `GET /api/issues/{issueId}/documents/{key}`
and read its body and `latestRevisionId`. Send the updated body with
`baseRevisionId` set to that revision. On `409`, fetch the latest document and
reconcile changes before retrying; preserve the skill's bounded-write retry rule.
If a write's status or receipt is unclear, GET the document to check the saved
content and revision before retrying. If delivery cannot be confirmed, report
that limitation instead of claiming the requested document was saved.
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 |