🗂️ Estrutura do repositorio

O repositorio mp-skill/ e organizado em uma raiz curta com tres tipos de elementos: arquivos de documentacao na raiz, pastas de servico (docs, scripts, manifest) e a pasta skills/ dividida em buckets. Veja a arvore inteira em um lugar so:

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)

O bucket engineering/ guarda as skills que voce realmente puxa quando esta escrevendo, lendo ou revisando codigo. Sao 10 skills, cada uma com um proposito reduzido e um verbo claro. Se uma skill aqui nao for usada por semanas, ela desce para misc/ — engineering nao acumula bagagem.

O bucket productivity/ existe para skills que orquestram o trabalho: conduzir entrevistas, fechar sessoes, escrever, decidir. Nao tem nada de compilar codigo aqui. Sao 4 skills, todas usadas em ritmo semanal.

misc/ e o purgatorio. Skills que ja foram uteis, ainda servem em casos especificos, mas nao merecem espaco mental diario. Ficam aqui exatamente para nao poluir engineering ou productivity.

Os tres buckets privados. Tudo aqui esta no repo, mas nao aparece no README.md nem no plugin.json. Saber a diferenca entre eles evita poluir o catalogo publico com rascunhos ou ferramentas tao especificas que so funcionam na sua maquina.

Os tres `.md` da raiz tem publicos distintos. Trocar um pelo outro confunde tanto humano quanto agente. Memorize: README e para quem chega, CONTEXT e para entender intencao, CLAUDE e para o agente operar.

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

O Claude Code nao descobre suas skills por magia de filesystem. Ele le um manifest em .claude-plugin/plugin.json que lista, explicitamente, cada skill publica. Sem entrada no manifest, a skill existe no disco mas o agente nao a enxerga.

// .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 e um unico arquivo: SKILL.md, dentro de uma pasta com o nome da skill. Frontmatter YAML no topo, corpo em markdown abaixo. Nao tem mais arquivos obrigatorios — se voce precisar de referencias, coloque em references/ dentro da pasta.

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