🗂️ Repository structure

The repository mp-skill/ and is organized in a short root with three types of elements: documentation files at the root, service folders (docs, scripts, manifest) and the folder skills/ divided into buckets. See the entire tree in one place:

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)

The bucket engineering/ keeps the skills you actually reach for when writing, reading, or reviewing code. There are 10 skills, each with a focused purpose and a clear verb. If a skill here isn’t used by weeks, it moves down to misc/ — engineering doesn’t accumulate baggage.

The bucket productivity/ exists for skills that orchestrate the work: conduct interviews, close sessions, write, decide. There’s no code compilation here. These are 4 skills, all used weekly.

misc/ and purgatory. Skills that used to be useful and still apply in specific cases, but don't deserve daily mental space. They belong here specifically so they don't clutter engineering or productivity.

The three buckets private. Everything here is in the repo, but no appears in the README.md nor in the plugin.json. Knowing the difference between them keeps you from cluttering the public catalog with drafts or tools so specific they only work on your machine.

The three `.md` files in the root have distinct audiences. Swapping one for the other confuses both people and agents. Remember: README is for newcomers, CONTEXT is for understanding intent, and CLAUDE is for the agent to operate.

# 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 doesn't discover your skills by filesystem magic. It reads a manifest in .claude-plugin/plugin.json that explicitly lists every published skill. Without an entry in the manifest, the skill exists on disk but the agent can't see it.

// .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
  ]
}

Every skill is a single file: SKILL.md, inside a folder named after the skill. YAML frontmatter at the top, markdown body below. There are no other required files—if you need references, put them in references/ inside the folder.

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