Skill Sediment

> - Author: Evan Song > - Repository: https://github.com/Songhonglei/build-better-skills > - License: MIT — see [LICENSE](./LICENSE) > - Version: 1.0.2

skill-sediment

One-shot installer for the OpenClaw skill-sediment plugin extension — auto-distill successful conversation workflows into SKILL.md files, then promote them to skills/.

Core Facts

• What is being ported: an OpenClaw plugin extension (not an MCP, not a standalone

service) that listens to conversations and writes successful workflows as SKILL.md.

• The plugin is ≈340KB of pure TypeScript source (9 files), depending only on

OpenClaw core's built-in plugin-sdk + typebox.

• No embedding model required — sediment uses LLM semantic judgement, not vector retrieval.
• The plugin source is already embedded in assets/plugin-source/ (flat directory

of 9 TypeScript files + package.json + openclaw.plugin.json) — offline install works out of the box. A legacy .tar.gz fallback path is also supported for backward compatibility.

Quick Install

cd 
python3 scripts/manage.py install
# Then follow the prompt to manually restart: openclaw gateway restart
# Verify after restart: python3 scripts/manage.py doctor

In most cases plugins.allow is empty, so the plugin loads automatically from the convention directory — no config change required, just restart.

--valid-agent-id is only needed when restricting which agents get sediment enabled (comma-separated, e.g. main,debp; defaults to main).

Subcommands

| Command | Purpose | |---------|---------| | install | Full install: env check → deploy plugin to convention dir → interactive agent selection → allow-empty auto-load / allow-nonempty whitelist append → restart prompt | | config | Print current allow state and recommended actions (helpful for managed pods) | | doctor | Diagnose: version / plugin-sdk / plugin files / allow whitelist / validAgentId / sedimentskills dir | | recover | Restore after pod restart (plugin present → OK; PVC volume swapped → redeploy) | | status | Inspect sediment pool: pending incubations (sedimentskills/) and activated promotions (skills/) | | heal | Self-repair: detect and fix whitelist/file loss, supplement missing validAgentId, auto-restart gateway | | uninstall | Remove allow/entries config entries (add --purge to also remove plugin dir; never deletes already-sedimented SKILL.md) |

> Note: this open-source version intentionally omits the cron-setup subcommand > from the internal build, since unattended scheduling assumes platform-specific > orchestration. Use heal manually, or wire it into your own scheduler (cron, systemd > timer, K8s CronJob, etc.) by invoking python3 scripts/manage.py heal.

openclaw.json Changes

| Scenario | Change | |----------|--------| | plugins.allow empty | No openclaw.json change, convention dir auto-loads ✨ | | plugins.allow non-empty without this plugin | Idempotently append "skill-sediment" to allow | | plugins.entries | Optionally append validAgentId config (can be added manually any time) |

Convention-dir loading no longer requires plugins.load.paths; install does not touch it.

Key Constraints (must obey)

1. Plugin directory uses the workspace convention path

OpenClaw auto-discovers plugins under:

/.openclaw/extensions//

The plugin is deployed here (mounted on PVC, survives container restart/volume swap). Do not put it under /app/extensions (container layer is restored on restart).

When plugins.allow is empty, all plugins in this dir auto-load — no whitelist needed. When non-empty, the plugin must be explicitly listed in allow.

2. Managed environments (Lobi / Apollo)

If plugins.allow is non-empty and requires a whitelist append, you'll be writing openclaw.json. Managed pods face an override risk:

• Pre-detect: LOBI_SYNC_ENABLED / APPID=clawbot* / Apollo signals → skip

local write, redirect to remote console config

• The plugin file itself (convention dir) lands locally regardless, unaffected by

managed-config sync

If plugins.allow is empty (most cases), managed and unmanaged pods behave identically — zero config change.

3. Gateway restart is not automatic by default

By default install only prompts for manual restart. Pass --auto-restart to have it restart the gateway automatically.

4. Version compatibility

Verified OpenClaw baseline: 2026.3.8. install auto-compares the target version:

• = 2026.3.8 → green light
• > baseline → warn and continue (the plugin API surface is narrow; rely on

post-install smoke test)

• `/dev/null | tail

Or OpenClaw's own logs

grep "\[skill-sediment\]" ~/.openclaw/logs/*.log 2>/dev/null | tail

Or K8s from outside

kubectl logs | grep "\[skill-sediment\]"

Final confirmation that sediment actually works: after a normal conversation accumulates
~15 tool calls, `status` should show pending sediments under `sediment_skills/`.
`doctor` also prints these two steps at the end.

## Path Environment Variables (multi-pod / non-standard environments)

| env | Default | Description |
|-----|---------|-------------|
| `OPENCLAW_WORKSPACE` | `~/.openclaw/workspace` | Workspace root (plugin dir lives here) |
| `OPENCLAW_CONFIG` | `~/.openclaw/openclaw.json` | Config file (only needed when allow non-empty) |
| `SKILL_SEDIMENT_AGENTS` | `main` | Default validAgentId |
| `SKILL_SEDIMENT_CDN` | (empty) | Fallback URL for the plugin tarball (only used if the bundled `assets/` copy is missing; typical installs never use this) |
| `SKILL_SEDIMENT_SHA256` | (empty) | Optional sha256 checksum for the downloaded bundle |
| `SKILL_SEDIMENT_TZ` | `Asia/Shanghai` | Timezone for any local time formatting in diagnostics |

Convention plugin path (auto-computed, no manual config needed):

/.openclaw/extensions/skill-sediment/

## Sediment Mechanism (FAQ after install)

- **Trigger**: every ~15 tool calls, a background review sub-Agent is kicked off (`nudgeInterval` is tunable)
- **Output**: `sediment_skills/*.md` (pending) → after a second hit, promoted to `skills/*.md` (activated)
- **Second-hit logic**: a different parent session hits again, OR the sediment is ≥1 day old and the same session hits again
- **Eviction**: untouched for 10 days → auto-evict / max 20 per agent / 3-day grace for new ones
- Full architecture (6 Gates / lifecycle / promote guards) is in `references/sediment-internals.md`

## License

MIT — see [LICENSE](./LICENSE) for the full text.

When publishing to clawhub.com the platform re-licenses uploads as MIT-0 (No
Attribution); the GitHub source tree remains true MIT. See clawhub docs for details.

## Dependencies

Runtime:

- **Python 3.8+** (uses `pathlib`, `argparse`, `subprocess`, `urllib`, `json` — all stdlib, no `pip install` needed)
- **OpenClaw runtime** with the `plugin-sdk` module — the verified baseline is `2026.3.8`;
  `install` will warn or refuse on older versions
- **`openclaw` CLI** available on `PATH` (used for `gateway restart` and optional
  `agents list` discovery)

No third-party Python packages are required.

## Environment Variables (read by `scripts/manage.py`)

The script reads the following environment variables. They are all optional with
sensible defaults; this list is provided for audit transparency.

| Env | Purpose |
|-----|---------|
| `OPENCLAW_WORKSPACE` | Workspace root (default `~/.openclaw/workspace`) |
| `OPENCLAW_CONFIG` | Path to openclaw.json (default `~/.openclaw/openclaw.json`) |
| `OPENCLAW_CORE_PKG` | OpenClaw core package.json (default `/app/package.json`) |
| `OPENCLAW_PLUGIN_SDK` | plugin-sdk directory (default `/app/dist/plugin-sdk`) |
| `SKILL_SEDIMENT_AGENTS` | Default `validAgentId` (default `main`) |
| `SKILL_SEDIMENT_CDN` | Optional fallback URL for the plugin tarball (default empty) |
| `SKILL_SEDIMENT_SHA256` | Optional sha256 for the downloaded bundle (default empty) |
| `SKILL_SEDIMENT_DETECT_WAIT` | Read-back detection window in seconds (default 20) |
| `SKILL_SEDIMENT_TZ` | Timezone for diagnostics formatting (default `Asia/Shanghai`) |
| `HOME` | Standard POSIX home dir; used to resolve workspace/config defaults |
| `LOBI_SYNC_ENABLED`, `APPID`, `APOLLO_META`, `APOLLO_APP_ID` | Managed-env signals (read-only detection; never written) |

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Songhonglei](https://github.com/Songhonglei)
- **Source:** [Songhonglei/build-better-skills](https://github.com/Songhonglei/build-better-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.