helderberto/agent-skills

June 19, 2026 · View on GitHub

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.