How to use the create-issue-interaction-ui agent skill

What an agent skill is and what this one does

An agent skill is a folder with a SKILL.md file that gives an agent extra instructions for a specific task. This skill's SKILL.md is the only file it ships with, and it does not run any scripts.

When the skill applies, the agent follows a checklist that covers five layers of an issue-thread interaction: the shared type and validator code, the server service and routes, the UI card and issue-thread wiring, the channel handling, and the helper and documentation work (CLI, MCP tool, plugin SDK and the skills/paperclip guidance).

• Shared: kind constant, payload and result interfaces, Zod validators, exported types and shared tests.
• Server: create, accept, reject, respond, staleness, supersede, idempotency, activity log and wake behavior.
• UI: pending, resolved and stale card states, fixtures, Storybook and issue-thread wiring.
• Channels: complete question context, native response or Paperclip handoff, and callback authorization.
• Helpers and docs: CLI command, MCP tool, plugin SDK path and skills/paperclip guidance.

Install the create-issue-interaction-ui skill

Download the ZIP for this skill from the page, then unzip it into one of these locations: ~/.claude/skills/ for your user account, or .claude/skills/ inside a project. Alternatively, in the Claude apps, open Settings, go to Capabilities, then Skills, and upload the ZIP there.

Only install it where repository work happens. The skill file itself says not to install it on production Paperclip agents.

• Personal install: ~/.claude/skills/
• Project install: .claude/skills/ in your project folder
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP

Requirements before you start

You need a local clone of the paperclipai/paperclip repository. You also need Git, because the skill's worked example uses a git show command on commit 4d5322c82.

The skill does not use the network and does not run scripts, so these are the only prerequisites listed.

• A local clone of paperclipai/paperclip
• Git installed on your machine

How to trigger the skill with natural requests

The skill is meant for repository work that introduces or extends an interaction card. Name the kind of card you want, and say you are changing the Paperclip code. The skill's description lists request_confirmation, request_checkbox_confirmation, ask_user_questions and suggest_tasks as examples of existing kinds.

Ask for the change in terms of the repo, not day-to-day agent operations. Requests like adding a compact picker or an in-thread approval card fit the skill. Requests to change how agents call existing interactions do not, because the guide sends those to skills/paperclip.

• Add a new interaction kind for a structured rating card in issue threads, following the Paperclip shared, server and UI layers.
• Add a parallel variant of request_confirmation with a different payload shape and validation, and tell me which existing kind it is closest to.
• Extend the checkbox confirmation pattern to a new card in the paperclipai/paperclip repo, using commit 4d5322c82 as the reference.

Follow the order of operations

The guide asks you to start with the shared contract, because it is the smallest correct change you can land before the UI is final and every later layer reads its types and validators. Then work through the server service and routes, the UI card wiring, the channel handling and the helpers and docs.

Pick the closest existing kind and reuse its plumbing rather than inventing new mechanics. Target-bound yes/no cards follow the request_* kinds, structured forms follow ask_user_questions, and cards that create child entities follow suggest_tasks.

• Shared contract: packages/shared/src/constants.ts, types/issue.ts, validators/issue.ts, and issue-thread-interactions.test.ts.
• Server: server/src/services/issue-thread-interactions.ts and server/src/routes/issues.ts, with their matching test files.
• Keep option lists bounded, keep option ids unique, and use the shared RequestConfirmationTarget schema when target binding applies.
• Scope every read, write, expiration and supersede by companyId, and never trust an issueId alone.

Learn from the worked example

The guide names the checkbox confirmation rollout, merged in commit 4d5322c82 (GitHub PR #7649), as the current best end-to-end reference. Read its diff before you start, so you can see which files a complete change touches.

The plan for that change is kept as an issue document on PAP-10415. You can use it as a template for your own plan document if you run the work through Paperclip itself.

Safety notes: scripts and network

The skill runs no scripts and makes no network calls, according to its listing. Its only action is to give the agent instructions and a checklist, and any code changes still go through your normal review.

Governed actions keep their required human approval. The skill's guidance says neither a new interaction kind nor a channel callback widens resolver authority.

• Do not install it on production Paperclip agents.
• Review every change the agent makes before you merge it.
• Keep resolver policy, company cap and named addressee checks as they are in the shared service.