Skip to content

Latest commit

 

History

History
213 lines (166 loc) · 6.04 KB

skill-development.md

File metadata and controls

213 lines (166 loc) · 6.04 KB

Skill Development Guide

This guide explains how to create a new skill for the DeepCamera skill catalog.

What is a Skill?

A skill is a self-contained folder that provides an AI capability to SharpAI Aegis. Skills communicate with Aegis via JSON lines over stdin/stdout.

Skill Structure

skills/<category>/<skill-name>/
├── SKILL.md              # Manifest + setup instructions
├── config.yaml           # Configuration schema for Aegis UI
├── deploy.sh             # Zero-assumption installer
├── requirements.txt      # Default Python dependencies
├── requirements_cuda.txt # NVIDIA GPU dependencies
├── requirements_rocm.txt # AMD GPU dependencies
├── requirements_mps.txt  # Apple Silicon dependencies
├── requirements_cpu.txt  # CPU-only dependencies
├── scripts/
│   └── main.py           # Entry point
├── assets/
│   └── icon.png          # 64×64 icon (optional)
└── tests/
    └── test_main.py      # Tests (optional)

SKILL.md Format

The SKILL.md file has two parts:

  1. YAML frontmatter — machine-readable parameters and capabilities
  2. Markdown body — human/LLM-readable setup instructions
---
name: my-skill
description: "What this skill does"
version: 1.0.0

parameters:
  - name: model
    label: "Model"
    type: select
    options: ["option1", "option2"]
    default: "option1"
    group: Model

capabilities:
  my_capability:
    script: scripts/main.py
    description: "What this capability does"
---

# My Skill

Description of the skill.

## Setup

Step-by-step setup instructions that SharpAI Aegis's
LLM agent can read and execute.

Parameter Types

Type Renders As Example
string Text input Email, URL, API key
password Masked input Passwords, tokens
number Number input with min/max Confidence threshold
boolean Toggle switch Enable/disable feature
select Dropdown Model selection
url URL input with validation Server address
camera_select Camera picker Target cameras

config.yaml — Configuration Schema

Defines user-configurable options shown in the Aegis Skills UI. Parsed by parseConfigYaml().

params:
  - key: auto_start
    label: Auto Start
    type: boolean
    default: false
    description: "Start automatically on Aegis launch"

  - key: model_size
    label: Model Size
    type: select
    default: nano
    description: "Choose model variant"
    options:
      - { value: nano, label: "Nano (fastest)" }
      - { value: small, label: "Small (balanced)" }

  - key: confidence
    label: Confidence
    type: number
    default: 0.5
    description: "Min confidence (0.1–1.0)"

Reserved Keys

Key Type Behavior
auto_start boolean Aegis auto-starts the skill on boot when true

deploy.sh — Zero-Assumption Installer

Bootstraps the environment from scratch. Must handle:

  1. Find Python — check system → conda → pyenv
  2. Create venv — isolated .venv/ inside skill directory
  3. Detect GPU — CUDA → ROCm → MPS → CPU fallback
  4. Install deps — from matching requirements_<backend>.txt
  5. Verify — import test

Emit JSONL progress for Aegis UI:

echo '{"event": "progress", "stage": "gpu", "backend": "mps"}'
echo '{"event": "complete", "backend": "mps", "message": "Installed!"}'

Environment Variables

Aegis injects these into every skill process:

Variable Description
AEGIS_SKILL_ID Skill identifier
AEGIS_SKILL_PARAMS JSON string of user config values
AEGIS_GATEWAY_URL LLM gateway URL
AEGIS_VLM_URL VLM server URL
AEGIS_LLM_MODEL Active LLM model name
AEGIS_VLM_MODEL Active VLM model name
PYTHONUNBUFFERED Set to 1 for real-time output

JSON Lines Protocol

Scripts communicate with Aegis via stdin/stdout. Each line is a JSON object.

Script → Aegis (stdout)

{"event": "ready", "model": "...", "device": "..."}
{"event": "detections", "camera_id": "...", "objects": [...]}
{"event": "error", "message": "...", "retriable": true}

Aegis → Script (stdin)

{"event": "frame", "camera_id": "...", "frame_path": "...", "timestamp": "..."}
{"command": "stop"}

Categories

Category Directory Use For
detection skills/detection/ Object detection, person recognition
analysis skills/analysis/ VLM scene understanding, offline analysis
transformation skills/transformation/ Depth estimation, style transfer
annotation skills/annotation/ Dataset labeling, COCO export
camera-providers skills/camera-providers/ Blink, Eufy, Ring, Reolink, Tapo
streaming skills/streaming/ RTSP/WebRTC via go2rtc
channels skills/channels/ Messaging: Matrix, LINE, Signal
automation skills/automation/ MQTT, webhooks, HA triggers
integrations skills/integrations/ Home Assistant bridge

Testing Locally

# Test your skill without Aegis by piping JSON:
echo '{"event": "frame", "camera_id": "test", "frame_path": "/tmp/test.jpg"}' | python scripts/main.py

skills.json — Catalog Registration

Register skills in the repo root skills.json:

{
  "skills": [
    {
      "id": "my-skill",
      "name": "My Skill",
      "description": "What it does",
      "category": "detection",
      "tags": ["tag1"],
      "path": "skills/detection/my-skill",
      "status": "testing",
      "platforms": ["darwin-arm64", "linux-x64"]
    }
  ]
}

Status Values

Status Emoji Meaning
ready ✅ Production-quality, tested
testing 🧪 Functional, needs validation
experimental ⚗️ Proof of concept
planned 📐 Not yet implemented

Reference

See skills/detection/yolo-detection-2026/ for a complete working example.