bankr-twitter-agent

What this skill does

# Skill: twitter-agent
> Build and run one or more Twitter/X agents, each with a distinct personality, storyline, and post-image library.

# Twitter Agent Skill

This skill provides a framework for creating, managing, and automating Twitter/X agents with persistent personalities and voices. It supports running multiple agents side-by-side, each with its own files and (optionally) its own X account.

## Prerequisites

### X Account Setup (REQUIRED — Do This First, Per Agent)

Every agent's X account MUST be marked as an **automated account** before it posts a single tweet. X requires this disclosure; skipping it is the fastest way to get suspended.

**Exact path:**
1. Log in as the agent account on x.com.
2. Go to **Settings and privacy** → **Your account** → **Account information**.
3. Scroll to **Automation** and tap it.
4. Enter the password when prompted.
5. Set **Managing account** to the human/handle responsible for the bot and save.

Direct link (while logged in as the agent account): https://x.com/settings/account/automation

This adds the "Automated by @…" label to the profile and replies. Non-negotiable — do this once per agent account.

### Environment Variables (Default + Per-Agent Override)

This skill supports a single default credential set (for the primary / only agent) AND per-agent overrides (when running multiple agents with distinct X accounts).

**Default credentials** (used by the primary agent or any agent that does not have overrides):
- `X_API_KEY`
- `X_API_KEY_SECRET`
- `X_ACCESS_TOKEN`
- `X_ACCESS_TOKEN_SECRET`

**Per-agent overrides** (optional; only required when a second+ agent uses a different X account):
- `X_API_KEY_{SLUG_UPPER}`
- `X_API_KEY_SECRET_{SLUG_UPPER}`
- `X_ACCESS_TOKEN_{SLUG_UPPER}`
- `X_ACCESS_TOKEN_SECRET_{SLUG_UPPER}`

`{SLUG_UPPER}` is the agent's slug uppercased with hyphens converted to underscores. Example: the agent at `/agents/tn100x-intern/` looks up `X_API_KEY_TN100X_INTERN` first.

**Resolution order at post-time:**
1. Look up `X_*_{SLUG_UPPER}` for the target agent's slug.
2. If any of the four suffixed vars is missing, fall through to the default `X_*` set.
3. If still unset, error with a message naming both env var forms and the slug.

Generate all keys from the [X Developer Portal](https://developer.x.com/en/portal/dashboard) with **Read and Write** permissions enabled.

### Approval Channel for Flagged Drafts (Optional)

When a draft hits a guardrail, the automation does not post it — it ends its run by surfacing the draft in its final output message so you can approve or reject manually. Where that final message gets delivered is up to you: Bankr automations natively support **Telegram** (link Telegram once, select it as the output destination per automation, no bot token or custom code needed) but any destination Bankr automations support works. If you don't configure an output destination, flagged drafts are still logged to the `## Pending Approval Queue` in storyline.md — you'll see them on the next manual session.

## Agent Directory Structure

Each agent lives under its own folder at `/agents/{slug}/`. A top-level index file lists all agents. Every agent folder follows a predictable layout so automations and manual sessions can discover files the same way.

```
/agents/
  index.md                       ← TOP-LEVEL INDEX: lists all agents + path to each bundle.md
  {agent-slug}/
    bundle.md                    ← PER-AGENT MANIFEST: agent metadata + paths + fileIds for every file this agent uses
    personality.md               ← voice, style, vocabulary rules (required)
    storyline.md                 ← narrative history, entry log (required)
    post-images/                 ← library of images the agent can attach to posts
    references/                  ← (optional) arc-state, trade ledgers, trading configs, any other per-agent docs
    archive/                     ← pre-compaction storyline snapshots
  {next-agent-slug}/
    bundle.md
    ...
```

**How the agent discovers files at runtime:**
1. The user names the agent (slug, handle, or "default agent"). If ambiguous, read `/agents/index.md` and ask.
2. Read `/agents/{slug}/bundle.md` — this is the manifest. Every other file path is resolved through it.
3. Read the files the current operation needs (always personality + storyline; references as needed).

### Top-Level Index: `/agents/index.md`

A simple markdown table listing every agent. Minimal required columns:

```markdown
# Twitter Agents Index

| Slug | Handle | Bundle |
|------|--------|--------|
| tn100x-intern | @theinternbot | /agents/tn100x-intern/bundle.md |
| {next-slug} | @{next-handle} | /agents/{next-slug}/bundle.md |
```

### Per-Agent Bundle File: `/agents/{slug}/bundle.md`

The bundle is the manifest. It declares agent metadata and paths to every file this agent uses. Template:

```markdown
# Agent Bundle: {Display Name}

## Metadata
- **agent_slug**: tn100x-intern
- **agent_name**: The TN100x Intern
- **x_handle**: @theinternbot
- **x_account_url**: https://x.com/theinternbot
- **created**: 2026-04-22
- **env_var_prefix**: TN100X_INTERN  (uppercase slug used in X_API_KEY_{PREFIX} etc.; omit to use default X_* vars)

## Files (required)
- **personality**: /agents/tn100x-intern/personality.md  (fileId: …)
- **storyline**: /agents/tn100x-intern/storyline.md  (fileId: …)

## Files (optional)
- **arc_state**: /.memory/project_intern_trade_awareness.md  (fileId: …)
- **trade_outcomes**: /intern/trade-outcomes.md  (fileId: …)
- **trading_config**: /intern/trading-config.md  (fileId: …)

## Post-image library
- **post_images_folder**: /agents/tn100x-intern/post-images/
- Filename convention: descriptive, kebab-case (e.g. `intern-at-desk-plus38.png`).
- Pulled at post-time by reading the filename from the folder; no manifest needed.

## Archive
- **archive_folder**: /agents/tn100x-intern/archive/
```

Bundle.md is the single source of truth for "where does this agent keep X". If a file lives outside `/agents/{slug}/` (e.g. legacy paths at root or in `/.memory/`), the bundle's path entry just points at the current location — files don't have to be moved to be listed.

### Post-image Library: `/agents/{slug}/post-images/`

Every agent has a folder of images it can attach to posts. Usage:
- The user drops images into this folder (hand-drawn art, designed graphics, screenshots, reaction images — anything that might get attached to a tweet).
- When drafting a tweet that wants an image, reference a file from this folder by name.
- Posting uploads the image as media via the X v1.1 media endpoint, then attaches the returned `media_id` to the v2 tweet call.
- Prefer user-provided images when available. If none fit, text-only post is the default.

## The Personality & Storyline System

Every agent requires, at minimum, `personality.md` and `storyline.md` in its folder.

### Building a Personality

If an agent has no personality.md, walk the user through creating one by asking:

1. "what's the account about? give me the elevator pitch"
2. "how would you describe the vibe? pick a few: sharp, witty, degen, serious, chaotic, chill, academic, edgy, wholesome, provocative, technical, meme-heavy"
3. "what topics do you want to tweet about? what's strictly off-limits?"
4. "short punchy tweets or longer form? threads?"
5. "emojis? hashtags? lowercase or proper grammar?"
6. "any signature phrases or words you always use?"
7. "give me 2-3 example tweets that sound like you — or accounts you want to sound like"
8. "is there a character or persona the account should tweet as? or is it just you?"

Save as `/agents/{slug}/personality.md` and register the path in bundle.md.

### Pre-Flight Checklist

Before composing or posting any tweet, the agent MUST:
1. Resolve the target agent slug (from the user's request or the default agent).
2. Read `/agents/{slug}/bundle.md` to discover all file paths.
3. Read `personality.md` and `storyline.md` via the paths in bundle.md.
4. If the bundle declares