# bria-ai/bria-skill architecture

> Architecture diagram of the GitHub repository bria-ai/bria-skill, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bria-ai/bria-skill
- Repository: https://github.com/bria-ai/bria-skill

## Overview

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.

Main entry points: [`skills/bria-ai`](https://github.com/bria-ai/bria-skill/tree/main/skills/bria-ai) (Bria AI), [`skills/vgl`](https://github.com/bria-ai/bria-skill/tree/main/skills/vgl) (VGL), [`README.md`](https://github.com/bria-ai/bria-skill/blob/main/README.md) (README), [`.github/workflows/release-skills.yml`](https://github.com/bria-ai/bria-skill/blob/main/.github/workflows/release-skills.yml) (Release skills)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_repo_core["Core distribution"]
  node_node_readme["README<br/>entry docs<br/>[README.md]"]
  node_node_cli["CLI<br/>npm wrapper<br/>[cli.js]"]
  node_node_package["Package<br/>npm manifest<br/>[package.json]"]
  node_node_preambles["Preambles<br/>setup guidance"]
end

subgraph group_group_skills["Skill packs"]
  node_node_bria_skill["Bria AI<br/>cloud API skill"]
  node_node_remove_bg["Remove BG<br/>edit skill"]
  node_node_video_remove_bg["Video BG<br/>video edit skill"]
  node_node_vgl_skill["VGL<br/>structured gen skill"]
  node_node_image_utils_skill["Image Utils<br/>local utility skill"]
  node_node_skill_refs["Skill refs<br/>reference docs"]
end

subgraph group_group_adapters["Agent adapters"]
  node_node_claude_plugin["Claude plugin<br/>marketplace adapter<br/>[marketplace.json]"]
  node_node_claude_agents["Claude agents<br/>agent helper"]
  node_node_kiro_readme["Kiro guide<br/>adapter docs<br/>[README.md]"]
  node_node_kiro_bria["Kiro Bria<br/>adapter skill"]
  node_node_kiro_image["Kiro image<br/>adapter skill"]
  node_node_kiro_vgl["Kiro VGL<br/>adapter skill"]
end

subgraph group_group_release["Release pipeline"]
  node_node_release_npm["Publish npm<br/>workflow<br/>[publish-npm.yml]"]
  node_node_release_skills["Release skills<br/>workflow<br/>[release-skills.yml]"]
end

node_node_readme -->|"points to"| node_node_preambles
node_node_readme -->|"describes"| node_node_bria_skill
node_node_readme -->|"installs"| node_node_cli
node_node_package -->|"packages"| node_node_cli
node_node_cli -->|"loads"| node_node_skill_refs
node_node_bria_skill -->|"uses"| node_node_skill_refs
node_node_remove_bg -->|"uses"| node_node_skill_refs
node_node_video_remove_bg -->|"uses"| node_node_skill_refs
node_node_vgl_skill -->|"uses"| node_node_skill_refs
node_node_image_utils_skill -->|"uses"| node_node_skill_refs
node_node_bria_skill -->|"specializes"| node_node_remove_bg
node_node_bria_skill -->|"specializes"| node_node_video_remove_bg
node_node_bria_skill -.->|"alongside"| node_node_vgl_skill
node_node_image_utils_skill -.->|"adapts to"| node_node_kiro_image
node_node_bria_skill -.->|"adapts to"| node_node_kiro_bria
node_node_vgl_skill -.->|"adapts to"| node_node_kiro_vgl
node_node_claude_plugin -->|"packages"| node_node_bria_skill
node_node_claude_agents -->|"supports"| node_node_bria_skill
node_node_release_npm -->|"publishes"| node_node_package
node_node_release_skills -->|"releases"| node_node_bria_skill
node_node_release_skills -->|"releases"| node_node_vgl_skill
node_node_release_skills -->|"releases"| node_node_image_utils_skill
node_node_preambles -->|"prepares"| node_node_bria_skill

click node_node_readme "https://github.com/bria-ai/bria-skill/blob/main/README.md"
click node_node_cli "https://github.com/bria-ai/bria-skill/blob/main/bin/cli.js"
click node_node_package "https://github.com/bria-ai/bria-skill/blob/main/package.json"
click node_node_preambles "https://github.com/bria-ai/bria-skill/tree/main/preambles"
click node_node_bria_skill "https://github.com/bria-ai/bria-skill/tree/main/skills/bria-ai"
click node_node_remove_bg "https://github.com/bria-ai/bria-skill/tree/main/skills/remove-background"
click node_node_video_remove_bg "https://github.com/bria-ai/bria-skill/tree/main/skills/video-remove-background"
click node_node_vgl_skill "https://github.com/bria-ai/bria-skill/tree/main/skills/vgl"
click node_node_image_utils_skill "https://github.com/bria-ai/bria-skill/tree/main/skills/image-utils"
click node_node_claude_plugin "https://github.com/bria-ai/bria-skill/blob/main/.claude-plugin/marketplace.json"
click node_node_claude_agents "https://github.com/bria-ai/bria-skill/blob/main/.claude/agents/api-skill-tester.md"
click node_node_kiro_readme "https://github.com/bria-ai/bria-skill/blob/main/kiro/README.md"
click node_node_kiro_bria "https://github.com/bria-ai/bria-skill/tree/main/kiro/bria-ai"
click node_node_kiro_image "https://github.com/bria-ai/bria-skill/tree/main/kiro/image-utils"
click node_node_kiro_vgl "https://github.com/bria-ai/bria-skill/tree/main/kiro/vgl"
click node_node_release_npm "https://github.com/bria-ai/bria-skill/blob/main/.github/workflows/publish-npm.yml"
click node_node_release_skills "https://github.com/bria-ai/bria-skill/blob/main/.github/workflows/release-skills.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_readme,node_node_cli,node_node_package,node_node_preambles toneBlue
class node_node_bria_skill,node_node_remove_bg,node_node_video_remove_bg,node_node_vgl_skill,node_node_image_utils_skill,node_node_skill_refs toneAmber
class node_node_claude_plugin,node_node_claude_agents,node_node_kiro_readme,node_node_kiro_bria,node_node_kiro_image,node_node_kiro_vgl toneMint
class node_node_release_npm,node_node_release_skills toneRose
```

## Components

### Core distribution

Primary packaging, docs, and release surfaces for the skill repository.

- [README](https://github.com/bria-ai/bria-skill/blob/main/README.md): entry docs · Human-facing overview and setup entrypoint. · `README.md`
- [CLI](https://github.com/bria-ai/bria-skill/blob/main/bin/cli.js): npm wrapper · Installed command for fetching or managing skill bundles. · `bin/cli.js`
- [Package](https://github.com/bria-ai/bria-skill/blob/main/package.json): npm manifest · npm distribution and dependency metadata for the CLI bundle. · `package.json`
- [Preambles](https://github.com/bria-ai/bria-skill/tree/main/preambles): setup guidance · Scenario-specific onboarding and auth guidance for agents. · `preambles`

### Skill packs

Agent-readable skill bundles and their references.

- [Bria AI](https://github.com/bria-ai/bria-skill/tree/main/skills/bria-ai): cloud API skill · General Bria API skill for generation and media tasks. · `skills/bria-ai`
- [Remove BG](https://github.com/bria-ai/bria-skill/tree/main/skills/remove-background): edit skill · Skill for background removal via Bria endpoints. · `skills/remove-background`
- [Video BG](https://github.com/bria-ai/bria-skill/tree/main/skills/video-remove-background): video edit skill · Video background removal skill variant. · `skills/video-remove-background`
- [VGL](https://github.com/bria-ai/bria-skill/tree/main/skills/vgl): structured gen skill · Structured visual generation control and schema guidance. · `skills/vgl`
- [Image Utils](https://github.com/bria-ai/bria-skill/tree/main/skills/image-utils): local utility skill · Local image processing skill using Python/Pillow. · `skills/image-utils`
- **Skill refs**: reference docs · Endpoint docs, schemas, and code examples bundled with each skill.

### Agent adapters

Packaging surfaces for specific agent ecosystems and runtimes.

- [Claude plugin](https://github.com/bria-ai/bria-skill/blob/main/.claude-plugin/marketplace.json): marketplace adapter · Claude Code marketplace distribution metadata. · `.claude-plugin/marketplace.json`
- [Claude agents](https://github.com/bria-ai/bria-skill/blob/main/.claude/agents/api-skill-tester.md): agent helper · Claude-specific helper guidance for agent behavior. · `.claude/agents/api-skill-tester.md`
- [Kiro guide](https://github.com/bria-ai/bria-skill/blob/main/kiro/README.md): adapter docs · Kiro-specific entry documentation. · `kiro/README.md`
- [Kiro Bria](https://github.com/bria-ai/bria-skill/tree/main/kiro/bria-ai): adapter skill · Kiro adaptation of the Bria AI skill with steering docs. · `kiro/bria-ai`
- [Kiro image](https://github.com/bria-ai/bria-skill/tree/main/kiro/image-utils): adapter skill · Kiro adaptation of local image utilities. · `kiro/image-utils`
- [Kiro VGL](https://github.com/bria-ai/bria-skill/tree/main/kiro/vgl): adapter skill · Kiro adaptation of structured generation guidance. · `kiro/vgl`

### Release pipeline

Automation for publishing the CLI and skill bundles.

- [Publish npm](https://github.com/bria-ai/bria-skill/blob/main/.github/workflows/publish-npm.yml): workflow · GitHub Action for publishing the npm package. · `.github/workflows/publish-npm.yml`
- [Release skills](https://github.com/bria-ai/bria-skill/blob/main/.github/workflows/release-skills.yml): workflow · GitHub Action for releasing skill bundle content. · `.github/workflows/release-skills.yml`

## Connections

- README → Preambles: points to · Docs route agents through setup and auth guidance.
- README → Bria AI: describes · Main entry explains the skill-pack architecture.
- README → CLI: installs · Human entry connects to the npm bootstrap path.
- Package → CLI: packages · Manifest defines the distributable CLI wrapper.
- CLI → Skill refs: loads · CLI helps fetch or surface skill bundles and references.
- Bria AI → Skill refs: uses · Bria skill is backed by endpoint docs and examples.
- Remove BG → Skill refs: uses · Background-removal skill is backed by API docs and examples.
- Video BG → Skill refs: uses · Video background-removal skill is backed by API docs and examples.
- VGL → Skill refs: uses · VGL skill is backed by schema/reference docs.
- Image Utils → Skill refs: uses · Local utility skill is backed by code examples.
- Bria AI → Remove BG: specializes · Narrow edit workflow is a capability subset of the broader Bria surface.
- Bria AI → Video BG: specializes · Video variant extends the Bria media-edit boundary.
- Bria AI → VGL: alongside · Structured generation is a parallel control path to prompt/edit workflows.
- Image Utils → Kiro image: adapts to · Kiro ships a parallel adapter for the local utility workflow.
- Bria AI → Kiro Bria: adapts to · Kiro ships a parallel adapter for Bria API guidance.
- VGL → Kiro VGL: adapts to · Kiro ships a parallel adapter for VGL guidance.
- Claude plugin → Bria AI: packages · Marketplace distribution wraps the same skill content for Claude.
- Claude agents → Bria AI: supports · Claude helper behavior supplements skill usage.
- Publish npm → Package: publishes · Workflow publishes the npm-distributed CLI package.
- Release skills → Bria AI: releases · Workflow publishes skill content updates.
- Release skills → VGL: releases · Workflow publishes structured generation skill updates.
- Release skills → Image Utils: releases · Workflow publishes local utility skill updates.
- Preambles → Bria AI: prepares · Setup guidance helps choose the correct Bria workflow.