📦 Module 2.1 — What is mp-skill

O mp-skill is the Portuguese version of the repository mattpocock/skills, created by Matt Pocock — the same person behind Total TypeScript, from the TypeScript articles that have probably already gotten you out of a jam, and from the newsletter AI Hero about AI applied to engineering.

Matt started putting these skills together after running into the failure modes recurring issues with Claude Code and Codex: the agent forgets context between sessions, invents APIs that don't exist, skips tests, makes unnecessarily large refactors, or simply "hallucinates" a plan and starts writing code that doesn't work.

Instead of accepting this as a "model limitation," Matt decided encode the solutions. Every time I discovered a pattern that avoided a failure mode, it became a skill. Every time I had to repeat an instruction manually in three consecutive sessions, it became a skill. The result is a repository that looks small but solves dozens of real problems.

Matt documents the project’s evolution in his newsletter. Worth reading — especially the posts where he explains why a skill was created (which agent error it tries to fix).

🔗 Newsletter: aihero.dev/s/skills-newsletter

Three adjectives define the project: small (small), composable (composable) and adaptable (adaptable). Each skill does one thing, does it well, and can be combined with others freely.

This philosophy is a direct answer to the "all-in-one" frameworks that emerged in the ecosystem — GSD, BMAD-METHOD, Spec-Kit. They work, but come with a cost: you adopt their entire process or none of it.

The repository groups skills into buckets (folders) according to maturity and purpose. This isn’t just an organizational detail—it defines which skills are publicly visible and which ones stay internal.

skills/
├── engineering/      # daily code work — TDD, code review, debugging
├── productivity/     # daily non-code workflow — handoff, grill-me
├── misc/             # kept around but rarely used
├── personal/         # tied to author's setup, not promoted
├── in-progress/      # drafts not yet ready to ship
└── deprecated/       # archived, kept for reference

The first three (engineering, productivity, misc) are public: appear in the project README and in the list .claude-plugin/plugin.json. The last three (personal, in-progress, deprecated) stay internal: exist in the repo, but aren’t officially exposed as plugin skills.

This structure keeps the repository honest: what’s promoted has been tested and Matt actually uses it; what’s in drafts is clearly identified; what’s been discontinued stays documented but doesn’t get in the way of people getting started.

GSD (Get-Stuff-Done), BMAD-METHOD, and Spec-Kit are popular frameworks for "agentic coding." They work — but they solve a different problem than skills do. It’s worth understanding the difference before choosing.

It's not “one is better than the other” — it's different problem. If you need a complete process from scratch, use a framework. If you already have a process and want to strengthen the agent’s weak points, use skills.

Skills aren’t exclusive to one profile. What changes is which skills go in and in what order. Three common profiles:

And what’s the typical adoption curve? It almost always follows the same order — install the repo, test a skill, see the benefit, add the next one. In two weeks, it becomes a workflow.

⏱️ Typical adoption timeline

The project is MIT. Practical translation: you can use, copy, modify, distribute, and sell it—in a personal project, at a company, or in a commercial product. The only requirement is to keep the copyright notice and license in the code.

Contribution model is fork-friendly. Matt accepts PRs, but expects each PR to be focused: a new skill, a fix to an existing skill, a docs improvement. Giant PRs ("I rewrote everything") tend to be rejected—not out of hostility, but because philosophy: the project is intentionally small.

# 1. Fork no GitHub, depois:
git clone https://github.com/SEU_USER/skills.git
cd skills
git checkout -b minha-skill

# 2. Criar a skill em engineering/ ou productivity/
mkdir -p skills/engineering/minha-skill
$EDITOR skills/engineering/minha-skill/SKILL.md

# 3. Registrar nos dois lugares públicos obrigatórios:
$EDITOR README.md                        # adicionar linha com link
$EDITOR .claude-plugin/plugin.json       # adicionar entrada
$EDITOR skills/engineering/README.md     # descrição de 1 linha no bucket

# 4. Commit + push + PR
git add .
git commit -m "feat: add /minha-skill"
git push origin minha-skill
gh pr create --base main

This repository (mp-skill, maintained by inematds) is a active fork of the mattpocock/skills with two extra goals:

In summary: mp-skill = mattpocock/skills + PT-BR + course. Same philosophy, same core set of skills, same bucket structure — just with the language barrier removed and instructional material added.