yoelgal
UserPortable dev practices, packaged as skills - that run inside the coding agent you already use (Claude Code, Codex, pi, hermes). Not an agent, framework, or provider layer.
Categories
Indexed Skills (31)
packaging
Use when installing better-dev on a machine, cutting a release, or validating the package before distribution - covers the global per-host install, the Claude Code plugin manifest, and the release gate.
security-pass
Use when a diff or work-item touches an untrusted-input, auth, money/PII, file-upload, external-fetch, or LLM/agent surface and needs a security verdict - as /review's Security channel when the host ships no /security-review, as /plan-grill's abuse-case reference, invoked directly on a work-item, or when deciding whether some tool/log/model output is safe to act on.
codebase-audit
Use when someone points at an existing codebase, or one area of it, and wants to know what is worth doing before any single item is chosen - "audit this repo", "where's the leverage here", "what should we improve", "what's worth doing in this code". It ranks findings by leverage, hands the human one item, and builds nothing itself. For a chosen feature go to /plan-grill, for a reported symptom /diagnose, for structural orientation alone /codebase-map.
codebase-map
Use when you need structural orientation in an unfamiliar area before scoping, diagnosing, or reviewing - to find a symbol's callers and dependents, the real schema or API surface, or the blast radius of a change. Reach here on "who calls this", "what depends on this", or "what would this change break".
diagnose
Use when a bug, regression, crash, flaky test, or a report that "X is broken / throwing / failing / slow", "why is prod down", or "make it faster" needs root-causing before any fix - the fix-side entry into the work-item loop, where a symptom becomes a reproducible red signal and a root cause.
gauntlet
Use when the deliverable is a Gauntlet Loop prompt - "gauntlet this", "one-shot the whole thing", "write me a prompt that builds X in a fresh session against a real bar", or a front-end offered the gauntlet route on a greenfield ask and the user took it. The output is one handoff prompt for a fresh agentic session; the build itself never runs here. For a feature in an existing codebase reach for /plan-grill; for an epic that needs a shared foundation and parallelizable work-items, /groundwork.
graphify-wrapper-map
Use when a sprawling repo needs turning into a small, deliberate set of domains worth indexing - "index the repo", "build the code graph", "map this codebase" - the guided front door to /graphify-wrapper-index.
graphify-wrapper-setup
Use when a repo or machine needs graphify-wrapper wired up for the first time - installing the graphify CLI, seeding the per-repo registry, and picking a semantic backend - the one-time "set up graphify" step before any mapping or indexing.
graphify-wrapper-sync
Use when a worktree's domain graphs need building or refreshing - "sync the index", "rebuild the graph", "refresh graphify" - AST-only by default, --semantic for the full extract.
groundwork
Use when a greenfield project or a large new area/epic is starting and needs a shared foundation before feature work can safely fan out in parallel - the step above /plan-grill, which grills a single feature. For one feature reach for /plan-grill; for a bug, /diagnose.
onboard
Use when setting up better-dev in a repository for the first time, or re-running to wire in anything missing - greenfield or existing codebase. Also use when the repo has the better-dev tool installed but no .better-dev/ scaffold, no .better-dev/bin bridge, or no CLAUDE.md discovery block yet.
release-promotion
Use when the integration branch looks ready to ship and someone wants to promote it to the release branch and tag a release, when a just-tagged release needs its deploy verified live and healthy ("did the deploy land", "is prod healthy after the release"), when a bad release needs rolling back ("roll back the release", "revert prod"), or when a production incident needs a hotfix landed correctly. For the hotfix path specifically, this skill's hotfix notes carry the both-branches detail.
review
Use when a diff or branch needs an independent verdict inside the better-dev loop - the loop's gate after an implementer reports done, a whole-branch pass before a PR into the integration branch, or "review since X" against a fixed point - or when a colleague's inbound human-authored PR needs this repo's recorded policy applied over the host's PR-review mechanics. It is the loop's spec+standards evaluator; for a quick working-diff scan the host /code-review is fine.
worktree-branching
Use when a feature, fix, or chore work-item is about to start and needs its own isolated branch off the integration branch - before planning, diagnosis, or the autonomous loop runs - or when detecting whether such a worktree already exists. For removing one after merge, see this skill's teardown notes; for moving a half-finished item to a colleague or another machine, its handoff notes.
graphify-wrapper-index
Use when a named domain index needs registering or removing by hand - "add an index for services/backend", "drop that domain" - discovery via /graphify-wrapper-map, build via /graphify-wrapper-sync.
graphify-wrapper-query
Use when a question needs traversing a domain's graph to orient before grepping - "who calls this", "what depends on X", "what breaks if I change this", "shortest path between A and B", "explain this node", "where does this architecture concentrate". Builds the index on first use, so a cold repo is not a reason to skip it.
uninstall
Use when a person wants to remove better-dev - unwire a repo (drop the .better-dev/bin bridge and optionally the CLAUDE.md/AGENTS.md block) or remove the global per-host install. Never deletes your rules, overrides, or learnings unless you ask.
graphify-wrapper-status
Use when someone wants to see the registered domain indexes and their freshness for this worktree - "graphify status", "which graphs are built", "are my indexes stale".
bootstrap-hooks
Use when installing better-dev into a host so sessions and dispatched workers automatically notice the practices are present - wiring the SessionStart and SubagentStart awareness hooks, or adapting them for a non-Claude-Code host.
browser-capability
Use when a work item's done-criteria need a real browser - verify a page actually renders, run an end-to-end or visual check against the running UI, screenshot or inspect the live DOM - and no browser tool is wired yet. The worked example of sourcing a tool on a capability gap.
deploy-capability
Use when a product needs a live deploy surface that does not exist yet - "deploy this" or "get it live" on a greenfield product with no platform project, repo connection, domain, or per-environment config - when /release-promotion finds no recorded deploy rules and /guardrails-install has nothing to observe because nothing was ever created, or when a feature needs a product service provisioned (a database, an auth provider, transactional email, a domain). The deploy-surface sibling of /browser-capability - the same source-a-capability-on-a-gap practice.
design-brief
Use when a work item has real UI surface and its visual direction isn't settled - a request to make something look good, design a landing page or a screen, pick an aesthetic or a design system, fix a UI that reads as generic AI slop, or turn a vague "looks nice" into visual done-criteria the loop can verify. This is the design front-end `/groundwork` composes to settle foundation tokens and `/plan-grill` composes for a UI feature. Composes the host's design skill and sources one on a gap; hardcodes no aesthetic or stack. Not for auditing existing UI code against accessibility or style guidelines - that is a host design-review skill (`/web-design-guidelines`) or `/review`.
observability-install
Use when a repo that deploys has no standing production observability - no error tracking wired, no health endpoint, no alert channel that reaches a human when prod fails - or when a recorded obs-* rule reads none and that gap should now be filled. The runtime sibling of /guardrails-install - commit-time gates catch a broken commit before it lands; this catches a broken prod before a user reports it.
self-extension
Use when sourcing an existing skill has come up empty and a capability still needs filling, when a proven, repeatable workflow is worth capturing as a new reusable skill of its own, or when a recurring correction or re-recorded override looks like a defect in the shipped skill text rather than this repo's preference - to name it a library-defect candidate for the operator to carry upstream.
tool-sourcing
Use when a capability gap surfaces mid-work - the agent needs a tool or skill it doesn't have, or someone asks "is there a skill for X" / "find a tool that does X" - reach here before writing a new skill from scratch.
update
Use when the better-dev tool itself needs updating - "update better-dev", "is there an update", a session-start update or reonboard nudge naming /update, or after a git pull in the global clone to reconcile skill links and this repo's wiring.
autonomous-loop
Use when a planned feature or a diagnosed fix now has to be built to real, proven done - carrying one work-item through the implement-and-verify loop in its worktree, resuming it after an interruption, or restarting it when it stalls. Not for the planning or diagnosis that comes first.
orchestrating-agents
Use when development work is large, parallelizable, or benefits from fresh-context isolation - a broad review or audit, a migration, building or changing many components, or anything better split across fresh workers than done inline; also when an orchestrator needs the agent-agnostic verb for dispatching a fresh worker.
overrides
Use when the user pushes back on a better-dev default mid-flow - "just push to the PR, don't open a worktree", "use feat/ not feature/", "skip the grill here", "we never instrument prod" - to honor the correction now and, with a light confirm, make it the standing default for this project. Also when a mid-loop instruction changes what is being built rather than how - a correction to a decision the work-item's contract pins - to route it to the right disposition instead of absorbing it. Also the read-first layer every skill consults before applying a default.
pr-and-verify
Use when a change is ready to land - "ship it", "open a PR", "let's merge this", "raise the pull request" - or the loop has settled DONE / DONE_WITH_CONCERNS. Opens or refreshes the PR into the integration branch, reads CI truthfully, and verifies the contract's done-criteria end-to-end before it can merge. The clean review verdict is an entry precondition it checks, not a step it runs.
writing-skills
Use when authoring, reviewing, or refactoring any better-dev skill - writing or editing a SKILL.md, including when the self-extension flow generates a new one.
Bio shown is the top-scored skill's repo description as a fallback — real GitHub bios land in a future update.