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:

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:

   pip install -e /path/to/my-plugin
   hermes plugins enable my-plugin
   

2. Run setup:

   hermes my-plugin setup
   

3. Check status:

   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 — Quick start, API overview, what Fabricium provides
• Fabricium API Reference — Full Python API surface
• Fabricium Workflows — Recipes: build plugin, add API, release, debug
• Fabricium Architecture — System design, C4 diagrams
• Fabricium Testing Guide — Integration test environment, fixtures
• Fabricium Conventions — Code style and naming conventions