skill-creator/SKILL.md

name, description, metadata

name	description	metadata
skill-creator	Instructions for creating new VibeStack skills	version vibestack 1.0.0 main type false knowledge

Skill Creator

This document teaches you how to create new VibeStack skills.

Before Creating a Skill

1. Check if it exists: Query Gitea API to see if skill already exists

   curl -s "https://git.vibe-overflow.com/api/v1/repos/azat/{skill-name}" | jq '.id'
   

   If returns an ID, skill exists. Don't recreate.

2. Check installed skills: Look in /skills/ directory

   ls /skills/
   

Skill Structure

Every skill needs:

skill-name/
├── SKILL.md              # Required: metadata + documentation
└── scripts/
    ├── autorun.sh        # Optional: install dependencies
    └── run.sh            # Optional: start service (if skill runs continuously)

SKILL.md Format

---
name: skill-name
description: One-line description of what it does
metadata:
  version: "1.0.0"
  vibestack:
    main: false           # true only for the main orchestrator
    requires:             # optional dependencies
      - other-skill
    metrics-port: 8080    # optional, if exposes metrics
    type: knowledge       # optional, for non-running skills
---

# Skill Name

Longer description of what the skill does.

## Configuration

| Variable | Default | Description |
|----------|---------|-------------|

## Usage

How to use the skill...

autorun.sh Pattern

Runs once when skill is loaded. Must be idempotent.

#!/bin/bash
set -e

# Idempotent installation
install_something() {
    if command -v something &>/dev/null; then
        echo "something already installed"
        return 0
    fi

    echo "Installing something..."
    apt-get update
    apt-get install -y something
    echo "something installed"
}

install_something

echo "Skill setup complete"

run.sh Pattern

Runs the service. Use exec to replace shell.

#!/bin/bash
set -e

PORT="${SKILL_PORT:-8080}"

echo "Starting service on port $PORT..."
exec some-command --port "$PORT"

For HTTP APIs (bash + socat)

#!/bin/bash
set -e

PORT="${SKILL_PORT:-8080}"

# Create handler script
cat > /tmp/handler.sh << 'HANDLER'
#!/bin/bash

read -r request_line
method=$(echo "$request_line" | cut -d' ' -f1)
path=$(echo "$request_line" | cut -d' ' -f2)

# Read headers
while read -r header; do
    header=$(echo "$header" | tr -d '\r')
    [ -z "$header" ] && break
done

send_response() {
    local status="$1" body="$2"
    printf "HTTP/1.1 %s\r\nContent-Type: application/json\r\nContent-Length: %d\r\n\r\n%s" \
        "$status" "${#body}" "$body"
}

case "$path" in
    /health) send_response "200 OK" '{"status":"ok"}' ;;
    *) send_response "404 Not Found" '{"error":"not found"}' ;;
esac
HANDLER
chmod +x /tmp/handler.sh

echo "Starting HTTP server on port $PORT..."
exec socat TCP-LISTEN:$PORT,reuseaddr,fork EXEC:/tmp/handler.sh

Creating and Pushing a New Skill

# 1. Create directory
mkdir -p /skills/new-skill/scripts

# 2. Write SKILL.md
cat > /skills/new-skill/SKILL.md << 'EOF'
---
name: new-skill
description: What it does
metadata:
  version: "1.0.0"
  vibestack:
    main: false
---

# New Skill

Documentation...
EOF

# 3. Write scripts (if needed)
cat > /skills/new-skill/scripts/autorun.sh << 'EOF'
#!/bin/bash
set -e
echo "Setup complete"
EOF

# 4. Create repo on Gitea
curl -X POST "https://git.vibe-overflow.com/api/v1/user/repos" \
  -H "Authorization: token $GIT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"new-skill","private":false,"description":"What it does"}'

# 5. Initialize git and push
cd /skills/new-skill
git init
git add .
git commit -m "Initial skill implementation"
git branch -M main
git remote add origin "https://${GIT_USER}:${GIT_TOKEN}@git.vibe-overflow.com/${GIT_USER}/new-skill.git"
git push -u origin main

Validation Checklist

Before pushing, verify:

• SKILL.md exists with valid YAML frontmatter
• name in frontmatter matches directory name
• description is set
• If has autorun.sh, it's idempotent (can run multiple times)
• If has run.sh, it uses exec for the main process
• No hardcoded secrets (use environment variables)
• Repo doesn't already exist on Gitea

Common Patterns

Installing apt packages

apt-get update && apt-get install -y package-name

Installing from GitHub releases

VERSION="1.0.0"
curl -sSL "https://github.com/org/repo/releases/download/v${VERSION}/binary" -o /usr/local/bin/binary
chmod +x /usr/local/bin/binary

Reading environment with defaults

PORT="${SKILL_PORT:-8080}"
HOST="${SKILL_HOST:-0.0.0.0}"

Exporting for other skills

mkdir -p /run/vibestack
echo "SOME_URL=http://localhost:$PORT" > /run/vibestack/skill-name.env

Environment Variables Available

• SKILLS_DIR - Skills directory (default: /skills)
• GIT_HOST - Git server (default: git.vibe-overflow.com)
• GIT_USER - Git user (default: azat)
• GIT_TOKEN - Git auth token