# Papercuts > Registra en `.agents/PAPERCUTS.md` la fricción real y recurrente del repositorio (setup confuso, comandos inestables, errores engañosos, archivos generados obsoletos) y también revisa, deduplica y resuelve las entradas existentes. Fuente: https://skillsagentes.com/skills/every-app/open-seo/papercuts Markdown: https://skillsagentes.com/skills/every-app/open-seo/papercuts.md Repositorio: https://github.com/every-app/open-seo Autor: every-app Licencia: MIT Actualizado: el mes pasado Coste de contexto: 132 tok instalada, 994 tok al activarse, 1.1k tok con todos los archivos del bundle Bundle: 2 archivos, 4 KB Permisos que pide: ninguno declarado ## Instalación Un skill son archivos markdown: los mismos archivos valen para cualquier agente y lo único que cambia es el directorio de destino, es decir la bandera `--agent`. Añade `-g` para instalarlo en todos los proyectos de la máquina. ```bash # Claude Code npx -y skills add every-app/open-seo --skill papercuts --agent claude-code # Cursor npx -y skills add every-app/open-seo --skill papercuts --agent cursor # Codex npx -y skills add every-app/open-seo --skill papercuts --agent codex # Gemini CLI npx -y skills add every-app/open-seo --skill papercuts --agent gemini # Windsurf npx -y skills add every-app/open-seo --skill papercuts --agent windsurf # Cline npx -y skills add every-app/open-seo --skill papercuts --agent cline ``` ## Qué hace - Registra en `.agents/PAPERCUTS.md` la fricción real y recurrente del repositorio: setup confuso, un comando o script inestable, un error interno engañoso, archivos generados obsoletos o un gotcha no obvio. - Aplica el test de dos preguntas: solo se registra si es reproducible para cualquiera en un checkout limpio Y el repositorio puede arreglarlo. - Nunca registra los errores de sandbox o permisos del propio agente, fallos de scripting de shell, inestabilidad transitoria ni rarezas de herramientas de terceros. - Añade un ítem sin marcar bajo `## Open` con timestamp UTC y una etiqueta corta de agente, en una o dos frases, sin desviarse de la tarea. - Al revisar el archivo, vuelve a pasar el test a cada entrada abierta, deduplica, verifica que aún se reproduce y mueve las arregladas a `## Resolved`. ## Cuándo usarla - Se topa con fricción genuina y recurrente del repositorio que costará tiempo al siguiente contribuidor. - Se pide revisar, deduplicar o resolver las entradas existentes de papercuts. ## Cuándo no - Errores de sandbox o permisos del agente, fallos propios de shell, inestabilidad transitoria o límites de herramientas de terceros que el repo no puede cambiar. ## Qué la activa - "Registra este papercut: el script de setup falla sin decir por qué" - "Revisa y deduplica .agents/PAPERCUTS.md" - "Resuelve las entradas de papercuts que ya estén arregladas" ## Archivos - SKILL.md — 4 KB - agents/openai.yaml — 224 B ## SKILL.md Reproducido tal cual desde every-app/open-seo bajo MIT. Esta sección es el documento original y está en inglés. # 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: ```markdown - [ ] `YYYY-MM-DDTHH:MM:SSZ` — `agent` — . ``` 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.) ## Dónde encaja - Categoría: [Herramientas para desarrolladores](https://skillsagentes.com/categorias/herramientas-desarrollo.md) — Skills que cambian cómo tu agente escribe, revisa y despliega código. - Creador: [every-app](https://skillsagentes.com/creators/every-app.md) — 19 skills en el directorio - [Todas las skills](https://skillsagentes.com/skills.md) - [Ranking de instalaciones](https://skillsagentes.com/ranking.md) ## Otras skills del mismo repositorio - [Seo Coach](https://skillsagentes.com/skills/every-app/open-seo/seo-coach.md): Entra en un modo de coach de OpenSEO cercano que explica los flujos, recomienda los siguientes pasos y ayuda a usar bien agentes, búsqueda web, scraping y datos MCP. - [Seo Audit](https://skillsagentes.com/skills/every-app/open-seo/seo-audit.md): Audita un sitio y entrega un informe SEO de una página, en lenguaje llano, que cualquiera puede accionar, centrado en una única acción para esta semana. - [Create Repo Skill](https://skillsagentes.com/skills/every-app/open-seo/create-repo-skill.md): Crea o actualiza una skill en este repositorio de la forma correcta: hogar canónico en `.agents/skills`, marca interna o pública, symlinks en `.claude/skills` y registro en las docs públicas para las skills de producto. - [Seo Project Setup](https://skillsagentes.com/skills/every-app/open-seo/seo-project-setup.md): Rellena el contexto compartido de OpenSEO de un proyecto (alcance del sitio, objetivos, posicionamiento, competidores, páginas clave y preferencias), más comprobaciones de MCP y entrada de Search Console. - [Keyword Research](https://skillsagentes.com/skills/every-app/open-seo/keyword-research.md): Descubre oportunidades de palabras clave, evalúa métricas y SERPs y guarda o etiqueta los términos prometedores usando los datos MCP de OpenSEO. ## Skills relacionadas - [Simple Issue Description](https://skillsagentes.com/skills/every-app/open-seo/simple-issue-description.md): Convierte un reporte de bug tosco, una petición de feature, una nota de soporte o un PR en un issue corto y en lenguaje llano, centrado en el problema y el comportamiento deseado. - [Maintain Greptile Rules](https://skillsagentes.com/skills/every-app/open-seo/maintain-greptile-rules.md): Evalúa hallazgos verificados de revisiones de merge-ready, Greptile, PR, CI, seguridad y facturación, y promueve los huecos de revisión duraderos a la configuración versionada de `.greptile`. - [Create Repo Skill](https://skillsagentes.com/skills/every-app/open-seo/create-repo-skill.md): Crea o actualiza una skill en este repositorio de la forma correcta: hogar canónico en `.agents/skills`, marca interna o pública, symlinks en `.claude/skills` y registro en las docs públicas para las skills de producto. - [Keyword Research](https://skillsagentes.com/skills/every-app/open-seo/keyword-research.md): Descubre oportunidades de palabras clave, evalúa métricas y SERPs y guarda o etiqueta los términos prometedores usando los datos MCP de OpenSEO. - [Openseo Release Notes](https://skillsagentes.com/skills/every-app/open-seo/openseo-release-notes.md): Corta una release de OpenSEO: sube la versión, redacta notas de versión para el usuario desde los commits del último tag, pasa una revisión con verificación por subagentes y abre un PR `release: vX.X.X`. --- Skills Agentes · [Índice de páginas en markdown](https://skillsagentes.com/sitemap.md) · [Inicio](https://skillsagentes.com/index.md)