hum

1. Init — /hum init sets up the data directory with template files (VOICE.md, CONTENT.md, AUDIENCE.md, CHANNELS.md, knowledge/index.md) and folders. After running init.py, also run bash setup.sh from the repo root to create the venv and install Python dependencies. All subsequent scripts require the venv (venv/bin/python3).
2. Refresh feed — /hum refresh-feed fetches your X home feed (via Bird filter:follows), configured X profiles, Hacker News, YouTube, and knowledge sources (RSS, sitemaps, YouTube transcripts, podcasts from knowledge/index.md) — all via direct APIs with no browser automation. Ranks items, sends a digest to Telegram, saves aggregated data to feeds.json
3. Crawl knowledge — /hum crawl independently crawls knowledge sources defined in knowledge/index.md. Saves full articles to knowledge//. Also runs as part of refresh-feed.
4. Manage sources — /hum sources adds, removes, and lists social/ephemeral feed sources in sources.json
5. Brainstorm — /hum brainstorm researches each content pillar across YouTube, X, Reddit, Hacker News, Polymarket, and web, then saves ideas to ideas.json
6. Learn — /hum learn analyzes feed trends and platform algorithms, updates context files
7. Manage ideas — /hum ideas shows the pipeline as numbered plain text. Format: 1. ID · Title · platform · status. One idea per line. No markdown tables, no bullet points, no code blocks.
8. Review drafts — /hum content lists current saved draft files and generated assets

⚠️ Always use /hum create and read VOICE.md + content-samples/ when drafting posts. Follow the create flow: research → outline → approval → draft. Do not produce a draft without an approved outline.

1. Draft posts — /hum create [platform] [type] [idea] follows a strict 4-step process:
• Step 1 — Load context: read VOICE.md, CHANNELS.md, content-samples/, knowledge/, the idea from ideas.json
• Step 2 — Research: 3-5 web searches (core topic, stats, contrarian, examples, adjacents); build a fact base; present findings
• Step 3 — Propose outline: style selection (with rationale) + hook/angle/structure + research summary; do NOT write prose yet; get user approval first; style must be named and justified using STYLES.md
• Step 4 — Write: only after outline is approved; match user's voice from content-samples/; present draft; iterate until approved
• ⚠️ Never skip to drafting without research + outline approval — the full CREATE.md process is mandatory
2. Refine — iterate on drafts until approved, then save
3. Publish — /hum publish posts approved drafts to LinkedIn or X via API scripts
4. Engage — /hum engage handles follow suggestions, outbound engagement plays, and replies/comments

Configuration

The skill stores all data in a configurable directory. Set the HUM_DATA_DIR environment variable:

export HUM_DATA_DIR=~/Documents/hum

If not set, defaults to ~/Documents/hum. When running inside OpenClaw, it also reads from openclaw.json → skills.entries.hum.config.hum_data_dir (or the legacy data_dir key for existing installs).

Data Directory Structure

All user-owned data lives in :

Writing Guidelines

• Always read content-samples/ before drafting — these are real examples of the user's writing and the most authoritative reference for their voice.
• Always read knowledge/ before drafting — any reference material the user has placed there should inform the content.
• Always read VOICE.md for tone and style rules.

Post Types

Each post type has a defined structure. The /hum create command requires a platform and post type.

X

LinkedIn

Actions & Connectors

Actions live in scripts/act/, connectors in scripts/act/connectors/ (one per channel):

• Connectors (act/connectors/):
• x.py — X API v2 (requires credentials/x.json or X_USER_ACCESS_TOKEN env var)
• linkedin.py — LinkedIn REST API (requires credentials/linkedin.json or env vars)
• All connectors follow a uniform interface — see act/connectors/__init__.py for the load(platform) dispatcher
• Actions (act/):
• publish.py — draft parsing, preview, and publishing via connectors
• engage.py — follows, comments, replies
• analyze.py — account insights and post analytics
• Browser-based actions (when API is unavailable) are handled by the agent via the browser tool.
• Never put secrets in the skill files. Read them from credentials/x.json, credentials/linkedin.json, or env vars.

Image Generation

Images for posts are generated using the bundled image-gen library at scripts/lib/image-gen/. It provides a unified interface to multiple AI image providers:

API keys are set as environment variables or in openclaw.json → env.vars. The active provider is configured in openclaw.json → skills.entries.hum.config.image_model (default: gemini) or via the HUM_IMAGE_MODEL env var.

When drafting, add image_prompt to the post. Calling validate(post) auto-generates the image and sets media_path. If VOICE.md has a ## Visual Style section, it is automatically appended to the image prompt.

Daily Loop

/hum loop runs the full morning workflow. See LOOP.md for the step-by-step instructions. Individual steps call scripts from scripts/ where needed.