helderberto/agent-skills

Personal SDLC toolbelt for AI coding agents — from PRD to ship.

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.

  DEFINE          PLAN            BUILD            VERIFY            REVIEW           SHIP
 ┌──────┐       ┌──────┐        ┌──────┐         ┌──────┐         ┌──────┐         ┌──────┐
 │ Idea │ ────▶ │ Spec │ ─────▶ │ Code │ ──────▶ │ Test │ ──────▶ │  QA  │ ──────▶ │  Go  │
 │Refine│       │ PRD  │        │ Impl │         │Debug │         │ Gate │         │ Live │
 └──────┘       └──────┘        └──────┘         └──────┘         └──────┘         └──────┘
 /hb:prd        /hb:plan        /hb:build        /hb:verify-plan  /hb:review       /hb:ship

Each phase has a dedicated workflow skill that orchestrates the smaller toolbelt skills underneath it. Workflow skills are designed to be invoked explicitly; everything else auto-routes by description.

---

Quick Start

Claude Code (recommended)

Install via the marketplace:

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

After install, skills are available as /hb:<skill-name> — e.g. /hb:prd, /hb:tdd, /hb:ship. Most skills also auto-trigger from natural language ("review this PR", "check accessibility", etc.) based on their description.

Gemini CLI

Install as native skills:

gemini skills install https://github.com/helderberto/agent-skills.git --path skills

Skills are auto-discovered and routed by description. See docs/gemini-cli-setup.md.

OpenCode

Clone and point OpenCode at the workspace — AGENTS.md plus the skills/ directory drive auto-routing:

git clone https://github.com/helderberto/agent-skills.git

Open the project in OpenCode. The .opencode/skills symlink and root AGENTS.md are already wired. See docs/opencode-setup.md.

Cursor

Clone the repo, then copy individual skills into .cursor/rules/:

git clone https://github.com/helderberto/agent-skills.git
cp agent-skills/skills/tdd/SKILL.md .cursor/rules/tdd.md
cp agent-skills/skills/code-review/SKILL.md .cursor/rules/code-review.md

See docs/cursor-setup.md for the recommended starter set.

---

Workflow example — full SDLC walkthrough

A non-trivial feature flows through all six phases. Each workflow skill is one invocation:

You: /hb:prd add dark mode support
AI:  Interviews, scans the codebase, writes .specs/prds/dark-mode.md.
     Run /hb:plan dark-mode next?

You: /hb:plan dark-mode
AI:  Breaks the PRD into phased vertical slices.
     Writes .specs/plans/dark-mode.md.

You: /hb:build dark-mode
AI:  Implements next incomplete phase. TDD loop, lint, type-check.
     Marks checkboxes in the plan. Offers a commit.

You: /hb:verify-plan dark-mode
AI:  Verifies plan checkboxes against actual codebase.
     Reports total progress and remaining blockers.

You: /hb:review
AI:  Detects what changed, runs relevant audits in order
     (code-review, a11y-audit, safe-repo, perf-audit, deps-audit, ...).
     Consolidates findings into Critical / Important / Suggestion.

You: /hb:ship
AI:  Pre-launch gate (validate-code + safe-repo --diff).
     Atomic commits, push current branch.
     /hb:ship --fast skips the gate (hotfix only).

For quick standalone tasks, you don't need the workflow — just describe what you want and the relevant skill triggers ("write tests for X", "audit deps", "create an ADR for Y").

---

Skills

Skills come in two modes. User-invoked ones you type explicitly (/hb:<name>) and never auto-trigger (disable-model-invocation: true) — the SDLC workflow spine plus deliberate, heavyweight, or interactive tools. Their descriptions stay a single what-it-does sentence: trigger phrases are dead weight when nothing auto-routes, yet still cost context tokens every turn. Model-invoked ones auto-route by description (and are still callable explicitly) — focused capabilities the agent reaches for based on the task, so their descriptions carry the trigger and anti-trigger clauses that routing depends on.

User-invoked

The six-phase SDLC workflow — type each to advance:

Skill	Phase	What it does
prd	DEFINE	Interview + codebase scan → structured PRD in .specs/prds/<slug>.md
plan	PLAN	Turn PRD into multi-phase implementation plan (tracer-bullet vertical slices)
build	BUILD	Implement next incomplete phase of a plan with feedback loops
verify-plan	VERIFY	Verify plan checkboxes against codebase; mark or unmark
review	REVIEW	Detect scope, run relevant audits, consolidate findings
ship	SHIP	Pre-launch gate + atomic commits + push (--fast to skip gate)

Plus deliberate tools you invoke on demand:

Skill	What it does
architecture-audit	Surface architectural friction, propose refactors toward deep modules as RFCs
prototype	Build a throwaway prototype — terminal app or toggleable UI variations — to flesh out a design
grill-me	Stress-test a plan or design through relentless interview (runs grilling)
teach	Stateful teaching workspace — lessons, references, learning records tied to a mission
handoff	Compact the current conversation into a handoff doc for a fresh agent
create-pull-request	Open a GitHub PR with structured body
create-skill	Author a new skill with proper structure

Model-invoked

Focused capabilities the agent applies automatically based on the task (also callable explicitly). Expand a group to browse.

Build & test

Skill	What it does
tdd	Red → green → refactor loop for any new logic
source-driven	Implement using official docs for exact dependency versions
fortify	Split large functions, add edge-case coverage, backfill missing tests
e2e	Write end-to-end tests for user flows using Cypress

Verify

Skill	What it does
coverage	Test coverage for unstaged changes
validate-code	Auto-fix lint, verify types, run tests
lint	Run linting and formatting checks
diagnose	Disciplined diagnosis loop for hard bugs and perf regressions
visual-validate	Browser-driven UI validation via Chrome DevTools or Playwright MCP

Review & audit

Skill	What it does
code-review	Five-axis review of a PR (correctness, readability, architecture, security, performance)
a11y-audit	Accessibility compliance audit (WCAG)
i18n	Find hardcoded strings, check translation coverage
perf-audit	Frontend bundle size and performance audit
deps-audit	Check dependencies for vulnerabilities (npm)
safe-repo	Sensitive data scan; --diff mode for in-flight changes
harden	Proactive security hardening at trust boundaries (OWASP-style)

Git & release

Skill	What it does
commit	Single commit following repository style
atomic-commits	Group unstaged changes into atomic commits by concern
create-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
grilling	Relentless plan/design interview, one question at a time (engine behind grill-me)

Session, meta & writing

Skill	What it does
brief	Session briefing — active features, progress, suggested focus
explain-code	Explain code with visual diagrams and analogies
setup-pre-commit	Configure Husky + lint-staged for commit-time gates
caveman	Ultra-compressed communication mode (cuts ~75% tokens)
prose-fix	Fix typos, dashes, formatting in markdown
revise	Structurally edit and improve article drafts

---

Structure

agent-skills/
├── .claude-plugin/      Plugin manifest + marketplace entry (Claude Code)
├── .opencode/skills →   Symlink to skills/ for OpenCode discovery
├── skills/              one folder per skill, each with SKILL.md
├── docs/                Skill anatomy + per-agent setup guides
├── AGENTS.md            Intent → skill mapping (drives OpenCode auto-routing)
├── CONTRIBUTING.md      How to contribute new skills or improvements
├── LICENSE              MIT
└── README.md

Artifact convention

Workflow skills write structured artifacts to .specs/:

• .specs/prds/<slug>.md — PRDs from /hb:prd
• .specs/plans/<slug>.md — phased plans from /hb:plan

The .specs/ directory is local-first. Add it to .gitignore if you prefer specs as scratch space, or commit it if you want specs as versioned project documentation.

---

Contributing

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

---

License

MIT © Helder Burato Berto