bria-ai/bria-skill

1. Repository purpose

This repo is not the image-generation backend itself; it is the distribution and instruction layer for Bria AI capabilities inside coding agents. Its main job is to package agent-readable skills, examples, and setup metadata so tools like Claude Code, Cursor, Cline, and others can invoke Bria services correctly.

2. Core architecture: skill packs

The primary unit of organization is the skills/ directory. Each subfolder is a self-contained skill package with a SKILL.md entrypoint, supporting references, and example code. These are the documents the agent reads to decide how to perform a task such as generation, background removal, VGL-based control, or image utilities.

3. Capability boundaries

The repo separates concerns by capability:

- skills/bria-ai for the broad Bria API surface

- skills/remove-background for the narrow background-removal path

- skills/vgl for structured Visual Generation Language control

- skills/image-utils for local image manipulation with Pillow

- skills/video-remove-background for the video-specific variant

This makes the architecture modular: agents can load only the skill that matches the task.

4. Instruction and reference layering

Inside each skill, the architecture is split between:

- SKILL.md as the authoritative task guidance

- references/ for endpoint docs, schema docs, and code samples

- license files for bundled upstream skill content

This keeps executable knowledge out of the high-level README and gives agents a clear “what to do” vs “how to do it” boundary.

5. Bria API integration path

The Bria-backed skills depend on the external platform.bria.ai API and an BRIA_API_KEY. The data flow is: user request → agent loads the relevant skill instructions → agent uses API references/examples → client code or direct calls reach Bria endpoints → generated or edited media is returned. The repo itself stores the calling conventions, not the API implementation.

6. Structured generation with VGL

skills/vgl and kiro/vgl define the structured control plane for deterministic image generation. Instead of only prompt text, this layer uses a JSON schema/reference to describe objects, lighting, composition, and style. Architecturally, this is the “high-control” path that sits alongside prompt-driven and edit-driven workflows.

7. Local utility workflow

skills/image-utils is different from the Bria API skills: it is a local processing layer for standard image operations like resize, crop, composite, and format conversion. The README notes Python dependencies (Pillow, requests), so this path executes on the user’s machine rather than in Bria’s cloud service.

8. Agent-specific adaptation layers

The repo includes multiple packaging surfaces for different agent ecosystems:

- .claude-plugin/marketplace.json for Claude Code marketplace distribution

- .claude/agents/ for agent helper behavior

- kiro/ with POWER.md and steering/ docs for Kiro-specific guidance

These are not separate features; they are different “adapters” around the same skill content.

9. CLI and npm packaging

The presence of package.json, package-lock.json, and bin/cli.js indicates an npm-distributed CLI wrapper. This is the install/bootstrap path used by commands like npx skills add ..., which helps agents fetch the right skill bundle into their local skills directory.

10. Documentation as the user-facing control plane

README.md is the entrypoint for humans, but the detailed operational knowledge lives in the skill docs and preambles. The preambles/ folder contains scenario-specific onboarding guidance such as device-flow auth and image-input handling, which likely helps agents choose the right setup path before making API calls.

11. Release and publishing pipeline

GitHub Actions in .github/workflows/ handle distribution:

- publish-npm.yml for npm publication of the CLI/package

- release-skills.yml for releasing the skill bundle content

This suggests the repo has two release concerns: package tooling and skill content updates.

12. End-to-end data flow

The typical runtime flow is:

user request in an agent → skill selection from skills/ or kiro/ → setup/auth via preambles and README → example-guided API call or local utility execution → image/video asset returned to the agent. The repo’s architecture is centered on making that flow reproducible across multiple agents and task types.

13. Important architectural boundary

The key boundary to capture in a diagram is between instruction/artifact distribution in this repo and actual media generation/editing services in Bria’s API. This repo orchestrates intent, routing, and examples; the heavy lifting happens either in Bria cloud endpoints or in local Python utilities for classic image operations.