Sindri Extension Guide

Sindri Extension Development Guide

Slash Commands (Recommended)

For reliable extension creation with all documentation updates, use these commands:

Example:

/extension/new mdflow https://github.com/johnlindquist/mdflow
/extension/update-docs nodejs

These commands enforce the complete workflow including all required documentation updates.

Overview

This skill guides you through creating declarative YAML extensions for Sindri. Extensions are YAML files, not bash scripts - all configuration is driven by declarative YAML definitions.

Documentation Locations

IMPORTANT: After creating any extension, you must update the relevant documentation.

Key Documentation Files

Quick Start Checklist

1. Create directory: docker/lib/extensions/{name}/
2. Create extension.yaml with required sections
3. Add to docker/lib/registry.yaml
4. Validate: ./cli/extension-manager validate {name}
5. Test: ./cli/extension-manager install {name}
6. Update documentation (see Post-Extension Checklist below)

Extension Directory Structure

docker/lib/extensions/{extension-name}/
├── extension.yaml       # Required: Main definition
├── scripts/             # Optional: Custom scripts
│   ├── install.sh       # Custom installation
│   ├── uninstall.sh     # Custom removal
│   └── validate.sh      # Custom validation
├── templates/           # Optional: Config templates
│   └── config.template
└── mise.toml            # Optional: mise configuration

Minimal Extension Template

metadata:
  name: my-extension
  version: 1.0.0
  description: Brief description (10-200 chars)
  category: dev-tools
  dependencies: []

install:
  method: mise
  mise:
    configFile: mise.toml

validate:
  commands:
    - name: mytool
      versionFlag: --version
      expectedPattern: "v\\d+\\.\\d+\\.\\d+"

Extension YAML Sections

1. Metadata (Required)

metadata:
  name: extension-name # lowercase with hyphens
  version: 1.0.0 # semantic versioning
  description: What it does # 10-200 characters
  category: dev-tools # see categories below
  author: Your Name # optional
  homepage: https://... # optional
  dependencies: # other extensions needed
    - nodejs
    - python

Valid Categories:

• base - Core system components
• language - Programming runtimes (Node.js, Python, etc.)
• dev-tools - Development tools (linters, formatters)
• infrastructure - Cloud/container tools (Docker, K8s, Terraform)
• ai - AI/ML tools and frameworks
• agile - Project management tools (Jira, Linear)
• database - Database servers
• monitoring - Observability tools
• mobile - Mobile SDKs
• desktop - GUI environments
• utilities - General tools

2. Requirements (Optional)

requirements:
  domains: # Network access needed
    - api.github.com
    - registry.npmjs.org
  diskSpace: 500 # MB required
  secrets: # Credentials needed
    - GITHUB_TOKEN

3. Install (Required)

Choose ONE installation method:

mise (recommended for language tools):

install:
  method: mise
  mise:
    configFile: mise.toml # Reference to mise config
    reshim: true # Rebuild shims after install

apt (system packages):

install:
  method: apt
  apt:
    repositories:
      - name: docker
        key: https://download.docker.com/linux/ubuntu/gpg
        url: https://download.docker.com/linux/ubuntu
        suite: jammy
        component: stable
    packages:
      - docker-ce
      - docker-ce-cli

binary (direct download):

install:
  method: binary
  binary:
    url: https://github.com/org/repo/releases/download/v1.0.0/tool-linux-amd64.tar.gz
    extract: tar.gz # tar.gz, zip, or none
    destination: ~/.local/bin/tool

npm (Node.js packages):

install:
  method: npm
  npm:
    packages:
      - typescript
      - eslint
    global: true

script (custom installation):

install:
  method: script
  script:
    path: scripts/install.sh
    timeout: 300 # seconds (default: 300)

hybrid (multiple methods):

install:
  method: hybrid
  hybrid:
    steps:
      - method: apt
        apt:
          packages: [build-essential]
      - method: script
        script:
          path: scripts/install.sh

4. Configure (Optional)

configure:
  templates:
    - source: templates/config.template
      destination: ~/.config/tool/config.yaml
      mode: overwrite # overwrite|append|merge|skip-if-exists
  environment:
    - key: TOOL_HOME
      value: $HOME/.tool
      scope: bashrc # bashrc|profile|session

5. Validate (Required)

validate:
  commands:
    - name: tool-name
      versionFlag: --version
      expectedPattern: "\\d+\\.\\d+\\.\\d+"
  mise:
    tools:
      - node
      - python
    minToolCount: 2
  script:
    path: scripts/validate.sh
    timeout: 60

6. Remove (Optional)

remove:
  confirmation: true
  mise:
    removeConfig: true
    tools: [node, python]
  apt:
    packages: [package-name]
    purge: false
  script:
    path: scripts/uninstall.sh
  paths:
    - ~/.config/tool
    - ~/.local/share/tool

7. Upgrade (Optional)

upgrade:
  strategy: automatic # automatic|manual|none
  mise:
    upgradeAll: true
  apt:
    packages: [package-name]
    updateFirst: true
  script:
    path: scripts/upgrade.sh

8. Bill of Materials (Optional but Recommended)

bom:
  tools:
    - name: node
      version: dynamic # or specific version
      source: mise
      type: runtime
      license: MIT
      homepage: https://nodejs.org

Adding to Registry

After creating your extension, add it to docker/lib/registry.yaml:

extensions:
  my-extension:
    category: dev-tools
    description: Short description
    dependencies: [nodejs]
    protected: false

Validation Commands

# Validate single extension
./cli/extension-manager validate my-extension

# Validate all extensions
./cli/extension-manager validate-all

# Check extension info
./cli/extension-manager info my-extension

# Test installation
./cli/extension-manager install my-extension

# Check status
./cli/extension-manager status my-extension

Common Patterns

Language Runtime (mise-based)

Best for: Node.js, Python, Go, Rust, Ruby

• Use method: mise with a mise.toml config file
• Set appropriate environment variables in configure section
• Validate with version command

Development Tool (npm-based)

Best for: TypeScript, ESLint, Prettier

• Depend on nodejs extension
• Use method: npm with global packages
• Add configuration templates

CLI Tool (binary download)

Best for: GitHub releases, standalone binaries

• Use method: binary with GitHub release URL
• Handle extraction (tar.gz, zip)
• Validate binary exists and runs

Complex Setup (hybrid)

Best for: Desktop environments, multi-step installs

• Use method: hybrid with ordered steps
• Combine apt + script for flexibility
• Include cleanup in remove section

Script Guidelines

All scripts must:

1. Start with #!/usr/bin/env bash
2. Include set -euo pipefail
3. Exit 0 on success, non-zero on failure
4. Use $HOME, $WORKSPACE environment variables
5. Log progress with echo statements

Example:

#!/usr/bin/env bash
set -euo pipefail

echo "Installing my-tool..."
# Installation commands here
echo "my-tool installed successfully"

Troubleshooting

Post-Extension Documentation Checklist

CRITICAL: After creating or modifying an extension, you MUST complete these documentation updates:

Required Updates (Always Do These)

• Registry Entry - Add to docker/lib/registry.yaml

  extensions:
    my-extension:
      category: dev-tools
      description: Short description
      dependencies: []
  

• Extension Documentation - Create docs/extensions/{NAME}.md

  • Use UPPERCASE for filename (e.g., NODEJS.md, AI-TOOLKIT.md)
  • Include: overview, installation, configuration, usage examples
  • For VisionFlow: docs/extensions/vision-flow/VF-{NAME}.md

• Extension Catalog - Update docs/EXTENSIONS.md

  • Add to appropriate category table
  • Include link to extension doc

Conditional Updates (When Applicable)

• Profiles - If adding extension to profiles:

  • Update docker/lib/profiles.yaml
  • Update relevant profile descriptions in docs/EXTENSIONS.md

• Categories - If adding new category:

  • Update docker/lib/categories.yaml
  • Update docker/lib/schemas/extension.schema.json (category enum)
  • Update category docs in docs/EXTENSIONS.md

• Schema - If adding new extension fields:

  • Update docker/lib/schemas/extension.schema.json
  • Update docs/SCHEMA.md
  • Update REFERENCE.md in this skill

• Slides - If extension is notable/featured:

  • Update docs/slides/extensions.html

VisionFlow-Specific Updates

• Update docs/extensions/vision-flow/README.md
• Update docs/extensions/vision-flow/CAPABILITY-CATALOG.md
• Update VisionFlow profile if applicable

Validation After Updates

# Validate YAML files
pnpm validate:yaml

# Lint markdown
pnpm lint:md

# Validate extension
./cli/extension-manager validate {name}

Extension Documentation Template

When creating docs/extensions/{NAME}.md, use this template:

# {Extension Name}

{Brief description of what the extension provides.}

## Overview

{More detailed explanation of the extension's purpose and capabilities.}

## Installation

\`\`\`bash
extension-manager install {name}
\`\`\`

## What Gets Installed

- {Tool 1} - {purpose}
- {Tool 2} - {purpose}

## Configuration

{Any configuration options or environment variables.}

## Usage

{Usage examples.}

## Dependencies

{List any extension dependencies.}

## Requirements

- **Disk Space:** {X} MB
- **Network:** {domains accessed}
- **Secrets:** {optional secrets}

## Related Extensions

- {Related extension 1}
- {Related extension 2}

Reference Files

• Schema: docker/lib/schemas/extension.schema.json
• Registry: docker/lib/registry.yaml
• Categories: docker/lib/categories.yaml
• Profiles: docker/lib/profiles.yaml
• Examples: docker/lib/extensions/*/extension.yaml

For detailed field reference, see REFERENCE.md. For complete examples, see EXAMPLES.md.

Tip: Use Glob and Grep tools to discover current documentation files dynamically:

# Find all extension docs
ls docs/extensions/*.md

# Find VisionFlow docs
ls docs/extensions/vision-flow/*.md