Agent skill

Installation

$ npx gbs-add-block@latest -skill

The block writes the skill at the root of the project you run it in — not into component-lib/ — in the place each supported agent looks. Commit the result so that everyone on the team, and CI, gets the same guidance.

-a -skill and -a skill do the same thing, and it can be combined with a component install:

$ npx gbs-add-block@latest -a DataGrid -beta -skill

An agent that has never seen this library will otherwise guess. It will write import { Button } from "gbs-add-block", which does not resolve, because the CLI copies source into your repo rather than publishing a package to import from. It will reach for onChange on a Switch, which the type omits. It will wrap an Input in its own <label> and break the wiring the component already does. The skill is the file that stops all three.

What lands in your repo

.gbs/                                canonical, and what the GBS agent reads
  .install-manifest.json
  skills/gbs-components/
    SKILL.md                         always in the agent's context
    references/
      install.md                     CLI flags, folder names, shared/
      forms.md                       text and choice fields
      pickers.md                     Select, MultiSelect, DatePicker, FileUploader
      overlays.md                    Modal, dialog, Popover, Menu, Tooltip
      toaster.md                     toast() and Toaster
      data-grid.md                   columns, imperative API, export
      data-display.md                Card, Tabs, Accordion, Badge, Avatar, Progress
      styling.md                     --gbs-* tokens, layers, slots, data-*
      accessibility.md               what is supplied, what you must add

.claude/skills/gbs-components/       Claude Code
.agents/rules/gbs-components.md      Antigravity
AGENTS.md                            Codex — a marked block, nothing else touched

Only SKILL.md is loaded up front. It is an index: the import rule, the handful of rules that are most often got wrong, a one-line inventory of every component, one complete example, and a list of things not to do. The agent opens a reference file only when the task needs that depth, so a small change does not drag eleven thousand characters of DataGrid documentation into the conversation.

What it teaches

The rules that earn their place are the ones a reasonable agent gets wrong by default.

Imports. That there is no package to import from; that components come from component-lib/<folder> plus that folder's styles.css; that the folder is the lowercased name except for data-grid, date-picker, file-uploader, number-input and radio-group; and that anything deeper than the barrel is internal.

Change handler names. This is the single most common mistake, because nothing in the naming predicts which one a component uses:

Fields own their own markup. label, description and error are props. error also sets aria-invalid and appends the message to aria-describedby. An agent that hand-rolls a <label htmlFor> around the control is fighting wiring that is already there.

Styling goes through the library's seams — --gbs-* on :root for the palette, classNames slot maps for inner parts, data-* attributes for state — rather than !important or selectors written against internal class names.

The two things that must be mounted once: <Toaster /> and <DialogHost />. Without them toast() and dialog.confirm() do nothing, silently.

Composition rules, such as Tab and TabPanel throwing outside <Tabs>, AccordionItem outside <Accordion>, and MenuItem outside <Menu>.

Keeping it current

Re-run the same command to update:

$ npx gbs-add-block@latest -skill

The installer records a sha256 of every file it writes — across all four locations — in .gbs/.install-manifest.json. On the next run it compares, and it will not replace a file you have edited:

✗ These skill files have local changes:
  - .claude/skills/gbs-components/references/forms.md

  Updating the skill would replace them. Re-run with --force to do that,
  or move your own guidance into a separate skill folder first.

--force overwrites anyway. Files an older version installed and that you have not touched are cleaned up on update.

Which agents read it

No agent reads all of these locations, so the CLI writes one copy per agent from the same source. They differ only in where they sit and what their front matter is called.

Narrow it if you only use some:

$ npx gbs-add-block@latest -skill --for claude,codex$ npx gbs-add-block@latest -skill --for none          # only .gbs/

Dropping a target on a later run removes the files it wrote, and empty folders with them. A .claude folder that also holds your own settings is left in place.

The description is the only part always in an agent's context, and for Claude Code it is the main thing that decides whether the skill loads at all. If an agent is not picking the skill up on UI work, that line is what to look at first.

Codex and AGENTS.md

AGENTS.md is always in context and usually maintained by hand, so the skill is not inlined there — 5 KB in every conversation is a poor trade. Instead the CLI writes a pointer inside markers:

<!-- gbs-add-block:start -->
 
...
 
<!-- gbs-add-block:end -->

Anything outside those markers is never touched. If the file does not exist it is created; if the block is already there it is replaced in place; if the file exists without the block it is appended. This is also the one part not covered by the edit check, because the project owns the rest of the file.