goal-agent

Overview

The goal-agent skill creates a workspace that turns an OpenClaw agent into a focused, autonomous optimizer. You give it a goal and a shell command that measures progress — the agent does the rest, iterating heartbeat by heartbeat, learning what works and what doesn't.

Usage

Step 1: Collect inputs

Step 2: Run scaffold.sh

CODEBLOCK0

This generates the following files in --output-dir:

• - GOAL.md — goal definition, iteration counter, history table
• INLINECODE13 — current approach, hypotheses, next action
• INLINECODE14 — rules extracted from experience
• INLINECODE15 — the feedback loop instructions (replaces main HEARTBEAT.md)
• INLINECODE16 — runnable metric evaluator

Step 3: Activate the feedback loop

The generated HEARTBEAT.md is the goal-agent loop. Each heartbeat, the agent:

1. 1. Measures the metric
2. Compares against target and history
3. Reflects on what worked/didn't
4. Decides the next action
5. Acts
6. Records results
7. Adapts strategy

To activate: Copy HEARTBEAT.md to ~/clawd/HEARTBEAT.md (or symlink it):
CODEBLOCK1

Step 4: Deploy options

Option A — Current agent (fastest)
Copy all generated files into your workspace and activate HEARTBEAT.md as above.

Option B — Dedicated VM (cleanest)
Use the spawn-agent skill to create a fresh agent VM, then copy the goal workspace there:

# On the new agent
scp -r ~/clawd/goals/dau-growth/ ubuntu@new-agent:~/clawd/goals/
ssh ubuntu@new-agent "cp ~/clawd/goals/dau-growth/HEARTBEAT.md ~/clawd/HEARTBEAT.md"

Examples

Example 1: Optimize test coverage

Example 2: Reduce build time

Example 3: Grow social followers

bash ~/clawd/skills/goal-agent/scripts/scaffold.sh \
  --goal "Reach 500 Twitter followers" \
  --metric "~/.openclaw/scripts/twitter-follower-count.sh" \
  --target 500 \
  --direction up \
  --constraints "Only post authentic content. No follow-for-follow schemes." \
  --output-dir ~/clawd/goals/twitter-growth

Safety & Sandboxing

Before activating a goal-agent loop, review these guidelines:

• - Review generated files before activating. Always read the generated HEARTBEAT.md and evaluate.sh before copying them into your workspace. Confirm the metric command and constraints are what you intended.
• Use --constraints to limit scope. The agent will only take actions within the constraints you define. Be explicit: "Only modify files in ~/myproject/src", "Do not make network requests", "Do not delete files".
• Set a low --max-iterations for first runs. Start with 5-10 to observe behavior before allowing longer runs.
• Prefer dedicated VMs for autonomous goals. Use spawn-agent to isolate goal-agents from your main workspace. This limits blast radius if the agent takes unexpected actions.
• Metric commands should be read-only. The --metric command should only measure — never modify state. Use simple commands like cat, wc, jq, grep.
• The "Act" step is constrained by text, not code. The agent follows the constraints you set in --constraints, but there is no programmatic sandbox. For high-stakes goals, combine with filesystem permissions, network egress controls, or a restricted user account.
• Monitor early iterations. Check GOAL.md history after the first few heartbeats to verify the agent is behaving as expected.

How it works

The HEARTBEAT.md implements a tight cognitive loop:

CODEBLOCK6

Each iteration, the agent reads its own history (GOAL.md), its current understanding (STRATEGY.md), and accumulated wisdom (LEARNINGS.md) before taking action. Over time it builds a library of what works for your specific goal.

Files reference

Skill location