agentleFS
NoyaraAINoyaraAI/Noyara/.agents/skills/papercuts/SKILL.md

papercuts

Skill1 starsChanged 3 months 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, 3 of them edited.

Adopted by

Most recently taken up by

Used with

Projects with it also use simple-issue-description, openseo-review-web-content and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • JwuthriSkill

    simple-issue-description

    Turn a rough bug report, feature request, support note, or pull request into a short, plain-language issue focused on the problem and desired behavior. Use when a contributor asks to simplify an issue, explain what a PR is for, create the corresponding issue for a PR, remove implementation detail from a report, or invokes /simple-issue-description.

    Also in 4 projects that use this

  • JwuthriSkill

    openseo-review-web-content

    Write and review content for the OpenSEO website (web/) — blog posts, guides, feature pages, FAQs. Distills the philosophy for on-brand, useful, accurate content. Use whenever adding or editing user-facing prose in web/content or web/src.

    Also in 4 projects that use this

  • akii-technologies-ltdSkill

    keyword-clustering

    Cluster and organize keywords into topical groups for SEO. Use when the user asks to "cluster keywords", "group keywords", "organize keywords", "keyword mapping", "topic clusters", "keyword grouping", "build a content plan", "pillar pages", "topical authority", "semantic clustering", or pastes a list of keywords.

    Also in 4 projects that use this

  • MicrosoftSkill

    competitive-landscape

    Use when a branch manager asks something like \"Who are we up against in each metro\"

    Also in 4 projects that use this

  • indranilbanerjeeSkill

    keyword-research

    Research keywords via the connected data source: intent, gaps. Grouping → keyword-cluster. \"what keywords should we target\"

    Also in 4 projects that use this

  • LangChainSkill

    competitor-analysis

    Analyze competitors in a given market segment. Trigger on: competitive landscape, competitor analysis, market comparison, competitive positioning.

    Also in 4 projects that use this

  • +5 more from Jwuthri

The file

We split this skill into the rules it gives an agent

9 rules. 0 are common, 7 are distinctive, and 2 are very specific to this project.

  • 0

    Common

    Most of the 8 edited versions we read keep these.

  • 7

    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
  1. Distinctive:

    If either answer is "no," push through it and move on — do not log it.

    line 25
  2. Distinctive:

    When something fails, first ask "is this the repo, or is this me/my environment?" Only the former is a papercut.

    line 45
  3. Distinctive:

    Only the former is a papercut.

    line 46
  4. Very specific:

    Search .agents/PAPERCUTS.md for an equivalent entry and avoid duplicates.

    line 50
  5. Distinctive:

    Keep it to one or two sentences: what got in the way, and the likely repo-side fix.

    line 57
  6. Very specific:

    Use UTC timestamps and a short agent label (codex, claude, human).

    line 61
  7. Distinctive:

    Only mine a whole session or do a broad review when the user explicitly asks.

    line 66
  8. Distinctive:

    When asked to review the file:

    line 68
  9. Distinctive:

    Verify each surviving papercut still reproduces.

    line 73

“Common” is measured: kept by at least 6 in 10 of the 8 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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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:

  1. 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.
  2. 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 or fetch 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_modules after 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

  1. Search .agents/PAPERCUTS.md for an equivalent entry and avoid duplicates.
  2. Append one unchecked item under ## Open using this format:

    - [ ] `YYYY-MM-DDTHH:MM:SSZ` — `agent` — <friction, and the smallest useful fix or workaround>.
  3. Keep it to one or two sentences: what got in the way, and the likely repo-side fix. Lead with the friction, not with what you were doing.
  4. 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.

When asked to review the file:

  1. Re-run the two-question test on every open entry; delete any that fail it (environment/shell/flake noise that slipped in).
  2. Deduplicate and group related entries.
  3. Verify each surviving papercut still reproduces.
  4. Fix the smallest safe, high-leverage entries first.
  5. Move fixed items to ## Resolved, check them, and append the resolving date or commit. Route real bugs to normal issue/fix work; route recurring review-policy gaps through maintain-greptile-rules.

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.)

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.