hum

AI content writer that researches, outlines, drafts, publishes, and manages engagement for LinkedIn and X using your voice and style guidelines.

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/<source>/. 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.
9. 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
10. Refine — iterate on drafts until approved, then save
11. Publish — /hum publish posts approved drafts to LinkedIn or X via API scripts
12. 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 <data_dir>:

Path	Purpose
<data_dir>/VOICE.md	Voice, tone, and writing guidelines
<data_dir>/AUDIENCE.md	Target audience definition
<data_dir>/CHANNELS.md	Publishing platforms and rules
<data_dir>/CONTENT.md	Content pillars with keywords for feed classification
<data_dir>/ideas/ideas.json	Brainstormed content ideas and brainstorm config
<data_dir>/content/drafts/	Unpublished drafts (outline → draft → ready)
<data_dir>/content/published/	Drafts moved here after successful publish
<data_dir>/content/images/	Generated images, cover art, diagrams
<data_dir>/content-samples/	Real posts from the user's social media — primary voice reference
<data_dir>/knowledge/	Reference material — auto-crawled from knowledge/index.md sources (RSS, sitemaps, YouTube transcripts, podcasts) plus user-curated notes
<data_dir>/knowledge/index.md	Knowledge source definitions (Key, Handler, Feed URL tables)
<data_dir>/feed/feeds.json	Aggregated feed — single source of truth for brainstorming
<data_dir>/feed/raw/	Per-source JSON crawl outputs
<data_dir>/feed/sources.json	Social/ephemeral feed sources (X accounts, YouTube creators, websites) — managed via /hum sources
<data_dir>/feed/assets/	Preference learning (rankings, feedback history, dedup tracker)

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

Post Type	Format
Tweet	Single tweet, under 280 chars, hook-driven. Optional media.
Thread	Multiple numbered tweets, each under 280 chars. Hook in tweet 1.
Article	Long-form post, up to 25,000 chars. Premium subscribers only. Rich text formatting, cover image, published directly to the X feed. Functions like a mini blog post. Requires cover image. Draft in full prose with H2 section headers.

LinkedIn

Post Type	Format
Post	Under 200 words. Short paragraphs. Opens with observation, ends with reflection/question.
Article	Long-form, 600–1000 words. Section headers. Requires cover image and intro feed post.

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:

Provider	Model	Env Var
gemini (default)	gemini-2.5-flash-image	GEMINI_API_KEY
openai	gpt-image-1	OPENAI_API_KEY
grok	grok-2-image	XAI_API_KEY
minimax	image-01	MINIMAX_API_KEY

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.