🗂️ Estructura del repositorio

El repositorio mp-skill/ y está organizado en una raíz corta con tres tipos de elementos: archivos de documentación en la raíz, carpetas de servicio (docs, scripts, manifest) y la carpeta skills/ dividida en buckets. Mira el árbol completo en un solo lugar:

mp-skill/
├── README.md              # indice publico de skills
├── CONTEXT.md             # quem e o autor, principios
├── CLAUDE.md              # regras do repo para o agente
├── LICENSE                # licenca de uso
├── .claude-plugin/
│   └── plugin.json        # manifest do plugin Claude Code
├── docs/                  # documentos longos, ADRs
├── scripts/               # automacoes auxiliares
└── skills/
    ├── engineering/       # codigo diario (publico)
    ├── productivity/      # workflow nao-codigo (publico)
    ├── misc/              # uso raro (publico)
    ├── personal/          # meu setup (privado)
    ├── in-progress/       # rascunhos (privado)
    └── deprecated/        # aposentadas (privado)

El bucket engineering/ guarda las skills que realmente usas cuando estás escribiendo, leyendo o revisando código. Son 10 skills, cada una con un propósito acotado y un verbo claro. Si una skill de aquí no se usa por semanas, pasa a misc/ — engineering no acumula experiencia.

El bucket productivity/ existe para skills que orquestan el trabajo: conducir entrevistas, cerrar sesiones, escribir, decidir. Aquí no hay nada de compilar código. Son 4 skills, todas se usan semanalmente.

misc/ y el purgatorio. Skills que ya fueron útiles, todavía sirven en casos específicos, pero no merecen espacio mental a diario. Se quedan aquí precisamente para no llenar engineering ni productivity.

Los tres buckets privados. Todo esto está en el repo, pero no aparece en el README.md ni en el plugin.json. Saber la diferencia entre ellos evita llenar el catálogo público de borradores o de herramientas tan específicas que solo funcionan en tu máquina.

Los tres `.md` de la raíz tienen públicos distintos. Cambiar uno por otro confunde tanto a las personas como al agente. Memoriza: README es para quien llega, CONTEXT para entender la intención y CLAUDE para que el agente opere.

# Trecho real do CLAUDE.md deste repo

Skills are organized into bucket folders under `skills/`:

- engineering/   # daily code work
- productivity/  # daily non-code workflow tools
- misc/           # kept around but rarely used
- personal/       # tied to my own setup, not promoted
- in-progress/    # drafts not yet ready to ship
- deprecated/     # no longer used

Every skill in engineering/, productivity/, or
misc/ must have a reference in the top-level
README.md and an entry in
.claude-plugin/plugin.json.

Skills in personal/, in-progress/,
and deprecated/ must not appear in either.

Claude Code no descubre tus skills por magia del filesystem. Lee un manifest en .claude-plugin/plugin.json que enumera explícitamente cada skill pública. Sin una entrada en el manifest, la skill existe en el disco, pero el agente no la ve.

// .claude-plugin/plugin.json
{
  "name": "mp-skill",
  "version": "1.0.0",
  "description": "Skills do Matt Pocock para Claude Code",
  "skills": [
    {
      "name": "diagnose",
      "path": "skills/engineering/diagnose"
    },
    {
      "name": "tdd",
      "path": "skills/engineering/tdd"
    },
    {
      "name": "handoff",
      "path": "skills/productivity/handoff"
    }
    // ... uma entrada por skill publica
  ]
}

Toda skill y un único archivo: SKILL.md, dentro de una carpeta con el nombre de la skill. Frontmatter YAML al principio y cuerpo en Markdown debajo. Ya no hay más archivos obligatorios; si necesitas referencias, colócalas en references/ dentro de la carpeta.

--- <-- frontmatter YAML
name: minha-skill
description: Use when ... (descricao de trigger)
--- <-- fim do frontmatter

# Skill body

Instrucoes em markdown para o agente seguir quando esta skill
ativa. Pode ter exemplos, regras, checklists, snippets de codigo.

Mantenha conciso: o agente vai ler isso TODA vez que a skill
ativar. Cada linha gasta contexto.

skills/engineering/diagnose/
├── SKILL.md             # obrigatorio
├── references/          # opcional, refs longas
│   └── checklist.md
└── examples/            # opcional, exemplos
    └── caso-1.md