helderberto/agent-skills

Personal SDLC toolbelt for AI coding agents — from idea to PR.

A collection of skills that encode the workflows, quality gates, and engineering practices I use day-to-day. Pure Markdown, zero runtime deps, installable as a Claude Code plugin or copied into any agent that reads instruction files.

TRIAGE    GRILL    SPEC       TICKETS       BUILD    REVIEW    SHIP     RETRO
triage ─▶ grill ─▶ to-spec ─▶ to-tickets ─▶ build ─▶ review ─▶ to-pr ─▶ retro

Type /hb:<command> for each step; /hb:triage tells you where to enter. The SHIP phase is /hb:to-pr: gate, push, PR, CI watch. Flow commands never chain on their own and never call each other. Each ends with a filled-in Next: /hb:<cmd> <args> line, so you always pull the trigger yourself.

Full walkthrough and the .specs/ artifact layout: docs/workflow.md.

---

Quick Start

Fastest path — any agent, one command. The skills CLI installs into 70+ agents (Claude Code, Cursor, Codex, Copilot, OpenCode, and more):

npx skills add helderberto/agent-skills             # install all skills
npx skills add helderberto/agent-skills --list      # browse before installing
npx skills add helderberto/agent-skills --skill tdd # one skill

It installs skills only; the Claude Code plugin also ships the agents/ subagents. Pick one install per agent, or every skill shows up twice.

Prefer a native integration? Pick your tool below.

Claude Code (Recommended)

Marketplace install:

/plugin marketplace add helderberto/agent-skills
/plugin install hb@helderberto-skills

Third-party marketplaces don't auto-update: turn it on in /plugin → Marketplaces.

SSH errors on install → git config --global url."https://github.com/".insteadOf git@github.com:.

Agent	Install	Guide
Codex	codex plugin marketplace add helderberto/agent-skills → codex plugin add hb@helderberto-skills	codex-setup.md
Cursor	Clone, then rsync -a agent-skills/skills/ .cursor/skills/	cursor-setup.md
Antigravity CLI	agy plugin install https://github.com/helderberto/agent-skills	antigravity-setup.md
Gemini CLI	gemini skills install https://github.com/helderberto/agent-skills.git --path skills	gemini-cli-setup.md
GitHub Copilot	copilot plugin marketplace add helderberto/agent-skills → copilot plugin install hb@helderberto-skills	copilot-setup.md
OpenCode	Clone, copy skills/* to .opencode/skills/, paste the OpenCode section of AGENTS.md into yours	opencode-setup.md
Other agents	npx skills@latest add helderberto/agent-skills -a <agent> (devin, windsurf, amp, pi; omit -a to choose)	—

Codex invokes skills as $hb:<skill>; the others use /hb:<skill>.

---

Skills

Typed as /hb:<name> or triggered from the task. Naming, invocation tiers, and effort hints: docs/skill-conventions.md.

SDLC workflow

The flow, one typed command per step:

Skill	Phase	What it does
triage	TRIAGE	Classify any input (idea, bug, ticket, PR, stack trace), size it, name the command to type; no args → where you are
grill	GRILL	Interview in rounds over the design-tree frontier, each question with a recommended answer
to-spec	SPEC	Settled conversation + codebase scan → structured spec in .specs/specs/<slug>.md
to-tickets	TICKETS	Slice a spec into tracer-bullet vertical slices with blocking edges
build	BUILD	Implement the next unblocked slice test-first via tdd, with feedback loops; --all fans every ticket out to parallel implementer subagents after one approval
review	REVIEW	Fan out parallel reviewers (scope-detected audits + agent lenses incl. spec conformance, standards, coverage, and a quality-bar check), consolidate into one verdict
to-pr	SHIP	Gate (check, ADR check), push, open a GitHub PR on the repo's template or the default, every field written by the model with no questions: Summary with a visual (diagram, diff sketch, or tree), Before/After evidence, merge danger (one-way or two-way door, blast radius); watch CI, debug on red (max 2); --safe runs safe-repo before the push, --skip-ci marks the HEAD commit [skip ci] and skips the watch, --diagram[=<type>] makes the visual a mermaid diagram, typed by the change unless given
retro	RETRO	Retrospective on a session — suggests navigation pointers, checks, coding standards, steering fixes; mechanical mistakes become checks

On-demand tools

Focused capabilities the agent applies based on the task; both-tier ones are also typed as /hb:<name>. Expand a group to browse.

Build & test

Skill	What it does
tdd	Red → green → refactor loop for any new logic, unit to end-to-end
source-driven	Implement using official docs for exact dependency versions
refactor	Behavior-preserving improvement: split large functions, backfill tests, simplify (Chesterton's Fence)

Verify

Skill	What it does
check	Auto-fix lint, verify types, run tests; --check writes nothing
debug	Disciplined diagnosis loop for hard bugs and perf regressions

Review & audit

Skill	What it does
code-review	Correctness lens used by build and review: a PR or diff against an approval standard — correctness, security, performance, a Fowler smell baseline; Critical→Nit severities
visual-review	Render a PR diff as an annotated HTML page — each hunk linked to a design/simplification principle with a suggested rewrite; --ui checks a UI change in a real browser via Chrome DevTools or Playwright MCP
feedback	Triage existing PR review comments (Copilot + human), verify against code, classify Address/Skip/Optional/Discuss
a11y-audit	Accessibility compliance audit (WCAG)
i18n	Find hardcoded strings, check translation coverage
perf-audit	Frontend bundle size and Core Web Vitals risks; no metric without a measurement
deps-audit	Check dependencies for vulnerabilities (npm/pnpm/yarn/pip/go/cargo)
safe-repo	Sensitive data scan; --diff [<base>] scopes to a branch's changes
harden	Proactive security hardening at trust boundaries (OWASP-style), including LLM features

Git & release

Skill	What it does
commit	Group unstaged changes into atomic commits by concern (repository style)
to-adr	Record a 1–3 sentence Architecture Decision Record

Design & discovery

Skill	What it does
codebase-design	Shared deep-module vocabulary for designing or improving an interface
frontend-ui-engineering	Front-load UI construction decisions — prop API, state placement, required states, a11y by construction
architecture-audit	Surface architectural friction in git hot spots, propose refactors toward deep modules as RFCs; --html for a before/after report
domain-modeling	Build and sharpen the project's ubiquitous language and glossary
research	Investigate a question against primary sources; capture cited findings as Markdown
prototype	Build a throwaway prototype — shareable HTML logic demo or toggleable UI variations — kept on a prototype/<name> branch
debate	Is a risky change or PR worth it? Advocate, skeptic, and neutral investigator argue it over two rounds, then one recommendation

Session, meta & writing

Skill	What it does
guide	Which skill fits? A map of the flow, on-ramps, and standalone skills, plus when to continue, /clear, /hb:handoff, or /compact
handoff	Compact the current conversation into a handoff doc for a fresh agent
teach	Stateful teaching workspace — lessons, references, learning records tied to a mission
wait-what	Last message didn't land — re-pitch it with context, in Simplified Technical English and glossary terms
zoom-out	Explain code with visual diagrams and analogies
create-skill	Author a new skill with proper structure
revise	Restructure article drafts, or polish any markdown (typos, dashes, filler)

---

Agents

Subagents the skills fan out to for independent, read-only perspectives (e.g. /hb:review spawns test-auditor as a lens). Bundled with the plugin, so installing hb ships them too. Claude Code only — other agents consume skills/ and ignore this directory.

Agent	Purpose
test-auditor	Test effectiveness beyond coverage: weak assertions, missing edge scenarios, surviving mutants
security-auditor	Exploitable flaws at trust boundaries, STRIDE per boundary; preloads harden
perf-auditor	Bundle size and Core Web Vitals risks, graded for review; preloads perf-audit
parity-auditor	Audit code migrations for missing functionality

---

Contributing

PRs welcome. See CONTRIBUTING.md for workflow, conventions, and where to start.

---

License

MIT © Helder Burato Berto