papercuts
Skill4 starsChanged 12 days agoMITView on GitHub
Log genuine, recurring repository friction to .agents/PAPERCUTS.md — confusing setup, a flaky repo command or script, a misleading in-repo error, stale generated files, or a non-obvious gotcha that will cost the next contributor time. Also use to review, deduplicate, and resolve existing entries. Gate hard before logging: only friction the repository itself can fix counts. Never log the agent's own sandbox/permission errors, shell-scripting mistakes, transient flakiness, or third-party tool quirks the repo can't change.
10 other projects use a version of this, 4 of them edited; 0 new projects in the last 4 weeks, against 1 the 4 before.
Adopted by
Cooling: 0 new projects took it in the last 4 weeks, 0× the 4 weeks before.thin data
Most recently taken up by
- NoyaraAI/Noyaraedited, first seen Nov 15, 2026
- nkrebs13/papercuttheir own version, first seen Nov 8, 2026
- jwuthri-cloud/Tracely-aiedited, first seen Oct 20, 2026
- AndyMelnykov/TeamOSTemplatetheir own version, first seen Oct 17, 2026
- matijagrcic/skillsedited, first seen Oct 13, 2026
- ten9876/AetherSDRtheir own version, first seen Oct 8, 2026
Other versions10 projects use a version of this.
Word for word · 1
- every-app/open-seo★ 28k100% same
Edited · 4
- Jwuthri/Tracely-ai★ 1.3k91% same
- jwuthri-cloud/Tracely-ai★ 97991% same
- matijagrcic/skills★ 130% same
- NoyaraAI/Noyara★ 191% same
Wrote their own version · 5
- ten9876/AetherSDR★ 259same name
- standardagents/skills★ 13same name
- AndyMelnykov/TeamOSTemplate★ 2same name
- nikhil-vytla/skills★ 1same name
- nkrebs13/papercut★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository29 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .claude/CLAUDE.mdCLAUDE.md
- ai-prompt-researchSkill
- ai-visibility-auditSkill
- competitive-landscapeSkill
- competitor-analysisSkill
- create-repo-skillSkill
- deslopSkill
- evaluate-skillSkill
- keyword-clusteringSkill
- keyword-researchSkill
- link-prospectingSkill
- local-seoSkill
- merge-readySkill
- observability-triageSkill
- openseo-release-notesSkill
- openseo-review-web-contentSkill
- review-briefSkill
- review-simplifySkill
- review-ui-statesSkill
- seo-auditSkill
- seo-coachSkill
- seo-project-setupSkill
- seo-reportSkill
- setup-openseoSkill
- simple-issue-descriptionSkill
- stageshowSkill
- test-auditSkill
- verify-local-mcpSkill
The file
We split this skill into the rules it gives an agent
8 rules. 0 are common, 6 are distinctive, and 2 are very specific to this project.
0
Common
Most of the 9 edited versions we read keep these.
6
Distinctive
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 25
If either answer is "no," push through it and move on — do not log it.
- Distinctive: line 45
When something fails, first ask "is this the repo, or is this me/my environment?" Only the former is a papercut.
- Distinctive: line 46
Only the former is a papercut.
- Very specific: line 50
Search .agents/PAPERCUTS.md for an equivalent entry and avoid duplicates.
- Distinctive: line 57
Keep it to one or two sentences: a current example (command/error or affected path), who it blocks or what time it wastes, and the smallest …
- Very specific: line 62
Use UTC timestamps and a short agent label (codex, claude, human).
- Distinctive: line 67
Only mine a whole session or do a broad review when the user explicitly asks.
- Distinctive: line 76
Check whether each surviving papercut still reproduces.
“Common” is measured: kept by at least 6 in 10 of the 9 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Papercuts
Capture small friction in the moment without derailing the current task. Aggregated entries show where the repository needs sanding down — so the bar is that a different contributor would hit the same thing, and the repository can do something about it.
The two-question test
Log it only if both are true:
- Reproducible for anyone. A different person, on a fresh checkout, working in this repo would hit the same friction. It is not specific to your sandbox, shell config, machine, network, or a one-time hiccup.
- Fixable in the repo. A change to the repo's code, config, scripts, or docs would prevent or reduce it.
If either answer is "no," push through it and move on — do not log it.
Do NOT log
- Your environment's failures. Sandbox
EPERM/listen/ IPC-socket errors, blocked network orfetch failed, permission denials, missing system tools. That is the runner, not the repo. - Your own shell mistakes. Reserved or special variable names (
status,path), unquoted globs, a broken login-shell hook. Fix the command — there is nothing in the repo to sand down. - Transient flakiness. A command that succeeded on retry with no repo-side cause (a network blip, a hung push, a slow mirror).
- Local state you corrupted. A partial
node_modulesafter branch-switching, a stale dev-server port, a dirty cache. Re-run the install or cleanup. - Third-party or beta-tool limitations the repo can't change — unless the fix is a repo-side workaround worth writing down (then log that workaround).
- Product or code correctness bugs (fix now or track as real work), and what you accomplished (that belongs in the task summary).
- Secrets, credentials, personal data, raw customer payloads, or sensitive paths.
When something fails, first ask "is this the repo, or is this me/my environment?" Only the former is a papercut.
Log proactively
- Search
.agents/PAPERCUTS.mdfor an equivalent entry and avoid duplicates. Append one unchecked item under
## Openusing this format:- [ ] `YYYY-MM-DDTHH:MM:SSZ` — `agent` — <friction, and the smallest useful fix or workaround>.- Keep it to one or two sentences: a current example (command/error or affected path), who it blocks or what time it wastes, and the smallest useful repo-side fix. Lead with the friction, not with what you were doing.
- Continue the original task. Do not expand a papercut into unrelated work.
Use UTC timestamps and a short agent label (codex, claude, human). Add a
PR or task identifier only when it helps future triage.
Review or resolve
Only mine a whole session or do a broad review when the user explicitly asks.
For a review or prioritization request, inspect and recommend; do not edit the log or implement fixes unless the user also asks for cleanup or implementation. Carry out an authorized cleanup using the same triage:
- Re-run the two-question test on every open entry; recommend removing entries that fail it (environment/shell/flake noise that slipped in).
- Deduplicate and group related entries.
- Check whether each surviving papercut still reproduces. Distinguish reproduced failures, source inspection, and historical reports you could not verify.
- Prioritize current impact against review and maintenance cost. Prefer an existing command or a short documentation fix over new helpers, dependencies, or setup hooks. Defer hypothetical improvements until a concrete need appears.
- For an authorized cleanup, remove noise, consolidate duplicates, and implement
the agreed fixes. Move fixed items to
## Resolved, check them, and append the resolving date or commit. Keep deferred reports separate from actionable open work, with a reason and a concrete trigger to revisit. Route real bugs to normal issue/fix work; route recurring review-policy gaps todocs/maintainers/review-guidelines.md.
Preserve useful history for genuinely-resolved papercuts; do not delete them merely to make the file shorter. (Noise that never belonged — see step 1 — is different: remove it.)
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

