3 lessons from distilling staff-engineer workflows into 15 SKILL.md skills — 7 free, one-command install into Codex

[Hahaknight]

I distilled the workflows a staff engineer actually repeats every day — code review, debugging, test generation, spec-before-code, commit hygiene — into 15 skills in the open SKILL.md format. Seven of them are free and MIT-licensed, and they install into Codex with one command:

npx skills add Hahaknight/claude-skills-pro --agent codex

(Full disclosure up front: I originally wrote them for Claude Code, hence the repo name — but they're plain SKILL.md files with no Claude-specific anything, which is the point of the format. The same seven install into Gemini CLI, Cursor, opencode, and ~75 other agents the same way; I verified the Codex path end-to-end, along with Gemini CLI, goose, crush and Qwen Code, and the command above is the ecosystem-standard installer from vercel-labs/skills.)

The free seven:

skill	what it enforces
pr-reviewer	7-dimension review sweep (correctness, security, perf, contracts, errors, tests, maintainability); findings as blocker/should-fix/nit with file:line — never a rubber stamp
bug-hunter	reproduce → bisect → single hypothesis → minimal fix → regression test; explicitly bans shotgun patching
test-forge	boundary-value and failure-path tests, then a mutation self-check — kill the mutants or the tests aren't done
feature-spec	one page before any code: scope, non-goals, interface contract, edge-case table, test scenarios
commit-craft	splits tangled changes into logical commits, scans for leaked secrets, writes messages that explain why
changelog-release	semver bump derived from actual contract changes; release notes written for the consumer, not the commit log
ai-code-reviewer	reviews AI-written code against its specific defect profile — hallucinated APIs, plausible-but-wrong logic, silent behavior drift, invented requirements, over-engineering; never grades on style

Three things I learned writing these that apply to any SKILL.md-compatible agent:

1. The description field is the trigger surface, not documentation. The agent decides when to load the skill almost entirely from the frontmatter description. So the description must name the trigger conditions in the user's own words ("reviewing a pull request", "this diff before I commit") — not describe the skill's architecture. Vague descriptions = a skill that never fires.
2. Numbered steps beat prose. A workflow written as an ordered list gets followed in order; the same content as paragraphs gets summarized and half-skipped. The review skill's dimension sweep is a numbered checklist for exactly this reason.
3. Anti-patterns earn their space. Half of each skill is a DO-NOT section: don't comment on style when a linter exists, don't approve because tests pass, don't rewrite when a 3-line fix works. Telling the agent what not to do is what keeps it from the sycophantic default.

Reproducible check: run the install above, then open any repo and say "review this diff" — pr-reviewer loads and returns findings as blocker/should-fix/nit with file:line. If it doesn't fire, that's a bug I want to know about.

Repo with all seven + install paths: https://github.com/Hahaknight/claude-skills-pro — the other 8 (security audit, safe refactoring, zero-downtime migrations, perf profiling…) are in a paid pack if the free ones work for you, but the seven above are fully standalone and always will be.

Happy to answer anything about the format or the workflows.