Chinese reader? Start here: 打开中文 README

understand_you

Language: English | 中文

understand_you is an OpenClaw skill built for one job: help a newly installed or partially profiled agent become noticeably more aligned with its owner in about 3 days of real use.

Help a new or partially profiled OpenClaw agent learn its owner faster, write that understanding into the right workspace files, and keep calibrating as the relationship evolves.

Overview

This skill is designed for the moment when an OpenClaw agent still feels generic.

It helps the agent:

• learn the owner's business context, work habits, priorities, tools, and communication preferences
• understand safety boundaries and permission expectations
• write confirmed information into the right OpenClaw workspace files
• keep calibrating over time instead of resetting to a generic style
• update SOUL.md when the agent's role and relationship drift

Quick Start

1. Copy this folder into your OpenClaw workspace skills/ directory.
2. Start a new session with /new.
3. Run:

/skill understand_you start

That is the canonical bootstrap command for this skill.

Why This Exists

Most onboarding skills ask a few questions and stop. That leaves the agent generic.

understand_you is designed to keep converging:

• the first session actively learns the highest-value context
• the next 1-3 days keep filling profile gaps through heartbeat and natural follow-ups
• confirmed information is written into the right OpenClaw files
• calibration feedback turns into better rules instead of being forgotten
• SOUL.md can evolve when the agent's role changes over time

The intended effect is simple: the agent should stop sounding generic and start feeling like it actually knows how to work with you.

Who This Is For

This repository is for OpenClaw users who want one of these outcomes:

• a fresh agent that can get useful fast instead of staying bland for weeks
• an existing workspace that already has some memory, but still has obvious blind spots
• a long-running agent that needs recalibration because the work changed and the persona did not

Key Highlights

1. Fast convergence

   The skill is optimized for a visible behavior change within about 3 days, not for a one-off questionnaire.

2. Works for both new and existing workspaces

   It supports three profile modes:

   • cold_start
   • partial_profile
   • mature_profile

   So it does not blindly re-onboard an existing user from zero.

3. Gap-audit before asking

   Before it asks anything, it scans the current workspace and classifies each dimension as:

   • missing
   • weak
   • strong
   • conflicting
   • not_applicable

   Then it only asks about weak, missing, or conflicting dimensions.

4. Writes to the files that matter

   Depending on confirmed information and approval level, it can update:

   • USER.md
   • MEMORY.md
   • TOOLS.md
   • AGENTS.md
   • HEARTBEAT.md
   • SOUL.md

5. High-impact changes still require confirmation

   The skill is proactive, but it does not silently change permissions, identity posture, or major SOUL.md shifts without explicit confirmation.

What It May Write

When information is confirmed, the skill may update the following files:

• USER.md
• MEMORY.md
• TOOLS.md
• AGENTS.md
• HEARTBEAT.md
• SOUL.md

It also maintains runtime state in:

• state/understand_you/onboarding-state.json
• state/understand_you/calibration-state.json

Installation

Copy this folder into your OpenClaw workspace skills/ directory.

Example:

cp -R understand-you /path/to/your/openclaw-workspace/skills/understand-you

Installing the folder makes the skill available, but it will not reliably auto-run by itself. Use the Quick Start flow above for the first run.

Safety Model

The skill is intentionally proactive, but not unconstrained.

• It scans first, then asks.
• It prefers append or patch behavior over rewriting mature files.
• It does not silently change high-impact defaults.
• Major SOUL.md, permission, or identity shifts still require confirmation.
• Low-impact calibration adjustments can be proposed or applied with a lightweight receipt depending on impact level.

First-Run Lifecycle

The skill is designed to:

1. scan the current workspace files first
2. decide whether this is cold_start, partial_profile, or mature_profile
3. create runtime state under:
   • state/understand_you/onboarding-state.json
   • state/understand_you/calibration-state.json
4. install proactive follow-up infrastructure in AGENTS.md and HEARTBEAT.md
5. begin the onboarding conversation in the same session
6. write confirmed information into the appropriate .md files

Tested Behavior

This skill has been iterated against real OpenClaw usage with both:

• fresh workspaces
• existing workspaces that already contain USER.md, MEMORY.md, AGENTS.md, and HEARTBEAT.md

The current version is specifically shaped around:

• cold_start
• partial_profile
• mature_profile
• gap-audit behavior before questioning
• OpenClaw-first runtime assumptions

Recommended Test Flow

1. prepare a fresh workspace
2. copy this skill into skills/understand-you
3. start a new session
4. run /skill understand_you start
5. answer naturally for several rounds
6. inspect the generated workspace files

OpenClaw Scope

This package is designed for OpenClaw workspace semantics. It assumes the usual OpenClaw bootstrap files and OpenClaw-style heartbeat and cron behavior.

It is not presented as a generic multi-runtime skill package.

Known Limits

• Installation alone does not auto-start the skill. Use /skill understand_you start.
• Gateway or channel instability can interrupt onboarding and leave partial state.
• Existing workspaces with stale onboarding sections from older skills should be cleaned before evaluation.
• The packaged state/*.json files are templates, not live runtime files.

Repository Layout

understand-you/
  SKILL.md
  README.md
  README.zh-CN.md
  policies/
  prompts/
  references/
  schemas/
  state/
  writers/

Usage Notes

• If you are testing on an old workspace, remove stale onboarding sections from earlier skills before judging results.
• If the gateway or chat channel is unstable, fix that first. A broken Discord or WebSocket session can interrupt onboarding and leave partial state.
• The packaged state/*.json files are templates. Runtime state should live in the workspace under state/understand_you/.

License

MIT. See LICENSE.