How to use the Paperclip Task Bridge agent skill

What the skill makes the agent do

Agent skills are folders of instructions and helper scripts that an AI agent loads when a task matches their description. This one covers the Hermes-to-Paperclip direction: when a request needs new or updated Paperclip work, the agent can use a helper script to create tasks, add comments, change task status, or list tasks already assigned to it.

Access is limited by a scoped API key with the kind task_bridge. Such a key can create tasks only inside an approved parent task or project, and can comment on or update only tasks it created or was assigned. It cannot use company-wide issue list, search or read surfaces. This skill is separate from Paperclip waking Hermes, which is handled by the hermes_local or hermes_gateway adapter and is not covered here.

Install the skill

Download the ZIP from this page and unzip it. The folder contains two files: SKILL.md and paperclip-task.mjs. Place the folder in one of these locations:

• Personal skills: ~/.claude/skills/ (the skill folder goes inside this directory)
• Project skills: the .claude/skills/ folder inside a specific project
• Claude apps: upload the skill under Settings → Capabilities → Skills

Set up credentials

Configure credentials in your Hermes env or profile secrets, not in prompt text. The skill needs PAPERCLIP_API_URL (your Paperclip base URL, with or without /api) and PAPERCLIP_BRIDGE_API_KEY (an agent API key created with scope kind task_bridge).

Optional variables are PAPERCLIP_API_KEY (a fallback for older profiles, which must still hold a task_bridge key), PAPERCLIP_COMPANY_ID and PAPERCLIP_AGENT_ID (each skips one identity lookup), and PAPERCLIP_RUN_ID (sent on mutating requests when Hermes runs inside a Paperclip heartbeat).

• Never print or paste API keys into chats or logs.
• Do not put a normal claimed agent API key in an internet-facing Hermes runtime, because normal keys can use broad same-company routes.

Create a bridge key

Create the bridge key from a board-authenticated Paperclip API session, and store the returned token once. Use parentIssueId or parentIssueIds to restrict Hermes to child tasks under approved work, or projectId or projectIds to restrict it to a project.

Run the helper and check it works

Run the helper from the skill directory to see its options. The helper reads credentials from environment variables and prints only response summaries.

• Show help: node ./paperclip-task.mjs --help
• List tasks assigned to Hermes: node ./paperclip-task.mjs list-assigned

Commands and examples

create-task defaults to assigning the new task to the authenticated Hermes agent so it is immediately actionable. Add --unassigned to create backlog work instead. Use --assignee-agent-id only when the key has permission to assign work to that agent.

For multiline text, pass a file or stdin rather than a long inline string.

• Create a task: create-task --parent-id with --title and --description
• Comment on an issue: comment --issue PAP-123 --body
• Change status with a note: update-status --issue PAP-123 --status in_review --comment
• Read a long body from a file or stdin with --description-file or --body-file -

Trigger it with natural requests

You do not run the commands yourself in normal use. Ask Hermes in plain language, and the agent uses the skill when the request needs Paperclip work. Good requests name the outcome and, where relevant, the issue. Ask the agent to check current assignments before creating work, since the skill recommends listing assigned tasks first to avoid duplicates.

• "File a follow-up Paperclip task under PAP-100 to check the retry logic."
• "Comment on PAP-123 that the failing request path is identified."
• "Check what Paperclip tasks are assigned to you before starting anything new."
• "Move PAP-123 to in_review with a note that it is ready for review."

Safety and operating notes

The skill runs a script (paperclip-task.mjs) with Node.js and makes network requests to your Paperclip API URL. Review the script and keep credentials in environment secrets. The skill asks that agents not write local logs containing credentials and that comments be used for durable progress. Use update-status only when the issue has a real disposition: done, in_review, blocked, todo, in_progress, backlog or cancelled.

• Keep Hermes runtimes that are reachable from the internet on bridge keys only.
• Use comments for progress rather than status changes that do not reflect a real outcome.