Skip to main content

​
Item Registry

The genie install, genie publish, and genie item commands manage the Genie item registry. Items are reusable components distributed via git repositories and described by a genie.yaml manifest.

​
Item Types

TypeDescription
agentAutonomous agent with model config, roles, and entrypoint
skillReusable skill with triggers and entrypoint
appApplication with runtime, NATS prefix, and entrypoint
boardBoard definition with stage pipeline and gate configs
workflowScheduled workflow with cron expression and command
stackBundle of multiple items installed together
templateProject template for scaffolding
hookHook script triggered by lifecycle events

​
genie install

Install a Genie item from a git repository. 
genie install <target> [options]
The target is a git URL with an optional version tag: 
github.com/user/repo
github.com/user/repo@v1.0.0
https://github.com/user/repo.git@v2.0.0
git@github.com:user/repo.git
OptionDescription
--forceOverride existing item with same name
--fullFull git clone instead of shallow

​
What happens on install

  1. Clones the repository (shallow by default) to ~/.genie/items/<name>/
  2. Detects the manifest — genie.yaml, or inferred from AGENTS.md, manifest.ts, skill.md
  3. Validates the manifest against type-specific rules
  4. Registers the item in the app store (PostgreSQL)
  5. Runs type-specific setup:
    • agent — regenerates agent cache
    • board — creates task type with stage pipeline
    • workflow — registers schedule with cron expression
    • stack — recursively installs all bundled items
--force overwrites an existing item with the same name. If you made local edits inside ~/.genie/items/<name>/, they’re discarded — use --full during development so the clone is a full git checkout you can work from.
Install a stack to bootstrap an entire workspace in one command — stack items recursively install every agent, skill, board, and workflow they bundle.

​
Examples

# Install an agent
genie install github.com/automagik-dev/agent-reviewer

# Install a specific version
genie install github.com/automagik-dev/board-software@v1.2.0

# Force reinstall
genie install github.com/automagik-dev/agent-reviewer --force

# Full clone (for development)
genie install github.com/automagik-dev/my-stack --full

​
genie publish

Publish the current directory as a Genie item. Must be run from a directory containing a valid manifest. Requires a pushed git tag matching the manifest version. 
genie publish

​
Prerequisites

  1. A genie.yaml manifest (or detectable convention) in the current directory
  2. A git tag matching the manifest version (e.g., v1.0.0 for version 1.0.0)
  3. The tag must be pushed to the remote

​
What happens on publish

  1. Detects and validates the manifest in the current directory
  2. Verifies a git tag matching v<version> exists and is pushed to the remote
  3. Registers or updates the item in the app store
  4. Records the version in app_versions with git SHA
  5. Sets approval status to pending

​
Example

# Tag and publish
git tag v1.0.0
git push origin v1.0.0
genie publish
genie publish records the version in app_versions against a specific git SHA — once registered, that (name, version) pair cannot be quietly replaced. If you pushed a broken tag, bump the version and publish again rather than trying to rewrite history.

​
genie item update

Update an installed item to the latest version or a specific tag. 
genie item update [name] [options]
OptionDescription
--allUpdate all git-installed items
# Update a specific item
genie item update my-agent

# Update all installed items
genie item update --all

​
genie item uninstall

Remove an installed item. 
genie item uninstall <name>

genie item uninstall my-agent

​
Manifest Format

Every item is described by a genie.yaml manifest: 
name: my-agent
type: agent
version: 1.0.0
description: A review agent
author:
  name: automagik
  url: https://github.com/automagik-dev
tags: [review, code-quality]
category: development
license: MIT
dependencies:
  - some-other-item

agent:
  model: sonnet
  entrypoint: AGENTS.md
  roles: [reviewer, qa]

​
Required Fields

FieldDescription
nameItem name (used as identifier)
typeOne of: agent, skill, app, board, workflow, stack, template, hook
versionSemantic version string

​
Type-Specific Sections

Each type has its own section with type-specific fields: agent 
agent:
  model: sonnet
  entrypoint: AGENTS.md
  roles: [engineer, reviewer]
skill 
skill:
  triggers: ["/review", "review this"]
  entrypoint: skill.md
board 
board:
  stages:
    - name: draft
      gate: human
    - name: build
      gate: agent
      auto_advance: true
    - name: review
      gate: human+agent
workflow 
workflow:
  cron: "0 9 * * 1-5"
  timezone: America/Sao_Paulo
  command: genie spawn reporter
stack 
stack:
  items:
    - name: my-board
      type: board
      inline: true
      config:
        stages:
          - name: todo
            gate: human
    - name: my-agent
      type: agent
      source: github.com/user/agent-repo

​
Manifest Detection

If no genie.yaml exists, Genie infers the manifest from conventions:
FileInferred type
genie.yamlExplicit manifest (first priority)
AGENTS.mdagent — reads name, model, roles from YAML frontmatter
manifest.tsapp
skill.mdskill

​
See also

Directory

Register and edit agents in the local directory.

Boards

Boards are one of the item types you can publish and install.

Scheduling

Workflow items create schedules on install.

Database

Inspect the app store tables that back the registry.