# Fabricium Sdk

> Guides the agent through using Fabricium's SDK to create standardized Hermes plugins with CLI lifecycle (setup/status/update), bundled skills, state persistence, and Git self-update — all in one line of registration. Use when the user wants to create a new Hermes plugin, build a Hermes plugin from scratch, add plugin infrastructure, or when they ask 'create a hermes plugin', 'build a plugin for hermes', '寫一個 hermes plugin', '用 fabricium 寫 plugin'. Do NOT use for editing an existing plugin's unique tools (that is plugin-specific business logic), for non-Hermes projects, or for debugging plugin installation issues (use jovaltus-setup for that).

- Skill: `uniterra-solutions/fabricium-sdk` (Agent Skill)
- Install (CLI): `npx skillmds@latest add uniterra-solutions/fabricium-sdk`
- Raw SKILL.md: https://api.skillmd.com/api/skills/uniterra-solutions/fabricium-sdk/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: Uniterra-Solutions (https://skillmd.com/u/uniterra-solutions)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/uniterra-solutions/fabricium-sdk

---


# Fabricium SDK

Guide the agent through creating a standardized Hermes plugin using
Fabricium's `HermesPlugin` class. The skill itself does not contain API
details — it tells the agent **where** to find them in the Fabricium
documentation, which is the canonical source of truth.

## Goal

A working Hermes plugin with standardized CLI commands (`setup`, `status`,
`update`), bundled skill auto-discovery, state persistence, and Git
self-update — all from a single `HermesPlugin` registration.

## Core Principle: Fabricium Docs Are the Source of Truth

Fabricium is a library (not a framework) that plugins import. Its API
surface, module responsibilities, and conventions are all documented in the
canonical repository. This skill tells the agent **which parts** of
Fabricium to use and **where** to find the docs — never hardcodes API
shapes or parameters that could become stale.

## Workflow

### Phase 1: Understand Fabricium's Capabilities

Before writing any code, read the Fabricium README to understand what
it provides out of the box:

```
https://raw.githubusercontent.com/Uniterra-Solutions/fabricium/main/README.md
```

Focus on these sections:
- **Quick Start: Building a Plugin** — the minimal plugin skeleton
- **What Fabricium Provides** — CLI commands, profile modes, state persistence, bundled skill lifecycle, Git self-update
- **API Reference** — `HermesPlugin` constructor and methods

The agent should understand: Fabricium gives every plugin `setup`, `status`, and `update` CLI commands, bundled skill auto-discovery, and state persistence — all in one `plugin.register(ctx)` call.

### Phase 2: Consult the API Reference and Workflow Docs

For specific API details, read:

```
https://raw.githubusercontent.com/Uniterra-Solutions/fabricium/main/docs/api-reference.md
```

For step-by-step recipes (including "Build a Plugin"), read:

```
https://raw.githubusercontent.com/Uniterra-Solutions/fabricium/main/docs/workflows.md
```

For understanding the plugin's internal architecture:

```
https://raw.githubusercontent.com/Uniterra-Solutions/fabricium/main/docs/architecture.md
```

For detailed module-level documentation:

| Module | Doc URL |
|--------|---------|
| HermesPlugin core | `docs/modules/core.md` |
| Skills lifecycle | `docs/modules/skills.md` |
| State persistence | `docs/modules/state.md` |
| Git utilities | `docs/modules/git-utils.md` |
| Integration testing | `docs/modules/testing.md` |
| Eval framework | `docs/modules/evals.md` |

All module docs are at:
`https://raw.githubusercontent.com/Uniterra-Solutions/fabricium/main/docs/modules/<name>.md`

### Phase 3: Create the Plugin

After understanding Fabricium's API, create the plugin following this
structure (the exact code comes from the docs, not from this skill):

```
my-plugin/
├── __init__.py      # HermesPlugin registration + custom tools
├── plugin.yaml      # Hermes plugin manifest
├── SOUL.md          # Agent identity (optional, auto-deployed by setup)
├── pyproject.toml   # Package metadata + dependencies
├── skills/          # Bundled skills (auto-discovered)
│   └── my-skill/
│       └── SKILL.md
└── tests/
    ├── test_plugin.py
    └── integration/
        └── test_cli.py
```

Key implementation points (verified against the docs):

1. **Plugin entry point**: Create `HermesPlugin(name=..., plugin_dir=..., default_profile=...)` and call `plugin.register(ctx)` in your `register()` function.

2. **Custom tools**: Register your unique business logic via `ctx.register_tool(...)` after the `plugin.register(ctx)` call.

3. **Bundled skills**: Place skills in `my-plugin/skills/` — they are auto-discovered. No manual registration needed.

4. **Profile modes**: Set `default_profile="my-profile"` for single-profile plugins, or `default_profile=None` for multi-profile (user selects at setup time).

5. **Dependencies**: Add `fabricium` as a dependency in `pyproject.toml`. Fabricium itself has zero runtime dependencies beyond the standard library.

### Phase 4: Verify the Plugin Works

After creating the plugin, verify it end-to-end:

1. **Install the plugin** locally:
   ```bash
   pip install -e /path/to/my-plugin
   hermes plugins enable my-plugin
   ```

2. **Run setup**:
   ```bash
   hermes my-plugin setup
   ```

3. **Check status**:
   ```bash
   hermes my-plugin status
   ```

4. **Test custom tools**: Invoke any custom tools via `hermes chat -p <profile>`.

### Phase 5: Add Integration Tests (Recommended)

Fabricium provides a Docker-based integration test environment. See the
testing docs for `HermesDockerTestEnv` and `CliAssert`:

```
https://raw.githubusercontent.com/Uniterra-Solutions/fabricium/main/docs/testing.md
```

## Gotchas

- **Fabricium is a library, not a framework.** Plugins import `from fabricium import HermesPlugin` — Fabricium never imports or controls the plugin. Any behavior can be overridden.
- **`plugin_dir` must be `Path(__file__).parent`.** The plugin root is used to locate `skills/` and `SOUL.md`. A wrong path here breaks bundled skill discovery and SOUL deployment.
- **Profile modes are immutable at setup time.** Switching from `default_profile=None` (multi-profile) to a named profile (or vice versa) changes the setup UX. Decide early.
- **Bundled skills are installed globally** to `~/.hermes/skills/`, not per-profile. Every profile on the system can load them.
- **Fabricium has zero runtime dependencies.** Do not add unnecessary transitive dependencies to Fabricium itself — only the plugin's own depenencies go in `pyproject.toml` alongside `fabricium`.
- **`plugin.yaml` is required** by Hermes for plugin discovery. Fabricium does not generate it — the plugin author must create it.
- **State file is auto-managed.** Do not create `~/.hermes/<plugin>_state.json` manually — Fabricium's `HermesPlugin` handles it via `fabricium.state`.
- **Integration tests require Docker.** The `fabricium.testing` module spins up containers with real Hermes installations. Unit tests should use monkeypatch instead.

## References

- [Fabricium README](https://raw.githubusercontent.com/Uniterra-Solutions/fabricium/main/README.md) — Quick start, API overview, what Fabricium provides
- [Fabricium API Reference](https://raw.githubusercontent.com/Uniterra-Solutions/fabricium/main/docs/api-reference.md) — Full Python API surface
- [Fabricium Workflows](https://raw.githubusercontent.com/Uniterra-Solutions/fabricium/main/docs/workflows.md) — Recipes: build plugin, add API, release, debug
- [Fabricium Architecture](https://raw.githubusercontent.com/Uniterra-Solutions/fabricium/main/docs/architecture.md) — System design, C4 diagrams
- [Fabricium Testing Guide](https://raw.githubusercontent.com/Uniterra-Solutions/fabricium/main/docs/testing.md) — Integration test environment, fixtures
- [Fabricium Conventions](https://raw.githubusercontent.com/Uniterra-Solutions/fabricium/main/docs/conventions.md) — Code style and naming conventions