AGENTS.md

Guidance for AI coding agents (Claude Code, Cursor, Gemini CLI, OpenCode, Copilot, etc.) when working with this repository.

Repository Overview

helderberto/agent-skills is a personal SDLC toolbelt for AI coding agents. Skills are packaged Markdown instructions that extend agent capabilities across the full lifecycle — from spec to ship.

Project Structure

skills/         → Core skills (one folder per skill, each with SKILL.md)
agents/         → Subagent definitions the skills fan out to (Claude Code only)
docs/           → Setup guides per agent (Cursor, Antigravity CLI, Gemini CLI, OpenCode, GitHub Copilot, Codex)
.claude-plugin/ → Plugin manifest + marketplace entry (Claude Code)
plugin.json     → Plugin manifest (Antigravity CLI)
.agents/plugins/ → Marketplace entry (Codex)
.plugin/        → Copy of .claude-plugin/plugin.json (Copilot CLI reads it first)

Integration Model

Different agents discover skills through different mechanisms. This repo supports all of them through one source of truth — the skills/ directory.

See docs/ for per-agent setup instructions.

OpenCode Integration

OpenCode uses a skill-driven execution model — the agent reads this file plus the skills/ directory and auto-routes user intent to the right skill.

Core Rules

• If a task matches a skill, you MUST invoke it
• Skills live at skills/<skill-name>/SKILL.md
• Never implement directly when a skill applies
• Always follow the skill instructions exactly — do not partially apply them
• Typed-only skills (disable-model-invocation: true) are rows that say suggest: name the command for the user to type, don't run it

Intent → Skill Mapping

Lifecycle Mapping (Implicit Flow)

When the user has a non-trivial task, suggest the flow commands in order. They are typed-only, so the user runs each one:

• TRIAGE → triage classifies the input, sizes it, and names the entry command; with no args it reports the current phase
• GRILL → grill interviews; settled terms go to the glossary via domain-modeling, decisions to to-adr
• SPEC → to-spec writes the spec from the conversation, no interview
• TICKETS → to-tickets slices the spec into tracer-bullet tickets, with architecture-audit or codebase-design as needed
• BUILD → build (one ticket per invocation, or --all), driven by tdd, source-driven, and check
• REVIEW → review (audits as parallel reviewers plus agent lenses: spec conformance with ticket checkboxes, standards, test effectiveness with changed-line coverage, floor-guard), covering a11y-audit, i18n, perf-audit, deps-audit, safe-repo, harden; feedback sorts existing reviewer comments
• SHIP → to-pr (gate, push, PR, CI watch); --safe adds a safe-repo scan before the push. Libraries then run to-release: draft release on the PR, tag and publish after the merge
• RETRO → retro, in the same session before /clear

Conventions

• Every skill lives in skills/<name>/SKILL.md (or <name>/SKILL.md if flat at root — see structure section)
• YAML frontmatter requires name and description
• Agents in agents/ are named *-auditor: read-only reviewers that preload, through skills: frontmatter, the skill holding their checklist when one exists
• Description starts with what the skill does. Model-visible skills follow with trigger conditions ("Use when..."); typed-only skills stop at one sentence
• Optional effort frontmatter (low/medium/high/xhigh/max) overrides reasoning effort for the turn the skill fires — set it only when the task deviates from the medium default
• No Claude Code hooks: they would block the user's own sessions. Safety checks run when the user asks (/hb:safe-repo, /hb:to-pr --safe)
• Supporting files split into subfolders: references/ (long-form docs loaded on demand), scripts/ (deterministic helpers), assets/ (templates/icons used in output). Split when SKILL.md exceeds ~150 lines
• .plugin/plugin.json is a byte copy of .claude-plugin/plugin.json: Copilot CLI checks it before the root plugin.json. The root plugin.json (Antigravity) allows only name and description, which must match. CI checks both
• Bump .claude-plugin/plugin.json version (semver) once per PR that changes a skill users see, so plugin consumers can track updates; then copy the file to .plugin/plugin.json. CI fails a PR that touches skills/ without the bump
• Release: /hb:to-release <PR> before the merge drafts the release; rerun it after the merge to tag vX.Y.Z on the merge commit and publish
• bash scripts/check.sh runs every CI check locally; bash scripts/audits.sh lists each skill's skills.sh audit status
• Untrusted text and verifying a skill's commands: docs/skill-conventions.md

Boundaries

This is a documentation-only project. It contains no application code, no runtime dependencies, no build step. Skills are pure Markdown.