public-artifact-hygiene
Skill0 starsChanged 5 months agoMITView on GitHub
Usar antes de escribir cualquier contenido en sistemas visibles para el equipo o terceros — repos (CLAUDE.md, README, código, mensajes de commit, descripciones de PR), Linear/Jira, Notion, GitHub issues/discussions, Slack público, documentación. Especialmente al final de un flujo de trabajo privado (workspace local, memoria personal, scratchpads) cuando vas a publicar el resultado.
- Commits and pushes
In this repository18 other files it gives its agents.
- adversarial-code-reviewSkill
- api-schema-separationSkill
- careful-destructive-opsSkill
- comments-disciplineSkill
- delegate-to-codexSkill
- design-rigor-alternativesSkill
- frontend-screen-and-loadingSkill
- migrations-alwaysSkill
- no-premature-abstractionSkill
- openapi-frontend-syncSkill
- paginate-and-filterSkill
- pr-disciplineSkill
- pre-deploy-checklistSkill
- read-before-writeSkill
- reuse-existing-patternsSkill
- secrets-handlingSkill
- test-layer-disciplineSkill
- use-worktreesSkill
The file
We split this skill into the rules it gives an agent
1 rule. About 0 are common, 1 is distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 150
"Origen: conversación con Claude el martes pasado": No es consultable.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Public Artifact Hygiene
Overview
Lo que escribes en sistemas compartidos queda visible para gente que no tiene tu contexto local: tus paths absolutos, tu workspace privado, tus memorias, tus notas previas. Referenciar artefactos privados en sistemas públicos genera ruido, confusión, y a veces expone información sensible.
Principio: lo privado se queda en lo privado. En lo compartido, referencias a artefactos que el lector PUEDE abrir.
Anunciar al inicio: "Aplicando public-artifact-hygiene antes
de publicar en <sistema>."
Qué cuenta como "sistema visible"
| Sistema | Visible por |
| Repos (CLAUDE.md, README, código, commits, PRs) | Todo el equipo + público si el repo es open source |
| Linear / Jira (descripciones, comentarios) | Equipo entero |
| Notion público | Toda la organización |
| GitHub issues / discussions / comments | Público si el repo es open source |
| Slack canales públicos | Toda la organización |
| Documentación externa | Clientes, stakeholders |
Lo opuesto — privado — incluye:
- Tu home local (
/home/carlos/...,~/). - Tu workspace de tareas (
workspace/tasks/,scratchpads/). - Tu auto-memoria (
~/.claude/projects/.../memory/). - Tus notas personales en archivos fuera del repo.
- Conversaciones de Claude/ChatGPT/Codex en tu máquina.
Step 1: Identificar qué clase de artefacto vas a escribir
| Vas a escribir... | Es visible? |
git commit -m ... | Sí — queda en historia |
gh pr create --body ... | Sí — visible en GitHub |
| README.md, CLAUDE.md, CONTRIBUTING.md | Sí — versionado |
| Linear issue description | Sí — equipo |
| Comentario en Notion | Sí — equipo o más |
Mensaje a Slack #general | Sí — toda la org |
Comentario // en código del repo | Sí — versionado |
Memoria local en ~/.claude/ | NO — privado |
Notas en workspace/tasks/ | NO — privado |
| Conversación viva con el agente | Privado por defecto |
Si la respuesta es "sí", aplica esta skill.
Step 2: No incluir paths locales
Patrones a evitar en cualquier contenido visible:
/home/<usuario>/...o~/Documents/...o~/projects/.../Users/<usuario>/...(macOS)C:\Users\...(Windows)- Rutas absolutas a archivos en tu máquina.
En lugar de:
"Ver
/home/carlos/Documents/Trabajo/proyecto/scripts/migrate.pypara el detalle."
Usar:
"Ver
scripts/migrate.pyen este repo." (path relativo desde la raíz del repo)
O si no está en el repo:
"El script de migración vive fuera de este repo por convención del proyecto."
Step 3: No referenciar artefactos privados
Patrones a evitar:
workspace/tasks/<tarea>/TASK.md(tu cuaderno privado).~/.claude/projects/.../memory/<archivo>.md(tu memoria de agente).scratchpads/<algo>.md(notas locales).docs/superpowers/specs/<spec>.mdsi la carpetadocs/superpowers/está gitignored.- Cualquier referencia a una sesión de Claude/Codex/ChatGPT como fuente de autoridad — esas conversaciones no son consultables por otros.
En lugar de:
"Origen: workspace/tasks/auth-rewrite/TASK.md"
Hacer una de dos:
- Pegar el contenido relevante inline en el artefacto público:
"Origen: tras incidente de 2025-11-20 donde el guard de auth no validaba el token en endpoints internos, decidimos reescribir el módulo. Scope: ..."
- Referenciar un artefacto público equivalente:
"Origen: GitHub issue #245, ADR #12, PR #1203."
Step 4: Quick test antes de publicar
Antes de enviar/commitear/abrir, leer el contenido completo y preguntarse:
"Si alguien sin acceso a mi laptop, sin acceso a mis memorias, sin haber estado en mi conversación con el agente, leyera esto, ¿lo entendería?"
Si la respuesta es no porque hay referencias a paths locales, workspace privado, memorias o conversaciones — reescribir hasta que sí.
Step 5: Cómo pegar contexto privado de forma pública
Si la información útil está en tu workspace privado, traerla al artefacto público de forma autocontenida:
| Vive en privado | Lleva a lo público como... |
| Análisis de causa raíz en notas locales | Resumen del análisis, no link a las notas |
| Decisión documentada en memoria | Razón inline + enlace a ADR público si existe |
| Discusión con el agente | Conclusión final + datos, no historia de la conversación |
| Spec borrador en scratchpad | Spec finalizado en docs/ del repo, sin referenciar el borrador |
Quick Reference
| Situación | Acción |
| Voy a escribir en repo / PR / commit / Linear / Slack | Step 1: confirmar que es visible + Step 2-3: limpiar |
| Tengo paths absolutos en lo que escribí | Step 2: convertir a relativos o quitar |
| Quiero referenciar workspace/tasks/, scratchpads/, ~/.claude/ | Step 3: pegar contexto inline en su lugar |
| Quiero citar una conversación con el agente | Step 5: traer la conclusión, no la conversación |
| El contenido es útil pero solo cierra con mi contexto | Step 4: reescribir para que cierre solo |
Common Mistakes
- Paths absolutos en CLAUDE.md / README. "Ver
/home/carlos/Documents/..." no significa nada para otro dev. - Referenciar
workspace/tasks/X/TASK.mden Linear. El equipo no tiene acceso a tu cuaderno privado. - "Origen: conversación con Claude el martes pasado". No es consultable.
- Asumir que
docs/superpowers/es público. Si está en.gitignore, no lo es. - Pegar texto que tiene
~/.claude/o paths locales en un commit message. Queda para siempre en la historia.
Red Flags
Nunca:
- Pegar paths absolutos (
/home/...,~/...,/Users/...,C:\...) en contenido visible. - Referenciar
workspace/tasks/, scratchpads, memorias personales, o carpetas gitignored desde sistemas compartidos. - Citar conversaciones con un agente como fuente de autoridad para otros.
- Asumir que algo en
docs/es público sin verificar.gitignore.
Siempre:
- Antes de publicar, leer el contenido entero pensando en un lector sin tu contexto local.
- Convertir paths absolutos a relativos al repo, o quitarlos.
- Pegar contexto privado inline cuando aporta al artefacto público, no como referencia.
- Cuando hay artefacto público equivalente (issue, PR, ADR, página Notion), referenciarlo a ese.
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.

