BalmUI Agent Skills

This repository contains official agent skills for BalmUI, designed to empower AI coding agents (like agy, claude-code, and codex) with deep knowledge of the framework's architecture, styling conventions, and customization patterns.

Available Skills

balm-ui-customization

A comprehensive guide and workflow protocol for customizing BalmUI styles using Sass variables (@use ... with) and minimal CSS overrides. It includes a strict "Discovery Protocol" ensuring AI agents actively search for Material Design Components (@material) variables instead of hallucinating them.

balm-ui-pro-list-view

Guide for building data-driven list pages using BalmUI Pro's ui-list-view component, relying on models and configuration rather than raw HTML/CSS.

balm-ui-pro-form-view

Guide for building standard create/edit form pages using BalmUI Pro's ui-form-view component and JSON configuration arrays.

balm-ui-pro-detail-view

Guide for building read-only detail pages using BalmUI Pro's ui-detail-view component and JSON configuration arrays.

balm-ui-pro-constants

Guide on using the centralized constant and dictionary management ($constant plugin) in BalmUI Pro projects to avoid hardcoding enum values.

balm-ui-pro-mocking

Guide for setting up and handling frontend mock APIs using MirageJS in BalmUI Pro architectures before real backend APIs are available.

balm-ui-pro-routing

Guide for adding and configuring new pages, routes, and modifying the dynamic sidebar menus in BalmUI Pro layouts.

balm-ui-pro-apis

Guide for utilizing the $apiModel plugin to define and interact with backend APIs, strictly decoupling HTTP requests from UI components.

balm-ui-pro-module ⭐

Meta-skill that orchestrates all BalmUI Pro skills above to scaffold a complete CRUD business module (constants → APIs → mocking → form config → list/detail/form views → routing) in one dependency-ordered pipeline.

Directory Structure

• skills/: Contains the actual skill packages (e.g., balm-ui-customization/). Each skill has its own SKILL.md and related reference/example files.
• docs/: Contains additional documentation and guides for users and developers.
  • balm-ui-customization-guide.md: The complete guide to styling strategies.
  • skill-anatomy.md: Specification for writing new BalmUI skills.
  • <tool>-setup.md: Specific setup guides for various CLI tools.

Quick Start

Claude Code

Copy any SKILL.md into your .claude/ directory, or reference the full skills/ directory. See docs/claude-setup.md.

Local / development:

git clone https://github.com/balmjs/balm-ui-agent-skills.git
claude --plugin-dir /path/to/balm-ui-agent-skills

Antigravity CLI

Install as a native plugin for skills. See docs/antigravity-setup.md.

Install from the repo:

agy plugin install https://github.com/balmjs/balm-ui-agent-skills.git

Install from a local clone:

git clone https://github.com/balmjs/balm-ui-agent-skills.git
agy plugin install ./balm-ui-agent-skills

Gemini CLI

Install as native skills for auto-discovery. See docs/gemini-cli-setup.md.

Install from the repo:

gemini skills install https://github.com/balmjs/balm-ui-agent-skills.git --path skills

Install from a local clone:

gemini skills install ./balm-ui-agent-skills/skills/

OpenCode

Uses agent-driven skill execution via AGENTS.md and the skill tool. Copy the skills/ directory into your .opencode/ or workspace directory and instruct your agent to use them. See docs/opencode-setup.md.

Codex / Other Agents

Skills are plain Markdown - they work with any agent that accepts system prompts or instruction files. Copy the contents into your project's .codex/ directory and explicitly reference the SKILL.md in your prompts to instruct the AI. See docs/codex-setup.md.

---

License

MIT - use these skills in your projects, teams, and tools.