Skill: ollieb89/agent-builder-ollieb89 (version 1.1.0)

--- name: omni-agent-builder description: Build high-performing, secure OpenClaw agents and multi-agent teams end-to-end. Generates required OpenClaw workspace files (SOUL.md, IDENTITY.md, AGENTS.md, USER.md, TOOLS.md, HEARTBEAT.md, BOOTSTRAP.md, optional MEMORY.md + memory/YYYY-MM-DD.md). Incorporates best practices for team orchestration, Personal Intelligence (Pi) memory management, continuous evaluation, and CLI-driven setup/deployment. --- # Omni-Agent Builder (OpenClaw) Design and generate a complete **OpenClaw agent workspace** with robust defaults: - secure-by-default operating rules - optional multi-agent orchestration (Planner / Executor / Critic) - Personal Intelligence (Pi) memory workflow (`MEMORY.md` + daily logs) - evaluation + acceptance tests - CLI notes for fast local iteration ## Canonical references (read these first) 1) Workspace layout + bootstrap file load order + heartbeat rules: `references/openclaw-workspace.md` 2) File templates/snippets: `references/templates.md` 3) Background (agent architecture: planning / memory / tool use): `references/architecture.md` ## Default outputs (workspace files) Minimum viable workspace (always generate): - `AGENTS.md` (cross-cutting rules; **sub-agents only get this + TOOLS.md by default**) - `SOUL.md` - `TOOLS.md` - `IDENTITY.md` - `USER.md` - `HEARTBEAT.md` (usually empty to avoid token sink) - `BOOTSTRAP.md` (one-time ritual; delete after completion) Optional (generate if requested or clearly beneficial): - `MEMORY.md` (curated long-term memory; private/main session only) - `memory/YYYY-MM-DD.md` (daily log seed) ## Workflow: build a new agent/team from scratch ### Phase 1 — Tight interview (clarifying questions) Ask only what you need. Prefer 1–2 short rounds. 1) **Mission + autonomy** - Mission (1 sentence) - Single agent or multi-agent orchestration? - Autonomy: Advisor / Operator / Autopilot 2) **Surfaces + boundaries** - Channels: Telegram/WhatsApp/Discord/iMessage/Slack/etc. - Private DM only vs group channels? - “Ask before outbound messages” rule (default: ALWAYS ask) 3) **Tools + CLI usage** - Must it run local `openclaw` CLI commands? Which quick aliases are desired? - Any repos/paths it should assume? 4) **Pi memory** - Should it maintain curated `MEMORY.md`? - Categories: preferences, projects, people/orgs, “never do”, conventions, vocab - Privacy: what must never be stored? 5) **Bootstrapping ritual** - Any first-run steps (connect channels, create folders, install deps)? 6) **Evaluation** - What metrics define success? - 5–10 acceptance tests you want it to pass (we’ll propose defaults if none) ### Phase 2 — Generate the workspace files Generate the files listed above. Use the templates but tailor to the user’s answers. Required global guardrails to include (at minimum): - **Ask-before-destructive** (prefer `trash` over `rm`; create backups; show diffs) - **Ask-before-outbound** (never send messages/emails/DMs/calls without explicit approval) - **Stop-on-CLI-error** (unknown flag/exit code → run `--help`, correct, retry) - **No secrets in repo** (credentials/config belong under `~/.openclaw/…`, not the workspace) - **Group etiquette** (don’t claim to be the user; don’t leak private memory) - **Loop breaker** (max iterations; escalate to user with options) ### Phase 3 — Orchestration (if multi-agent) If multi-agent, define roles in `AGENTS.md`: - **Planner** - breaks tasks into steps - identifies risks + guardrails - defines acceptance tests - **Executor** - runs tools/edits files - maintains change log + rollback notes - stops on errors and recovers via `--help` / docs - **Critic** - reviews outputs for safety + completeness - checks for policy violations, overreach, and missing requirements - proposes fixes (minimal diffs) Delegation contract (must be in `AGENTS.md`): - Context to pass: goal, constraints, definition of done, relevant workspace excerpts - Explicit do-nots: no destructive actions; no outbound messages; no secrets ### Phase 4 — Pi memory workflow (recommended defaults) - Append raw notes to `memory/YYYY-MM-DD.md` (daily log; append-only) - Curate durable items into `MEMORY.md` (preferences, stable facts, conventions) - Only load/use `MEMORY.md` in **main private session**; avoid in group channels - If the user says “remember this”, persist it ### Phase 5 — Evaluation + acceptance tests Provide 5–10 short test prompts. Include at least: - Safety test (draft but do not send; ask before sending) - CLI recovery test (unknown flag → `--help` recovery) - Pi retention test (store + recall a preference correctly) - Orchestration test (delegate; show what context was passed) - Group chat etiquette test (avoid leaking private memory) ## Workflow: iterate on an existing agent 1) Identify the top failure modes (overreach, loops, verbosity, hallucinations, unsafe actions). 2) Decide if changes belong in: - `SOUL.md` (tone/persona) - `AGENTS.md` (rules, delegation, memory workflow) - `HEARTBEAT.md` (keep tiny; avoid deep thinking) - `TOOLS.md` (environment notes + CLI aliases) 3) Propose minimal diffs with rollback notes. 4) Add/update acceptance tests. ## Deliverable format When you output a workspace: - Print each file with a heading and a fenced code block. - If generating a zip, include the complete directory tree and a short “how to install” section.

path: _meta.json
content: {
  "slug": "agent-builder",
  "version": "1.1.0",
  "files": [
    "SKILL.md",
    "references/*",
    "scripts/*"
  ],
  "origin": null
}


path: references/architecture.md
content: # references/architecture.md

A simple, reliable agent architecture:

1) **Plan**
- restate goal + constraints
- propose steps + risks
- define “done”

2) **Act**
- use tools when correctness matters
- stop on errors and recover
- keep a change log

3) **Reflect**
- verify outputs against “done”
- run quick acceptance tests
- write memories (daily log + curated memory)

In multi-agent mode:
- Planner produces plan + tests
- Executor implements
- Critic reviews and requests minimal fixes


path: references/openclaw-workspace.md
content: # references/openclaw-workspace.md

This reference describes the **OpenClaw agent workspace**: what files exist, what gets loaded, and how heartbeat should be used.

## Workspace: what it is
- The workspace is the agent’s home directory and the default working directory for file tools.
- Treat it as private memory and a working repo. Do **not** commit secrets.

## Bootstrap files (loaded into context)

A typical injection order is:

1. `AGENTS.md`
2. `SOUL.md`
3. `TOOLS.md`
4. `IDENTITY.md`
5. `USER.md`
6. `HEARTBEAT.md`
7. `BOOTSTRAP.md`
8. `MEMORY.md` (optional; sometimes `memory.md`)

Notes:
- Sub-agents may receive only `AGENTS.md` and `TOOLS.md` by default. Put cross-cutting safety rules there.

## Heartbeat
- Keep heartbeat cheap and small.
- Prefer “operator dashboard check” energy:
  - If nothing important changed → respond exactly `HEARTBEAT_OK`
  - If something needs attention → send a short alert + next action options

## Security
- Never store credentials, API keys, tokens, or private keys in workspace files.
- Prefer safe operations:
  - preview diffs
  - backups
  - `trash` over `rm`
  - ask before destructive or irreversible changes


path: references/templates.md
content: # references/templates.md

Use these as starting points. Always tailor to the user.

## IDENTITY.md
- Name, vibe, emoji.
- Optional avatar path.

## USER.md
- Preferred name, address style, timezone, language.
- Durable preferences.
- Hard boundaries (“never do”).

## SOUL.md
- Persona and tone.
- Operating principles.
- Safety boundaries and trust model.
- Continuity rules: where memory lives.

## AGENTS.md (most important)
- Session-start read order.
- Safety defaults (ask-before-destructive, ask-before-outbound, stop-on-CLI-error).
- Memory workflow.
- Delegation protocol + sub-agent rules.
- Evaluation loop.

## HEARTBEAT.md
- Keep empty (or comments only) to skip.
- If used: tiny checklist; avoid deep work; aim for `HEARTBEAT_OK` when idle.

## BOOTSTRAP.md
- One-time first-run ritual.
- After completing, delete the file.

## MEMORY.md (optional)
- Curated, user-approved durable items only.
- Never loaded/used in group contexts.


path: scripts/scaffold-workspace.sh
content: #!/usr/bin/env bash
set -euo pipefail

# scaffold-workspace.sh
# Create a fresh OpenClaw workspace skeleton in the current directory (or a target dir).
# Usage:
#   ./scripts/scaffold-workspace.sh [target_dir]

TARGET="${1:-.}"

mkdir -p "$TARGET/references" "$TARGET/memory" "$TARGET/scripts"

# Minimal placeholders (you can overwrite with your customized versions)
cat > "$TARGET/IDENTITY.md" <<'EOF'
# IDENTITY.md
- Name: Omni
- Vibe: sharp, calm, practical
- Emoji: 🦞
EOF

cat > "$TARGET/USER.md" <<'EOF'
# USER.md
- Preferred name:
- How to address you:
- Timezone: Europe/Oslo
EOF

cat > "$TARGET/SOUL.md" <<'EOF'
# SOUL.md
You are Omni 🦞. Be direct and practical. Prefer tool-first verification when correctness matters.
EOF

cat > "$TARGET/TOOLS.md" <<'EOF'
# TOOLS.md
# Environment-specific notes (paths, aliases, services). Do not store secrets here.
EOF

cat > "$TARGET/AGENTS.md" <<'EOF'
# AGENTS.md
Every session: read SOUL.md, USER.md, memory/YYYY-MM-DD.md (today+yesterday). In main private session also read MEMORY.md if present.

Safety:
- Ask before destructive actions; prefer trash over rm.
- Ask before outbound messages.
- Stop on CLI errors; run --help and recover.
- Never store credentials in this repo.
EOF

cat > "$TARGET/HEARTBEAT.md" <<'EOF'
# HEARTBEAT.md
# Keep empty to skip heartbeat.
EOF

cat > "$TARGET/BOOTSTRAP.md" <<'EOF'
# BOOTSTRAP.md
First-run ritual:
1) Ask user for mission + autonomy + boundaries + memory preference.
2) Update IDENTITY/USER/SOUL/AGENTS.
3) Seed memory/YYYY-MM-DD.md
Delete this file after completion.
EOF

TODAY="$(date +%F)"
cat > "$TARGET/memory/$TODAY.md" <<EOF
# $TODAY
- Workspace scaffolded.
EOF

echo "✅ Scaffolded OpenClaw workspace at: $TARGET"


path: scripts/validate-workspace.py
content: #!/usr/bin/env python3
"""validate_workspace.py

Static checks for an OpenClaw workspace. Exits non-zero if missing key guardrails.

Usage:
  python3 scripts/validate-workspace.py [workspace_dir]
"""

from __future__ import annotations
import sys
from pathlib import Path

REQ_FILES = [
    "AGENTS.md","SOUL.md","TOOLS.md","IDENTITY.md","USER.md","HEARTBEAT.md","BOOTSTRAP.md"
]

GUARDRAIL_SNIPPETS = {
    "ask-before-destructive": ["ask before destructive", "trash over rm", "prefer trash"],
    "ask-before-outbound": ["ask before outbound", "never send", "explicit approval"],
    "stop-on-cli-error": ["stop on cli", "--help", "unknown flag"],
    "no-secrets": ["never store credentials", "no secrets", "do not commit secrets", "credentials"],
    "sub-agent-note": ["sub-agent", "sub agents", "subagents"],
}

def main() -> int:
    root = Path(sys.argv[1]) if len(sys.argv) > 1 else Path(".")
    missing = [f for f in REQ_FILES if not (root / f).exists()]
    if missing:
        print("Missing required files:")
        for f in missing:
            print(f" - {f}")
        return 2

    agents = (root / "AGENTS.md").read_text(encoding="utf-8", errors="ignore").lower()

    failures = []
    for name, needles in GUARDRAIL_SNIPPETS.items():
        if not any(n in agents for n in needles):
            failures.append(name)

    if failures:
        print("AGENTS.md is missing guardrail(s):")
        for f in failures:
            print(f" - {f}")
        return 3

    print("✅ Workspace looks sane.")
    return 0

if __name__ == "__main__":
    raise SystemExit(main())


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)