helderberto/agent-skills

Personal SDLC toolbelt for AI coding agents — from spec 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.

  SPEC            PLAN            BUILD            TEST             REVIEW           SHIP
 ┌──────┐       ┌──────┐        ┌──────┐         ┌──────┐         ┌──────┐         ┌──────┐
 │ Idea │ ────▶ │ Spec │ ─────▶ │ Code │ ──────▶ │ Test │ ──────▶ │  QA  │ ──────▶ │  Go  │
 │Refine│       │Slices│        │ Impl │         │Verify│         │ Gate │         │ Live │
 └──────┘       └──────┘        └──────┘         └──────┘         └──────┘         └──────┘
 /hb:spec       /hb:plan        /hb:build        /hb:test         /hb:review       /hb:ship

Each phase has a dedicated workflow skill that orchestrates the smaller toolbelt skills underneath it. Type the spine in order, or let it chain — every skill auto-routes by description. Only the outward-facing steps that push work out of your hands (ship, create-pull-request) are gated against auto-triggering, so you always pull that trigger yourself.

Quick Start

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

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

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

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

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

You: /hb:plan dark-mode
AI:  Breaks the spec 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:test dark-mode
AI:  Runs validation (lint, types, tests) + coverage, then verifies
     plan checkboxes against the codebase. Reports progress + 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).

Skills

Skills come in two modes. User-invoked ones never auto-trigger (disable-model-invocation: true) — reserved for outward-facing, irreversible actions you must pull the trigger on yourself: ship and create-pull-request. Everything else is model-invoked: it auto-routes by description and stays callable explicitly as /hb:<name>. Model-invoked descriptions carry the trigger and anti-trigger clauses routing depends on; the two user-invoked ones keep a single what-it-does sentence, since trigger phrases are dead weight when nothing auto-routes.

Skills also carry an effort hint: mechanical ones (lint, commit, prose-fix) run at low reasoning effort, heavy ones (architecture-audit, harden, diagnose) at high or xhigh, and the rest at the implicit medium default. The override lasts only for the turn the skill fires — so complexity matches the task without you touching /effort.

SDLC workflow

The six-phase spine. Type each to advance, or let one phase chain into the next:

On-demand tools

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

Agents

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

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
├── agents/              subagent definitions (Claude Code only)
├── 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/specs/<slug>.md — specs from /hb:spec
• .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