garden-inbox
Scan a Paperclip user's Mine inbox, classify reversible archive candidates, request checkbox confirmation, and archive only accepted selections. Use when asked to garden, clean up, prune, or tidy a Paperclip inbox without changing issues, branches, or workspaces.
How do I install this agent skill?
npx skills add https://github.com/paperclipai/paperclip --skill garden-inboxIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill provides a utility for Paperclip users to manage their inbox by identifying and archiving stale or finished items. It follows a structured 'scan-confirm-apply' workflow, uses standard environment variables for authentication, and implements safety checks such as markdown escaping and idempotency keys.
- Socketpass
No alerts
- Snykwarn
Risk: MEDIUM · 1 issue
What does this agent skill do?
Garden Inbox
Use the bundled script for every stage. Keep the workflow strictly ordered: scan → confirm → apply.
Safety contract
- Treat
scanas read-only. It may read inbox, workspace, close-readiness, and local Git metadata only. - Treat
confirmas a confirmation-card write only. It must not archive inbox entries or mutate issue fields, branches, or workspaces. - Run
applyonly after a resolvedrequest_checkbox_confirmationinteraction. It archives only accepted option IDs that also occur in the originatingcandidates.json. - Remember that inbox archive state is per-user presentation state. It is reversible and does not change the underlying issue.
- Never substitute issue status changes, branch deletion, workspace cleanup, or issue deletion for inbox archiving.
Inputs
Require PAPERCLIP_API_URL and PAPERCLIP_API_KEY. The script strips a trailing /api from the URL. It resolves the target user from the run JWT payload's responsible_user_id; use --user-id <uuid> only for an explicit target override.
Use a run-owned output directory when available:
RUN_DIR="${PAPERCLIP_RUN_SCRATCH_DIR:-${PAPERCLIP_TASK_SCRATCH_DIR:-.}}/garden-inbox"
mkdir -p "$RUN_DIR"
1. Scan
node .agents/skills/garden-inbox/scripts/garden-inbox.mjs scan \
--output-dir "$RUN_DIR" \
--stale-days 60
Inspect garden-inbox-report.md and candidates.json. The report groups every inbox row into exactly one bucket:
The scan reads Mine separately for each included issue status so the endpoint's global 500-row cap does not silently omit older rows. If any single-status query reaches that cap, both outputs mark coverage as possibly truncated; do not treat that scan as complete.
- A: merged/archived workspace and all linked work terminal; selected by default.
- B: terminal or workspace-gone work idle beyond the threshold; selected by default.
- C: stale work with commits ahead of base; never selected by default.
- D: keep; never offered for archiving.
Do not manually promote bucket D entries into the candidate file.
2. Confirm
Post checkbox interactions on the driving issue:
node .agents/skills/garden-inbox/scripts/garden-inbox.mjs confirm \
--issue-id "$PAPERCLIP_TASK_ID" \
--candidates "$RUN_DIR/candidates.json"
The script posts sequential cards when a scan has more than 200 candidates. Re-running confirm with the same scan file is idempotent. Leave the driving issue in the waiting posture required by the surrounding Paperclip heartbeat workflow.
When a candidate was declined by the user in an earlier pass, pass --unselect <issueId> (repeatable) so it starts unchecked and its description notes the earlier decline. Never re-offer previously declined items as default-checked.
For development or payload review, suppress the POST:
node .agents/skills/garden-inbox/scripts/garden-inbox.mjs confirm \
--issue-id "$PAPERCLIP_TASK_ID" \
--candidates "$RUN_DIR/candidates.json" \
--dry-run
3. Apply accepted selections
After an interaction-resolution wake, take the resolved interaction ID from the wake payload and run:
node .agents/skills/garden-inbox/scripts/garden-inbox.mjs apply \
--issue-id "$PAPERCLIP_TASK_ID" \
--interaction-id "$INTERACTION_ID" \
--candidates "$RUN_DIR/candidates.json"
On rejection, expiry, or an accepted empty selection, the script archives nothing. Apply preserves the scan file's target user, including an explicit --user-id override. Its summary includes the API undo path and target-user body for every archived row.
Test apply without API writes by supplying a saved interaction response:
node .agents/skills/garden-inbox/scripts/garden-inbox.mjs apply \
--issue-id "$PAPERCLIP_TASK_ID" \
--interaction-file resolved-interaction.json \
--candidates "$RUN_DIR/candidates.json" \
--dry-run
Verify the bundled logic
Run the zero-dependency Node tests after changing classification or selection safety:
node --test .agents/skills/garden-inbox/scripts/garden-inbox.test.mjs
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/paperclipai/paperclip/garden-inbox">View garden-inbox on skillZs</a>