Guide · Agent skill
How to use the Garden Inbox agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
Garden Inbox is an agent skill for Paperclip, the work-management system where AI agents run tasks. It lets an agent scan a Paperclip user's Mine inbox, sort entries into buckets, and ask you to confirm which reversible archive candidates to hide. This guide explains what the skill does, how to install it, how to trigger it, and what it needs, so you can run a confirm-first inbox cleanup on your own terms.
Garden Inboxpaperclipai/paperclip · MIT Download the skill Quick start
- 1Install the skill. Download the ZIP from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/, or upload it under Settings → Capabilities → Skills in the Claude apps.
- 2Set environment variables. Export PAPERCLIP_API_URL and PAPERCLIP_API_KEY for your Paperclip instance, and confirm Node.js and Git are available.
- 3Run the scan. Run the scan command with an output directory and --stale-days 60, then read garden-inbox-report.md and candidates.json.
- 4Post the confirmation card. Run confirm on the driving issue so you can check the entries you want archived. Use --dry-run first if you want to review the payload.
- 5Apply accepted selections. After you resolve the interaction, run apply with the interaction ID. Only accepted items from candidates.json are archived.
What is an agent skill, and what does Garden Inbox do?
An agent skill is a folder with a SKILL.md instruction file and optional bundled scripts that an AI agent can load and follow for a specific job. Garden Inbox is one such skill, named garden-inbox, from the paperclipai/paperclip project under .agents/skills/garden-inbox. It is licensed MIT.
The skill runs a strictly ordered workflow: scan, then confirm, then apply. The scan reads your Mine inbox and writes a report and candidate file. The confirm step posts a checkbox card on the driving issue so you choose what to archive. The apply step archives only the options you accepted.
- Scan groups every inbox row into exactly one of four buckets: A (merged or archived workspace with 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), and D (keep, never offered for archiving).
- Archiving is a per-user display change. It is reversible and does not alter the underlying issue.
- The skill never deletes branches, closes issues, or cleans workspaces.
Install the Garden Inbox skill
Download the garden-inbox ZIP from this directory page and unzip it. You can install it for yourself or for a single project. For a personal install, unzip it into ~/.claude/skills/. For a project install, unzip it into the project's .claude/skills/ folder.
If you use the Claude apps instead, open Settings, go to Capabilities, and upload the skill under Skills.
- Personal: ~/.claude/skills/
- Project: .claude/skills/ inside your project
- Claude apps: Settings → Capabilities → Skills
Set up the requirements
The skill needs a Paperclip instance and two environment variables: PAPERCLIP_API_URL and PAPERCLIP_API_KEY. The script strips a trailing /api from the URL. It identifies the target user from the run JWT payload's responsible_user_id, and you can override this with --user-id <uuid> only when you want an explicit target.
You also need Node.js. The script uses only built-in modules and has no npm dependencies. Git must be available locally, because the skill checks local Git metadata for branch information.
Before running, create a run-owned output directory. The skill uses the run scratch directory when Paperclip provides one.
- PAPERCLIP_API_URL and PAPERCLIP_API_KEY environment variables
- Node.js (built-in modules only)
- Git available locally for branch metadata checks
RUN_DIR="${PAPERCLIP_RUN_SCRATCH_DIR:-${PAPERCLIP_TASK_SCRATCH_DIR:-.}}/garden-inbox"
mkdir -p "$RUN_DIR"Run the scan step
The scan is read-only. It reads inbox, workspace, close-readiness, and local Git metadata, then writes garden-inbox-report.md and candidates.json to your output directory. It uses a 60-day staleness threshold in the example command.
The scan queries Mine separately for each included issue status, so the endpoint's 500-row cap does not silently hide older rows. If any single-status query hits that cap, both outputs mark coverage as possibly truncated, and you should not treat that scan as complete. Do not manually add bucket D entries to the candidate file.
node .agents/skills/garden-inbox/scripts/garden-inbox.mjs scan \
--output-dir "$RUN_DIR" \
--stale-days 60Confirm selections with checkboxes
The confirm step posts checkbox interactions on the driving issue. It is a confirmation-card write only and does not archive anything. If a scan has more than 200 candidates, the script posts sequential cards. Re-running confirm with the same scan file is idempotent.
If a user declined a candidate in an earlier pass, pass --unselect <issueId> (repeatable) so it starts unchecked and its description notes the earlier decline. Previously declined items are never default-checked. To review the payload without posting, add --dry-run.
- Use --unselect <issueId> for items declined earlier.
- Use --dry-run to inspect the payload without a POST.
node .agents/skills/garden-inbox/scripts/garden-inbox.mjs confirm \
--issue-id "$PAPERCLIP_TASK_ID" \
--candidates "$RUN_DIR/candidates.json"Apply only the accepted selections
After the interaction is resolved, the wake payload provides an interaction ID. Running apply archives only accepted option IDs that also appear in the original candidates.json. If you reject the card, it expires, or you accept an empty selection, nothing is archived.
Apply keeps the scan file's target user, including any explicit --user-id override. Its summary lists the API undo path and target-user body for every archived row, so you can reverse changes. To test apply without API writes, pass a saved interaction response with --interaction-file and --dry-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"Trigger the skill with natural requests and check the tests
You do not need special syntax. The skill's description says it applies when you ask an agent to garden, clean up, prune, or tidy a Paperclip inbox without changing issues, branches, or workspaces. Phrase requests along those lines and the agent will follow the scan, confirm, apply order.
If you change the classification or selection logic, run the bundled zero-dependency tests to verify it.
- "Garden my Paperclip Mine inbox and show me what you'd archive."
- "Tidy up my Paperclip inbox, but don't touch issues, branches, or workspaces."
- "Prune stale finished work from my Mine inbox and ask me to confirm first."
node --test .agents/skills/garden-inbox/scripts/garden-inbox.test.mjsWhat people use it for
- Hiding stale finished work from a cluttered Paperclip Mine inbox after you review each suggestion.
- Running a supervised cleanup for a team of Paperclip agents where a person confirms every archive.
- Reviewing which inbox entries have commits ahead of base (bucket C) before deciding anything, since those are never selected by default.
- Checking the planned changes with --dry-run before any API writes happen.
Frequently asked questions
How do I install the garden-inbox agent skill?
Download the garden-inbox ZIP from this page and unzip it into ~/.claude/skills/ for personal use or a project's .claude/skills/ folder for one project. In the Claude apps, you can instead upload it under Settings → Capabilities → Skills.
What do I need to run Garden Inbox?
You need a Paperclip instance, the PAPERCLIP_API_URL and PAPERCLIP_API_KEY environment variables, Node.js (the script uses built-in modules only), and Git available locally for branch metadata checks.
Is Garden Inbox free to use?
The skill is licensed under MIT. The source does not state pricing for Paperclip itself, so check the Paperclip project for its terms.
Does Garden Inbox delete branches or close issues?
No. The skill explicitly forbids issue status changes, branch deletion, workspace cleanup, and issue deletion. Archiving is a reversible per-user display change that does not alter the underlying issue.
Will it archive items without asking me?
No. Apply runs only after you resolve a checkbox confirmation, and it archives only accepted options. If you reject the card, it expires, or you accept nothing, the script archives nothing.
Can I undo an archive?
Yes. The apply summary includes the API undo path and target-user body for every archived row, which you can use to reverse each archive.
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
Garden Inbox suits Paperclip users with a cluttered Mine inbox who want stale, finished work hidden, and teams that want a supervised, confirm-first cleanup. It is not a good fit if you want automatic cleanup without review, or if you expect it to delete branches, close issues, or clean workspaces, since the skill forbids all of those.
Download the skill