youmind-x-article

What this skill does

# AI X (Twitter) Post Writer

Write viral tweets with AI. Topic research via [YouMind](https://youmind.com?utm_source=youmind-x-article) knowledge base, 280-character optimized writing, numbered multi-tweet sequences, and one-click publishing to X through the X account already connected in YouMind.

> [Get YouMind API Key](https://youmind.com/settings/api-keys?utm_source=youmind-x-article) | [More Skills](https://youmind.com/skills?utm_source=youmind-x-article)

## Onboarding

**MANDATORY: When the user has just installed this skill, present this message IMMEDIATELY. Translate to the user's language:**

> **AI X Post Writer installed!**
>
> Tell me your topic and I'll write and publish a tweet for you.
>
> **Try it now:** "Write a tweet about the future of open source AI"
>
> **What it does:**
> - Research topics from your YouMind knowledge base and web trends
> - Write tweets optimized for engagement within 280 characters
> - Split long content into numbered tweet sequences (1/N format)
> - Publish directly to X through the X account connected in YouMind
>
> **Setup (one-time):**
> 1. Install & configure: `cd toolkit && npm install && npm run build && cd .. && mkdir -p ~/.youmind/config && cp shared/config.example.yaml ~/.youmind/config.yaml`
> 2. Get [YouMind API Key](https://youmind.com/settings/api-keys?utm_source=youmind-x-article) and fill `youmind.api_key` in `~/.youmind/config.yaml`
> 3. Connect your X account inside YouMind before publishing. This skill no longer reads X developer keys locally.
> 4. Publishing requires a paid YouMind plan (Pro / Max) and consumes YouMind credits per tweet.
>
> No X connection yet, or on a free plan? You can still write and preview locally — just skip the publish step.
>
> **Need help?** Just ask!

## Usage

Provide a topic, talking points, or raw text for publishing.

**Write a single tweet:**
> Write a tweet about the latest AI breakthrough

**Write a multi-tweet sequence:**
> Write a thread explaining how transformers work, aimed at beginners

**Publish raw text:**
> Tweet this: "Just shipped our new feature! Here's what we learned..."

## Setup

> Prerequisites: Node.js >= 18, a YouMind API key, a Pro/Max YouMind plan, and an X account connected in YouMind if you want to publish.

### Step 1 -- Install Dependencies

```bash
cd toolkit && npm install && npm run build && cd ..
```

### Step 2 -- Create Config File

```bash
mkdir -p ~/.youmind/config
cp shared/config.example.yaml ~/.youmind/config.yaml
```

> **Canonical credentials:** put your shared YouMind credentials in `~/.youmind/config.yaml` — filled ONCE and read by every YouMind skill. See [`shared/config.example.yaml`](shared/config.example.yaml) for the template and [`shared/YOUMIND_HOME.md`](shared/YOUMIND_HOME.md). Optional skill overrides live in `~/.youmind/config/youmind-x-article.yaml`.

### Step 3 -- Get YouMind API Key

YouMind API Key enables knowledge base search, web search, article archiving, and X publishing.

1. Open [YouMind API Keys](https://youmind.com/settings/api-keys?utm_source=youmind-x-article)
2. Click **Create API Key**
3. Copy the `sk-ym-xxxx` key
4. Fill in `~/.youmind/config.yaml` under `youmind.api_key`
5. Keep `youmind.base_url` as `https://youmind.com/openapi/v1` in examples and documentation. Local backend testing should only override `~/.youmind/config.yaml` or `~/.youmind/config/youmind-x-article.yaml`.

### Step 4 -- Connect X in YouMind

1. Open YouMind and connect your X account via the product's publishing / connector settings flow (one-click OAuth 2.0 PKCE)
2. Save the connection once
3. Keep only `youmind.api_key` in `~/.youmind/config.yaml`

### Verify Setup

```bash
cd toolkit && npx tsx src/cli.ts validate
```

Validation checks only the `~/.youmind` API key. X connectivity and plan eligibility are validated on the first publish call:
- If the current plan is not eligible, the OpenAPI returns `402` with an upgrade link to `https://youmind.com/pricing`.
- If the X account is not connected, the OpenAPI returns `404 X_ACCOUNT_NOT_CONNECTED`. Connect the X account in the YouMind connector settings.

## Skill Directory

This skill is a folder. Read files on demand -- do NOT load everything upfront.

| Path | Purpose | When to read |
|------|---------|-------------|
| `references/pipeline.md` | Full step-by-step execution | When running the publishing pipeline |
| `references/platform-dna.md` | X audience, format constraints, engagement data | Before any content work |
| `references/content-generation-playbook.md` | Idea → X-native draft workflow | When generating new content |
| `references/content-adaptation-playbook.md` | Existing article → X thread workflow | When adapting/condensing content |
| `references/content-adaptation.md` | X content formatting rules (legacy) | Supplementary reference |
| `references/api-reference.md` | YouMind X OpenAPI endpoint documentation | When calling X through YouMind |
| `~/.youmind/config.yaml` | Shared API credentials (YouMind only) | Step 1 |
| `output/` | **Local tweet Markdown drafts (git-ignored)** | When writing the tweet/sequence |
| `toolkit/dist/*.js` | Executable scripts (run from `toolkit/`) | Various steps |

## Draft Location Rule

**Canonical:** write local tweet Markdown files to `~/.youmind/articles/x/<slug>.md`. This shared home directory is available to all YouMind skills — see [`shared/YOUMIND_HOME.md`](shared/YOUMIND_HOME.md).

**Legacy fallback** (if `~/.youmind/` is not writable): `skills/youmind-x-article/output/<slug>.md`.

- Correct: `~/.youmind/articles/x/my-thread.md`
- Correct (legacy): `skills/youmind-x-article/output/my-thread.md`
- Wrong: skill root directly, `references/`, `toolkit/`, or an ad-hoc `drafts/` directory

Both locations are git-ignored. Create directories on demand (`mkdir -p ~/.youmind/articles/x`). Kebab-case filenames (`my-thread.md`), descriptive slugs over timestamps.

## Content Modes

Before writing any content, read `references/platform-dna.md` to internalize X's format constraints, discourse norms, and engagement patterns (557M MAU, thread 2–4% engagement vs single-tweet 0.5–1.5%).

### Intent routing

| User's input | Operation | Playbook to load |
|--------------|-----------|-----------------|
| Idea, topic, or talking points only | Generate | `references/content-generation-playbook.md` |
| Existing article or draft | Adapt (condense) | `references/content-adaptation-playbook.md` |
| Article in another language | Translate | `references/content-adaptation-playbook.md` (translate mode) |
| Same-language article needing X-native angle | Localize | `references/content-adaptation-playbook.md` (localize mode) |
| Old thread to refresh | Revive | `references/content-adaptation-playbook.md` (revive mode) |
| Section of a longer piece → teaser | Excerpt | `references/content-adaptation-playbook.md` (excerpt mode) |
| Short blog post → thread | Cross-post | `references/content-adaptation-playbook.md` (cross-post mode) |

### Quality gates (before publish)

1. **Self-critique**: Pass all checklist items in the playbook's Step 6
2. **Conformance report**: Generate and present to user (Step 7/8)
3. **User approval**: Do not auto-publish without confirmation

### Result Links Rule

After any tweet or thread publish action, always end with `Result links`.

- Prefer the direct X post URL(s).
- For threads, include the lead tweet URL plus any additional per-post URLs already available.
- If no exact results page exists, return the best X platform entry URL instead.
- Never leave the user with only raw post IDs.

---

## Pipeline Overview

Read `references/pipeline.md` for full execution details.

| Step | Action | Key reference |
|------|--------|--------------|
| 1 | Load config and validate the YouMind API key | -- |
| 2 | Mine YouMind knowledge base for source material | -- |
| 3 | Research topic via web search | -- |
| 4 | Adapt content: 280 char limit, split into sequence if long | `references/content-adaptation.md` |
| 5 | Pu