Guide · Agent skill
How to use the Suggestion Box agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The Suggestion Box skill is a SKILL.md instruction file for an AI agent. When the agent runs into material friction in its own work, such as an unreliable tool or a confusing instruction, the skill tells it to file a short improvement suggestion with the Paperclip platform and then carry on with the task. This guide explains what the skill does, how to install it, how to trigger it, and what it needs and exposes before you turn it on.
Suggestion Boxpaperclipai/paperclip · MIT Download the skill Quick start
- 1Download the ZIP. Download the skill ZIP from this page and unzip it. It contains SKILL.md.
- 2Place the skill folder. For personal use, unzip into ~/.claude/skills/. For one project, unzip into that project's .claude/skills/ folder.
- 3Or upload in the Claude apps. In the Claude apps, open Settings → Capabilities → Skills and upload the skill.
- 4Check the requirements. Confirm your run has a Paperclip environment with submit_suggestion, or the paperclip operational skill with its helper script, and existing Paperclip credentials.
- 5Run agent work as normal. The agent files suggestions in the background when it observes material friction and continues the main task without asking you first.
- 6Ask about feedback if needed. Ask the agent what it submitted. The skill requires a truthful answer.
What the Suggestion Box skill makes the agent do
The skill is about feedback on agent infrastructure, not ordinary bugs in your project. The source says an agent should submit a suggestion only when it directly observed material friction during the current run, the problem concerns agent tooling, permissions, environments, documentation, harness behavior, model interaction, or developer workflows, and the problem is likely to affect agents beyond that one task.
Examples in the source include inconsistent tool behavior, missing context agents routinely need, confusing instructions, unnecessary approval loops, unreliable environment setup, and an interface that makes a common agent action error-prone. The submission is meant to be a side effect: the skill says it must never interrupt, delay, or alter the primary task.
- Submits at most three suggestions in one run (guidance, not a server-enforced quota).
- Does not submit speculation, minor inconvenience, or duplicates of the same root cause in one run.
- Uses the complain skill instead when friction is material but there is no constructive improvement to propose. The same incident should never go through both skills.
Install the skill from the ZIP
Download the ZIP for the skill from this page and unzip it. The skill is a single file, SKILL.md. For a personal install, unzip it into ~/.claude/skills/. For a single project, unzip it into that project's .claude/skills/ folder.
Alternatively, upload the skill in the Claude apps under Settings → Capabilities → Skills.
- Personal install: ~/.claude/skills/
- Project install: the project's .claude/skills/ folder
- Claude apps: Settings → Capabilities → Skills, then upload
Know what the skill needs before you use it
The skill requires either a Paperclip environment that provides the submit_suggestion tool, or the installed paperclip operational skill and its scripts/submit-agent-commentary.mjs helper. The helper uses the existing Paperclip credentials available to the run. The source says no new credential is required.
The skill runs scripts and uses the network. Submissions go to Paperclip, and the skill states that Paperclip stores company, agent, run, and task attribution automatically. The skill also says no Slack or external destination is involved.
- Requires a Paperclip environment with submit_suggestion, or the paperclip operational skill with its helper script
- Uses existing Paperclip credentials available to the run
- Runs scripts: yes. Uses network: yes
How to trigger the skill with natural requests
The skill is designed to run on its own during agent work, so you do not need a special phrase to start it. Its description says the agent should submit proactively, without permission, preview, or announcement, and then continue the primary task.
If you want to see how an agent is handling feedback, you can ask it directly. The skill says that if a user asks about feedback or what was submitted, the agent should answer truthfully.
- Ask the agent what feedback it has submitted during this run and expect a truthful answer.
- Ask the agent whether it hit any tooling or workflow friction during the task.
- Check the installed skill folder to confirm SKILL.md is present.
Examples of what gets reported
A typical case from the source is a submission helper that reports success before the file exists, so the next step fails. The suggested improvement is to return success only after the write completes. The agent writes this as a short, plain-language message with its own wording.
Other fitting examples are a tool that behaves inconsistently between calls, or an instruction that forces an agent through repeated approval prompts for a routine action.
- Tool reports success before a write completes, causing a later step to fail
- Repeated approval prompts for a routine, low-risk agent action
- Missing context that agents routinely need to start a task
Safety notes: scripts, network and data
The skill tells agents not to include secrets, credentials, tokens, environment-variable values, customer or user data, private prompts, copied source code, or large raw logs. It also says to avoid naming people or speculating about who caused a problem.
Because the skill asks for run links and identifiers for follow-up, a report can identify the run or the person who hit the problem. The source accepts this when the context is useful. Review this before enabling the skill in private or regulated projects.
- Do not enable it where any automatic outbound report may conflict with your data policy.
- Users who want to approve reports before they are sent should not use this skill, since it forbids asking permission or showing a preview.
- The helper prints only a storage acknowledgement or a sanitized diagnostic, and failures are not retried.
node <paperclip-skill-directory>/scripts/submit-agent-commentary.mjs suggestionTips for getting the most from it
The skill favours one root cause per submission and brief, complete sentences. If you run agents inside Paperclip, the reports are most useful when the agent describes the system and behaviour rather than people.
Keep the skill for agents that work on Paperclip-managed tasks. For ordinary defects in your project, the skill tells agents not to file a suggestion unless agent infrastructure or workflow materially contributed.
- Use it in Paperclip environments where the platform collects this feedback.
- Keep to one clear root cause per run to avoid duplicate submissions.
- Pair it with the complain skill for material friction that has no proposed fix.
What people use it for
- Teams running agents inside Paperclip who want tooling and workflow problems reported back to the platform.
- Developers of agent tooling who want a steady stream of field feedback from real agent runs.
- Reporting an unreliable environment setup step that agents keep tripping over.
- Flagging an interface that makes a common agent action error-prone.
Frequently asked questions
Is the Suggestion Box skill free?
The source gives the licence as MIT. It does not state any price, so check the Paperclip project for any terms beyond the licence.
What do I need to use the Suggestion Box skill?
You need either a Paperclip environment that provides the submit_suggestion tool, or the installed paperclip operational skill with its scripts/submit-agent-commentary.mjs helper. The helper uses existing Paperclip credentials available to the run, and the source says no new credential is required.
How do I install the suggestion-box skill?
Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder. You can also upload it in the Claude apps under Settings → Capabilities → Skills.
Does the skill ask me for permission before sending a suggestion?
No. The skill explicitly forbids asking for permission or showing a preview, and it says submissions should happen silently. If you need to approve outbound messages, do not use this skill.
Does the skill send data outside Paperclip?
The source says the helper uses the run's existing Paperclip environment and credentials, and that no Slack, external destination, or new credential is involved. Reports can include run links and identifiers, so review your data policies first.
What should I use instead of the Suggestion Box skill?
Use the complain skill when friction is material but there is no constructive improvement to propose. For ordinary project bugs, the skill itself says not to submit unless agent infrastructure or workflow materially contributed, so report those through your normal channels.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use the Suggestion Box skill if your agents run inside Paperclip and you want them to report tooling and workflow friction to the platform without interrupting work. Skip it if you need to review or approve what leaves your environment, or if your project's data policies do not allow automatic outbound reports with run identifiers.
Download the skill