Skip to main content

Gesso Skills

Agent skills for building frontend UI with the Gesso Framework. The gesso-react skill inspects a Gesso project, selects documentation matching its resolved @acromedia/gesso package when available, and applies focused architecture, layout, and theming rules.

Versioning​

@acromedia/gesso-skill-react is versioned independently from @acromedia/gesso. Its package.json is the canonical version source, and .claude-plugin/plugin.json is generated from it by the package's version:sync script. The portable SKILL.md is intentionally versionless so these manifests cannot drift from embedded skill metadata.

Use pnpm check:gesso-react-version from the repository root to verify synchronization without modifying files.

Installation​

Opted-in frontends created with create-gesso run the same portable Skills CLI installation documented below from the generated frontend. Scaffolding omits --global to keep installation project-scoped and adds --yes to make it non-interactive. Existing projects can use the command below to install or update the skill.

Claude Code plugin​

/plugin marketplace add https://git.acromedia.com/acromedia/gesso/gesso.git
/plugin install gesso-react@gesso-skills

Portable skill (Cursor, Codex, Antigravity, Gemini, and others)​

From the project root, install the portable SKILL.md skill with:

DO_NOT_TRACK=1 pnpm dlx skills add git@git.acromedia.com:acromedia/gesso/gesso.git --skill gesso-react

DO_NOT_TRACK is used as a privacy-friendly default.

The installer detects supported agents and installs into their skill directories. Re-run the same command to update. Repository access is required.

What the skill provides​

  • Version-aware documentation discovery for each intended Gesso component
  • Matching source-checkout or installed-package documentation when available, with a disclosed latest-hosted fallback that may be incompatible
  • Real imports from @acromedia/gesso or a project package that re-exports it
  • Layout, responsive composition, theme, and design-token guidance
  • Project-aware guidance that preserves existing routes, providers, and theme setup

Requirements​

  • Node.js >=22.14.0, required for findPackageJSON-based package resolution
  • A skill-aware agent such as Claude Code, Cursor, Codex, Google Antigravity, or Pi
  • A project with a resolvable @acromedia/gesso package

Benchmarking (internal)​

Evaluate skill quality by comparing AI-generated code with and without the skill against a quality checklist.

1. Create test projects​

# From the Gesso repository root
./starter-kits/create-gesso/bin/create-gesso.js base_line_a --useLocal true
./starter-kits/create-gesso/bin/create-gesso.js base_line_b --useLocal true

2. Run benchmarks​

Run each side from its test project directory:

# Side A — without skill (run in base_line_a)
cd base_line_a
node ../gesso/skills/benchmark/run-benchmark.mjs \
  --plugin-dir ../gesso/skills/gesso-react --side a

# Side B — with skill (run in base_line_b)
cd base_line_b
node ../gesso/skills/benchmark/run-benchmark.mjs \
  --plugin-dir ../gesso/skills/gesso-react --side b

Optional runner arguments include --cwd, --case, --model, and --output.

3. Evaluate results​

From the corresponding test project directory, generate its report:

# Without design system
node ../gesso/skills/benchmark/generate-report.mjs \
  --results ./benchmark-results --evaluate

# With design system
node ../gesso/skills/benchmark/generate-report.mjs \
  --results ./benchmark-results --evaluate --project

The evaluator searches the project for generated code and scores it against the relevant quality checklist. Reports are saved to benchmark-results/<run-id>/report.md. Keep generated benchmark results out of source control.