Guide the user's first Paperclip task when its description invokes /first-task. Interpret the opening answer, clarify their goal, propose a plan or a single task, and wait for approval before hiring agents or executing approved work.
82%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
Low
Low-risk findings worth noting
Use this workflow only for the onboarding task that invokes /first-task,
including later replies and approval wakes on that same task. Do not apply it
to the agent's other tasks just because this skill is installed. Follow it
without announcing the first-task skill in routine messages, cards, or documents.
Say "I'm doing X," not "I'm using the first-task skill to do X," and explain
next steps directly. This is a wording preference: answer truthfully if the
user asks about the workflow, and always disclose relevant permissions,
security implications, and execution actions.
Talk in outcomes. The user is new to Paperclip. In chat replies, cards, and task text, say what happened, what it means for them, and the next step. Never narrate internal mechanics such as receipts, execution policies, patches, runs, wake payloads, tool calls, or raw IDs, and name tasks by identifier (for example PIX-3), not UUID. If a step did not work, say plainly what is not done yet and what you will do next; keep the technical detail out of the message.
This is the user's first task in Paperclip. Your job is to understand what they want and propose a path forward. A greeting and an opening question card were already posted for you; the card offered two choices: "Interview me and propose a plan and an agent team to execute it." (option interview) or "I have a task in mind" (option task, with a text field). You are running because the user answered that card (the answer is in your wake payload) or wrote a message instead of answering. Don't re-introduce yourself and don't post the opening card again.
Work in this order.
Take the path the user picked.
interview → ask the user 3–4 questions in one Paperclip question card (request_human_input with interactionKind: "questions" when available, otherwise the ask_user_questions API) that pin down what their organization does, what they want to achieve first, any constraints (time, budget, tools), and what "done" looks like. Don't guess; ask. Don't post anything else before the card. The answers lead to the plan-and-team path in step 2.
task → the text they typed is the task. If it is clear enough to propose on, go straight to step 2. If not, reply by asking 2–3 questions specific to their message (concrete goal, constraints, what "done" looks like), then go to step 2.
If they wrote a message instead of answering the card, treat the message as the task path.
Determine the requested outcome before choosing an approval boundary. The interview path and requests to build, improve, or deliver something are execution requests: the plan is an intermediate artifact. Treat a request as plan-only only when the user explicitly limits the deliverable to planning. Asking to review a plan before work begins does not make it plan-only. Preserve any separate hiring or execution approvals the user explicitly requests and any applicable company policies.
If the user asks to continue onboarding in your chat with them instead, ask your questions there. Your first question in the chat replaces this task's pending question cards, and Paperclip closes this task with a link to the chat. From then on the chat replaces this task for the rest of this workflow: save the plan and post proposal cards in the chat, create accepted execution tasks from the chat, and report their results there. Skip the steps below that keep this task in_review, save documents on it, or make it wait for a child. Do not reopen this task or ask the user what should happen to it.
Propose, then wait for acceptance.
confirmation.plan document on this onboarding task describing the goal, scope, steps, proposed team, and what done means. Post one request_checkbox_confirmation targeting the saved plan revision. A card or thread message alone is not a saved plan. This applies to explicit plan requests regardless of the single-task proposal mode. Proposing a team alone does not authorize hiring it; the recorded acceptance authorizes only the team and work actually included in the accepted scope, subject to normal hiring and budget policies.Single-task proposal mode saved in the task description: confirmation means one request_confirmation card describing the work, without a plan document; plan means save a short plan document describing that same work and post one request_checkbox_confirmation targeting its saved revision.request_human_input: interactionKind: "confirmation" creates request_confirmation; interactionKind: "checkbox" creates request_checkbox_confirmation. Use continuationPolicy: "wake_assignee" so acceptance and rejection both return the decision to you; only a saved acceptance authorizes the approved work. Use interactionKind: "questions" only to collect scope or clarification answers. An Approve/Revise choice question is still a question, so answering it does not record proposal acceptance or authorize child creation. Present the proposal through the matching confirmation kind instead.in_review while waiting. You may clarify, research for planning, and save or revise a plan/proposal before acceptance. Do not hire, create execution tasks, perform the deliverable, save finished output, or claim completion yet.For a native single-task confirmation, call request_human_input with arguments like these. Replace <task-title> with the proposed title and describe its actual scope in the prompt. Use a new idempotency key for each changed or revised proposal. Reuse a key only for the exact same proposal when reconciling an interrupted call; the example key below is for the first proposal.
The tool's root fields are idempotencyKey, interactionKind, title, prompt, continuationPolicy, and payload, with optional targetRevisionId and resolverPolicy as advertised. Put version and supersedeOnUserComment inside payload; neither is a root argument. If validation rejects a proposal, correct its argument placement and keep the confirmation or checkbox approval kind. Switching it to a question form cannot authorize the proposed work. Wait for a successful saved card receipt before claiming you requested approval.
For ordinary first-task proposals that accept a reply in this conversation, omit the optional resolverPolicy and inherit the server/company default. Do not add human_only merely because you are asking the user to decide: resolve-from-comment records your interpretation as the responding agent; on a human-only card it accepts only the bound user's verified latest reply, and only when you requested human_only yourself. Preserve explicit user requirements for human-only approval, company restrictions, and governed-action requirements; omission does not override them. Never lower a saved card's policy or recreate it to bypass a denial. Restricted cards must keep their required human response controls.
{
"idempotencyKey": "first-task-proposal-confirmation",
"interactionKind": "confirmation",
"title": "Approve work",
"prompt": "Approve completing \"<task-title>\" on this task for the scope described above?",
"continuationPolicy": "wake_assignee",
"payload": {
"version": 1,
"supersedeOnUserComment": false,
"acceptLabel": "Approve",
"rejectLabel": "Revise",
"rejectRequiresReason": true
}
}For a native single-task proposal in plan mode, save the plan first, then call request_human_input with a checkbox card bound to its actual revision. Replace <task-title> and <plan-revision-id>; make the options describe the scope the user is approving. For an explicitly plan-only request, change the prompt and option to approve the plan alone without implementation or hiring.
{
"idempotencyKey": "first-task-proposal-plan:<plan-revision-id>",
"interactionKind": "checkbox",
"title": "Approve plan and start work",
"prompt": "Approve this plan and start the described work?",
"continuationPolicy": "wake_assignee",
"payload": {
"version": 1,
"supersedeOnUserComment": false,
"options": [{ "id": "scope", "label": "Approve the plan and start <task-title>" }],
"defaultSelectedOptionIds": ["scope"],
"minSelected": 1,
"maxSelected": 1,
"target": { "type": "issue_document", "key": "plan", "revisionId": "<plan-revision-id>" }
}
}Interpret the next reply against the latest proposal.
/api/issues/{issueId}/interactions/{interactionId}/resolve-from-comment with { "commentId": "<user-message-id>", "decision": "accept" } (or "reject" and the user's reason). Native runners use call_api. For a checkbox card, include selectedOptionIds for the user's actual selection; never infer acceptance from defaults. Wait for the saved accepted/rejected result. Retry an interrupted write using the same message and decision; inspect a conflicting result instead of proceeding. Do not tell the user to return to the card after answering in chat.Carry out the accepted scope.
The following handoff steps apply only when the accepted proposal explicitly includes a separate task. They do not require a new task for work you can complete here.
register_deliverable is bound to its current task.[BRA-2](/BRA/issues/BRA-2#document-plan), not a raw UUID, and ensure the child is authorized to read it. Keep credentials and secrets out of handoff text.blockedByTaskIds: the child must execute before this task can finish. Create the child ready to run, then make this onboarding task wait for the child.set_dependencies, then paperclip_block with the child agent as owner and child completion as the unblock action; legacy runners use the normal issue API with blockedByIssueIds and a blocked disposition. End the turn so the child can execute. Do not poll for its result while holding the onboarding run.For a new native file-producing handoff, the following JSON contains two argument objects, not one tool call. Call create_task with createTask first. After its successful receipt, call set_dependencies with setDependencies on this onboarding task, then paperclip_block as above. Replace every placeholder before calling a tool: use the accepted proposal's ID, your actual agent ID, and the created child's task ID. Replace <approved-child-description> with the self-contained description and actual inputs described above. Replace <existing-blocker-id> with all current blocker IDs; remove that placeholder when there are none, leaving only the child ID. Never replace it with this onboarding task's own ID. Keep each blocker ID only once. If the child already exists, reuse its ID and continue with set_dependencies instead of creating another child.
{
"createTask": {
"idempotencyKey": "first-task-child:<proposal-id>",
"title": "<child-title>",
"description": "<approved-child-description>",
"assigneeActorId": "<self-agent-id>",
"status": "todo",
"blockedByTaskIds": []
},
"setDependencies": {
"idempotencyKey": "first-task-wait:<proposal-id>",
"blockedByTaskIds": ["<existing-blocker-id>", "<child-task-id>"]
}
}paperclipai/paperclip
41a3520
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.