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

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:spec, /hb:tdd, /hb:ship. Most skills also auto-trigger from natural language ("review this PR", "check accessibility", etc.) based on their description.

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.

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.

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.

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

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).

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 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.

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/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