PTENES
MODULE 2.3

⚙️ Installation and setup

30 seconds from zero to your first /grill-me. Setup for mattpocock/skills no mystery: prerequisites, installer, agent selection, issue tracker setup, and validation.

9
Sections
30s
Minimum
Basic
Level
Practice
Type
1

📋 Prerequisites

Before running any command, make sure your machine has the right environment. The Matt Pocock's skills run on runtimes that make specific assumptions—skipping this step is the #1 reason installations fail with cryptic messages.

🎯 The essentials in 3 items

  • • Claude Code (claude.com/claude-code) or Codex CLI installed and logged in.
  • • Node.js 18+ on the PATH — used by npx that downloads the installer.
  • • One working repository open (or new folder) — the installer writes to .claude/ e docs/agents/.

✓ Supported configurations

  • ✓Claude Code (desktop or terminal)—plugin mode
  • ✓Codex CLI — file mode (skills/ in the repo)
  • ✓macOS, Linux, WSL2 (native Windows via WSL)
  • ✓Node 18 LTS, 20 LTS, 22 LTS
  • ✓Git repositories (recommended) or standalone folders
  • ✓Issue trackers: GitHub, Linear, local (.scratch/)

✗ Not supported (yet)

  • ✗Native Windows without WSL—paths break
  • ✗Node 16 or earlier — npx incompatible
  • ✗Jira, GitLab Issues, Notion (planned, not ready)
  • ✗Editors like Cursor/Continue (skill is Claude/Codex)
  • ✗No write permission in the project (read-only mounts)
  • ✗Companies that block the npm registry (without a proxy)

💡 Quick check (10 seconds)

# Paste into the terminal before continuing: node --version # must return v18+ claude --version # or: codex --version git status # must be inside a repo

If any of them fail, fix it before before running the installer. Most reported bugs are caused by missing prerequisites.

2

📦 Installation via skills.sh (recommended)

O skills.sh is the official path. One command, no cloning a repo, no editing JSON by hand. It detects the runtime (Claude Code or Codex), copies the right files to the right place, and opens a selection screen.

# At the root of the project where you want to use the skills: npx skills@latest add mattpocock/skills

🔧 What the installer does behind the scenes

  • 1.Downloads the package skills via npx (doesn't install globally).
  • 2.Detects whether you’re in Claude Code (looks for .claude/) or Codex (looks for .codex/).
  • 3.Does git clone --depth 1 of mattpocock/skills in a temporary cache.
  • 4.List of available skills (engineering/, productivity/, misc/) with checkboxes.
  • 5.Copy the selected ones to .claude/skills/ (or the Codex equivalent).
  • 6.Register the skills in the plugin.json or in the local configuration.

Doesn't touch anything outside these two directories. Reversible: deleting the skills folder restores the original state.

3

🎛️ Selecting skills in the installer

After running the command, the installer switches to interactive mode. 4 visual steps until you confirm — you can't go wrong if you follow the screen. Most importantly: mark /setup-matt-pocock-skills at this stage, because it's what will configure everything later.

1

Run the command

Terminal open at the root of the repo

You type npx skills@latest add mattpocock/skills. O npx downloads the installer (~300KB) and runs in ~5 seconds the first time.

Expected output: "Fetching mattpocock/skills..." followed by "Detected runtime: claude-code".

2

Selection screen appears

Interactive checklist

You see all the skills grouped by bucket: engineering/ (handoff, ica, grill-me…), productivity/ (setup-matt-pocock-skills, triage-issues…), misc/. Use the arrows to navigate and space to mark.

Skills personal/, in-progress/ e deprecated/ don’t appear — protecting the user from drafts.

3

Choosing agents — mark /setup-matt-pocock-skills

Critical step — don’t skip

Mark /setup-matt-pocock-skills as required. This agent runs once after installation and generates the configuration files (labels, doc paths, issue tracker integration). Without it, the other skills work but remain disconnected from your workflow.

Minimum recommendation: /setup-matt-pocock-skills, /grill-me, /handoff. Then you add the rest.

4

Confirm and review the diff

Everything written at once, atomic

You press Enter. The installer shows a summary: "5 skills installed → .claude/skills/". If you use Git, do git status to see everything that was added. It’s recommended to commit right away as "chore: install matt-pocock skills".

If something goes wrong along the way, the installer won't leave a partial state: either everything is added, or nothing is.

4

🪄 Running /setup-matt-pocock-skills

With the skills installed, open Claude Code (or Codex) inside the same project and trigger the setup agent. It does one short interview (3–4 questions) and generates the configuration files in the right format for your workflow.

# In the Claude Code prompt: /setup-matt-pocock-skills Agent: I’ll configure your skills. Three quick questions. Agent: 1) Which issue tracker do you use? a) GitHub Issues b) Linear c) Local (.scratch/ in the repo) You: a Agent: 2) Repo: "my-org/my-app"? (detected from git remote) You: yes Agent: 3) Which labels does your team use for triage? (enter them separated by commas, or press Enter for the default) You: bug, enhancement, question, docs Agent: 4) Where should I save agent docs? Default: docs/agents/ — confirm? (y/n) You: y Agent: Configuring... - Creating docs/agents/triage-labels.md - Creating docs/agents/issue-tracker.md - Updating .claude/skills/triage-issues/config.json Agent: Done. Test with /grill-me or /triage-issues.

💡 Recommendations by team size

  • Solo / side project: local issue tracker (.scratch/). No friction, no external dependencies.
  • Small team (2–5 devs): GitHub Issues. That’s where the code already lives, and everyone has access.
  • Medium/large team (6+): Use Linear if the company already pays for it. Otherwise, GitHub Projects.
  • Regulated/closed company: local + manual sync. Avoids exposing internal decisions in a public SaaS.
5

🗂️ Configuring the issue tracker

The choice of issue tracker shapes the rest of the flow. Skills like /triage-issues e /handoff need to know where to create/read tickets. The three modes cover 95% of cases.

✓ When to use each one

  • GitHub Issues — public/private repo, the whole team has access, integrates with PRs.
  • Linear — a paid organization using Linear that wants structured cycles/projects.
  • Local (.scratch/) — solo, offline, exploratory. No cost, no auth.

✗ When NOT to use

  • GitHub — if the repo is closed but the tracker needs to work across repos.
  • Linear — if you're on your own or still validating an idea (overkill).
  • Local — in teams of 3+ people (each person will have a .scratch/ different, without sync).

The generated configuration lives in docs/agents/issue-tracker.md. Example generated by setup when you choose GitHub:

# docs/agents/issue-tracker.md tracker: github repo: my-org/my-app default_assignee: "@me" auth: gh-cli # use `gh auth status` to check queries: open_bugs: "is:open label:bug" needs_triage: "is:open no:label" my_work: "is:open assignee:@me" create_template: body_prefix: "<!-- generated by mattpocock/skills -->" add_labels_on_create: ["triage"]
6

🏷️ Triage labels

The labels are the vocabulary that connects humans and agents. If you say "this is a bug" and the agent says "this is a defect", you duplicate tickets. The setup generates a mapping role → label string for standardization.

Each semantic role (what the ticket represents in the workflow) becomes a canonical string. You change the strings to match your team’s vocabulary, but keep the roles:

# docs/agents/triage-labels.md labels: # --- role: issue type --- bug: "bug" # bug in existing behavior feature: "enhancement" # request for new behavior docs: "docs" # documentation improvement question: "question" # question, not actionable yet # --- role: status in the workflow --- needs_triage: "triage" # just came in and hasn't been evaluated yet blocked: "blocked" # waiting on something external ready: "ready" # prioritized and ready to be picked up # --- role: priority --- p0: "priority:p0" # incident, stop everything p1: "priority:p1" # high priority for the sprint p2: "priority:p2" # when there's time color_hints: bug: "#d73a4a" enhancement: "#a2eeef" docs: "#0075ca"

📊 Why map role -> string?

Because the internal name (bug) is stable in the agent’s code, but the string visible to the user ("defeito", "erro", "bug") varies across teams.

Renamed the label on GitHub? Edit one line here. The agent keeps working. Without this indirection, you break all the prompts every time the team changes its vocabulary.

7

🔧 Manual installation (without skills.sh)

If your company blocks npm registry, or you want full control over what goes into the repo, you can everything by hand. It’s more work, but it works in any environment.

# 1) Clone the skills repo to a separate location git clone https://github.com/mattpocock/skills.git ~/src/mp-skills # 2) Create a skills directory in your project (if it doesn't exist) mkdir -p .claude/skills # 3) Symbolic link (recommended — receives updates from git pull) ln -s ~/src/mp-skills/skills/engineering/grill-me .claude/skills/grill-me ln -s ~/src/mp-skills/skills/engineering/handoff .claude/skills/handoff ln -s ~/src/mp-skills/skills/productivity/setup-matt-pocock-skills .claude/skills/setup # 4) OR copy (snapshot, doesn't receive updates) cp -r ~/src/mp-skills/skills/engineering/grill-me .claude/skills/ # 5) Register in plugin.json (if applicable to your setup) cat .claude/plugin.json # adds the skills to the "skills": [...] array # 6) Restart Claude Code to load claude restart

🧭 Symlink vs. copy

  • Symlink: one git pull in the clone, updates everything. Good if you always want the latest.
  • Copy: freeze the version. Good for a team that needs a stable skill and PR reviews.

After this manual setup, you still need to run /setup-matt-pocock-skills inside Claude Code to generate the configuration files. Manual installation only puts the files in place — the configuration is separate.

8

✅ Verifying that everything works

Installed, configured — now prove it's alive. /grill-me is the fastest test: it makes the agent ask questions about the current problem instead of answering directly. If this skill loaded, they all loaded.

# In Claude Code, inside the project: /grill-me I want to add authentication to the app Agent: Before suggesting code, let me understand: 1. Which provider have you decided on? (Auth0, Clerk, custom, NextAuth...) 2. Web, mobile, or both? 3. Do you already have users in production? (determines migration vs. greenfield) 4. Email/password, social, magic link, or a combination? 5. What are your session requirements? (JWT, cookie, refresh tokens?) # If this appears, it's working. If the agent # respond directly with code; the skill didn't load.

📋 Validation checklist

  • ✓/grill-me <qualquer coisa> asks questions instead of giving direct answers
  • ✓/handoff generates structured markdown instead of free-form prose
  • ✓Files docs/agents/issue-tracker.md e triage-labels.md exist
  • ✓.claude/skills/ has the folders for the selected skills
  • ✓git status shows the new files — ready to commit
  • ✓Restarted Claude Code once to make sure the files were read
9

🩺 Troubleshooting

Almost everything that goes wrong falls into three buckets. Identify the symptom, apply the fix, move on.

✗ Common symptoms

  • Skill doesn’t appear when typing / — empty autocomplete or built-ins only.
  • Conflict with another skill — two skills with the same name or trigger, message "ambiguous command".
  • Plugin won't load — Claude Code opens, but no custom skills work; error in the startup log.
  • Agent responds directly without running the skill — you type /grill-me and it only responds like a regular chat.

✓ Solutions

  • Restart — 70% of cases. Claude Code only reads .claude/ at startup.
  • Rename the conflicting skill or disable the duplicate in the plugin.json.
  • Validate JSON — cat .claude/plugin.json | jq. A trailing comma breaks everything.
  • Force a skill prefix in the prompt: /grill-me has to be the first word in the message.

🛠️ Recipe: skill doesn't appear

  1. Check whether the directory exists: ls .claude/skills/grill-me.
  2. Check whether it has SKILL.md inside with valid frontmatter (name, description).
  3. Restart: close Claude Code completely (not just the window) and reopen it.
  4. If it still doesn't appear, check the logs in ~/.claude/logs/ — look for "skill load error".
  5. Last resort: delete the skill folder, run npx skills@latest add again.

⚠️ Attention to permissions

If you ran npx with sudo sometimes, the files may have been left owned by root, and Claude Code (running as your user) can't read them. Fix it with: sudo chown -R $USER .claude/. Never run the installer again with sudo.

🎓 Module Summary

✓
Prerequisites — Claude Code (or Codex) + Node 18+ + a repo with write permission. Without that, nothing runs.
✓
Installation via skills.sh — npx skills@latest add mattpocock/skills. One command copies files, registers the plugin, and is reversible.
✓
4 steps in the installer — run → screen → mark /setup-matt-pocock-skills → Confirm.
✓
Setup interviews you — issue tracker, labels, doc paths. Generates versionable files in docs/agents/.
✓
Labels = role -> string — indirection that protects your prompts when the team’s vocabulary changes.
✓
Verified with /grill-me — if it asks questions instead of answering directly, everything is alive.
✓
Troubleshooting — 70% of problems are solved by restarting Claude Code. Invalid JSON and permissions cover the rest.

Next Track:

Track 3 — Practice: running real skills in real projects, /handoff between sessions, /grill-me for architecture, advanced triage workflows.

← Module 2.2 Go to Track 3 →