No Personal Skills: Keep Them in the Repo

My general rule is nobody should have any personal skills and everything should be repo focused.

That way we can all improve it together, and we all know that everyone follows the same processes.

A skill in ~/.claude/skills is your own private copy of how the team works. Nobody else can see it, improve it or follow it. Put it in .claude/skills in the repo and it's everyone's.

Each repo owns its own process

Each repo defines how its PRs are created and reviewed. A shared, org-wide PR review skill has some value, but what to look out for is normally quite unique to the repository and the stack. So that knowledge belongs next to the code it's about.

Where each piece belongs

Not everything that could be a skill should be one. Here's where things go instead.

Personal skills ~/.claude/skillsWhere they live now. Move them into the repo.

Skills .claude/skills/In the repo, where everyone can improve them.

How PRs are written .github/pull_request_template.mdClaude uses it, and so do people opening PRs by hand.

Getting set up npm run setupA script, not a skill.

Review before a PR CLAUDE.mdSo nobody has to ask for it.

Checks inside a skill scripts, with testsThe skill calls them.

A PR template, not a PR skill

A GitHub PR template is a fairly standard file. Claude will use it. It also covers people opening PRs by hand.

It should remind Claude to explain the why, any background information, and not to talk about the code, because the code explains the code.

.github/pull_request_template.md · illustrative

<!--
Explain the why. Add any background information a reviewer needs.
Don't describe the code. The code explains the code.
-->

## Why

## Background

Setup is a script

In newer repos I use a setup step that checks your environment to see if it has all the right things, and then guides you through installing them or getting into permissions. It's npm run setup, the same for everyone.

scripts/setup.mjs · illustrative

// "setup": "node scripts/setup.mjs" in package.json
import { execSync } from 'node:child_process';
import { readFileSync } from 'node:fs';

const checks = [
  {
    name: 'Node matches .nvmrc',
    ok: () => process.version.startsWith('v' + readFileSync('.nvmrc', 'utf8').trim()),
    fix: 'Run `nvm use` and try again.',
  },
  {
    name: 'GitHub CLI signed in',
    ok: () => { execSync('gh auth status', { stdio: 'ignore' }); return true; },
    fix: 'Run `gh auth login`.',
  },
];

let failed = 0;
for (const check of checks) {
  let ok = false;
  try { ok = check.ok(); } catch {}
  console.log(`${ok ? '✓' : '✗'} ${check.name}${ok ? '' : `\n  ${check.fix}`}`);
  if (!ok) failed++;
}
process.exit(failed ? 1 : 0);

Review shouldn't need asking for

Running a review in an isolated sub-agent before opening a PR belongs in CLAUDE.md, so nobody has to remember to ask. We can automate all of that so people don't have to worry about it.

CLAUDE.md · illustrative

## Before opening a PR

Run a code review of the diff in a separate sub-agent that has none of this
session's context. Fix what it finds, then open the PR using
.github/pull_request_template.md.

Move the checks out of the markdown

When the checks a skill describes move into scripts the skill calls, the skill gets shorter and the checks get tests. As I put it about one of ours, the skill

loses 80 lines of markdown, but it gains 10 typescript tests.

Related: Give the Agent a Script, Not a Number, on skills and scripts that find things out instead of writing them down.