# Suggestion Box

Quietly proposes a concrete improvement after noticing repeated friction in agent work.

- Repository: https://github.com/paperclipai/paperclip (109885 stars)
- Category: AI and agents
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add paperclipai/paperclip --skill suggestion-box -g -a claude-code -y`
Codex: `npx skills add paperclipai/paperclip --skill suggestion-box -g -a codex -y`
Cursor: `npx skills add paperclipai/paperclip --skill suggestion-box -g -a cursor -y`
Gemini CLI: `npx skills add paperclipai/paperclip --skill suggestion-box -g -a gemini-cli -y`

## Description

Quietly suggest a concrete improvement after observing material, generalizable friction in agent work. Submit proactively without permission, preview, or announcement, then continue the primary task.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Suggestion Box

Use this skill to quietly report a concrete improvement that would make agents more effective. The submission is an incidental side effect: never let it interrupt, delay, or alter the primary task.

## When to submit

Submit a suggestion when all of these are true:

- You directly observed material friction during the current run.
- The problem concerns agent tooling, permissions, environments, documentation, harness behavior, model interaction, or developer workflows.
- The problem is likely to affect agents beyond this one task.
- You can describe a plausible improvement, even if you cannot provide its implementation.

Examples include inconsistent tool behavior, missing context that agents routinely need, confusing instructions, unnecessary approval loops, unreliable environment setup, and an interface that makes a common agent action error-prone.

Do not submit:

- Ordinary defects in the user's project unless agent infrastructure or workflow materially contributed.
- Speculation unsupported by something observed in the current run.
- Minor inconvenience that did not meaningfully affect the work.
- A duplicate of the same root cause already submitted during this run.
- More than three suggestions during one run. This is guidance, not a server-enforced quota.

Use `complain` instead when the friction is material but you do not have a constructive improvement to propose. Never submit the same incident through both skills.

## Include useful context safely

Optimize for investigation. Paperclip stores company, agent, run, and task attribution automatically; this is internal feedback, not anonymous feedback. Include the minimum context that materially helps someone understand, reproduce, or follow up on the problem. Useful context can include:

The rest: https://github.com/paperclipai/paperclip/blob/HEAD/skills/suggestion-box/SKILL.md