Claude Code skills best practices, derived from actually running them

Most best-practice lists are written from documentation. These eight were earned in a single long session installing 21 skills across 8 packages on a clean box — every rule below traces to something that happened, and links to the test where it happened.

1. Standardize on the one installer

Every package we tested installs through the universal skills CLI, most with no docs changes needed:

npx skills add owner/repo -a claude-code -y

First run costs a few seconds of bootstrap; every install after lands in 2–3 seconds. Learn its flags once (-s to pick skills from multi-packs, -g for user scope, -l to preview a repo's skills without installing) and you never read another install section.

2. Expect failures at use time, not install time

Across all eight packages we hit zero install failures — and three real use-time failures, all in the Remotion render pipeline. The pattern generalizes: installs are file copies; usage is where browsers, desktop apps, and render stacks live. Budget your validation time accordingly: a green install proves almost nothing. Run one minimal real task before you rely on a skill.

3. Verify the upstream is alive before adopting

The loudest lesson of our first batch: the 64.7k-star GSD repo is archived, with development moved — and the listings hadn't noticed. Thirty seconds on the repo page (archived banner? last push? open redirect notice?) before npx skills add protects you from building on a museum piece.

4. Know which of the three architectures you are adopting

Instruction-only skills (hallmark, obsidian-markdown) are zero-risk: markdown in, markdown out. Script-carrying skills (kill-ai-slop's scanner) add a small runtime surface you should skim before running. Runtime-backed skills (CodeDrobe's npm core, GSD's 71-command installer) are real software adoption — read what they write into .claude/ and know the uninstall story. Nothing wrong with any tier; the mistake is adopting tier three with tier-one casualness.

5. Mind the weight

Skills install per-project by default, and installs are full copies: video-shotcraft is 164MB of assets — per project. For heavy skills, install globally (-g) or accept the disk math knowingly. Check with du -sh .claude/skills/* once in a while; ours totaled a quarter gigabyte after one enthusiastic session.

6. Keep your installed set small and non-overlapping

By session end we had three anti-slop skills installed simultaneously — and generic design requests could plausibly match any of them. Skills compete for activation through their descriptions; near-duplicates shadow each other unpredictably. Pick one skill per job, remove the rest (npx skills remove), and your activation reliability improves for free (more on activation).

7. Pin what you tested

Skills ecosystems move weekly — two repos in our batch gained stars measurably during the day we tested them, and one moved orgs entirely within two months. Record the commit you installed (our test records carry it for every skill), and when a skill matters to production workflows, re-run your minimal task after updating rather than assuming compatibility.

8. Environment disclosure beats environment assumptions

Half the pain in public skill discussions is Mac-authored skills meeting Linux servers and vice versa. The good packages state their requirements plainly (obsidian-cli: "Requires Obsidian to be open"; CodeDrobe: platform-stamped adapter registry). When you publish, say what you tested on; when you adopt, check the gap between the author's environment and yours — that gap is where our only unresolvable test limits lived (CodeDrobe on headless Linux).