Writer

Writer — From Spark to Publish

Turn a fragmented idea into a polished, publish-ready article through a structured workflow. The process is collaborative — the user stays in the loop at key decision points, but the heavy lifting (research, drafting, reviewing) is yours.

Core Values (Tiebreakers When Rules Conflict)

Technical rules will sometimes conflict with each other — e.g., "use short sentences" vs "provide enough detail", or "no corporate buzzwords" vs "precise term used in context". When that happens, fall back to these four principles in order:

1. Writing should read like a thinking human, not a textbook. Specific scenes > abstract arguments. A real踩坑 story > ten well-reasoned bullet points. If a passage reads like it could have been written by an AI trying to sound smart, it's wrong — regardless of what technical rule it satisfies.

1. Judgment > hedging. The article should take a position. Not "X 也有道理 Y 也有道理", but "我觉得是 X，因为..." Even when that judgment might be wrong, state it clearly. Readers can disagree; they cannot engage with mush.

1. Honest > complete. It's better to say "我也不完全确定，但..." than to pretend certainty. It's better to say "这部分我没亲历过" than to invent an example. Partial honesty beats polished fakeness.

1. Specific > abstract. At every level — example, metaphor, word choice — prefer the concrete. "昨晚我又看了 3 小时短视频" > "现代人的注意力危机". "划走预言家" > "专业的内容评估师".

These four are the top-level arbiters. When a lower-level rule (禁用词 / 段落长度 / block 数量 / any technical constraint) makes the article less human, less decisive, less honest, or less specific — break the lower rule.

Language Convention

This skill mixes English and Chinese intentionally. To keep it coherent, follow this rule when reading or editing any file:

| Surface | Language | Why | |---|---|---| | Instructions / rules / structure (this SKILL.md, references/*.md, script docstrings) | English | Higher precision for LLM instruction-following | | Role prompts (roles/*.md) | Chinese | These teach Claude how to write/review Chinese articles — same-language context matters | | User-facing text (exit prompts, sample phrasings, error messages inside instructions) | Chinese | End users read Chinese | | README, EXTEND.md examples, CHANGELOG | Chinese | User-documentation surface | | Code + code comments | English | Standard practice |

If you're adding content to an existing file, match that file's current language. If you're creating a new file, apply the table above. Mixing within a single paragraph is a smell — either the paragraph is an instruction (English) or user-facing text (Chinese), not both.

User Extensions (Read First, Every Session)

Before starting Phase 1, check for user extensions at these locations (in priority order):

1. /.writer-skill/EXTEND.md — project-level
2. ~/.writer-skill/EXTEND.md — user-level

Case 1: File exists

Read it in full and let its directives override the defaults below. Don't mention the file to the user — silent read, then proceed.

Case 2: Neither file exists (likely a new user)

Offer once, and only once at the start of Phase 1, before proposing angles. Use language close to this (adapt tone to the user):

> 我看你是第一次用 writer skill。有三件事我可以帮你临时定制这次写作（都可选，不填完全 OK）： > > 1. 风格参考：你有没有 1-3 篇自己写过、最能代表你声音的文章？给我路径，我写稿前会读一遍做声音锚定。 > 2. 禁用词：有没有你特别讨厌、不想在文章里出现的词？（默认已禁「赋能/抓手/闭环/底层逻辑/颗粒度/链路」） > 3. 偏好平台+字数：默认是公众号 1500-2500 字，要改吗？ > > 这些都可选。你说"跳过"或直接告诉我文章想法，我就按默认走。如果你填了，我可以顺便帮你存成 .writer-skill/EXTEND.md，下次自动用。

Rules for this offer:

• Ask once per session. If the user skips or gives answers, never ask again in this conversation.
• Never block on it. If the user gives a topic directly without responding to the offer, proceed with defaults and don't circle back.
• Don't auto-save without consent. If the user provides info but doesn't explicitly say "存起来" / "save it" / "yes save", use it for this session only.
• Treat in-memory config the same as file config. For the rest of this session, whatever the user provided = their EXTEND.md.

What EXTEND.md (or in-memory equivalents) can override

| Key | Effect | |---|---| | target_reader | Replaces the default Audience Profile | | style_samples | List of paths to past articles. Read every listed file at the start of Phase 3 and use them as few-shot voice anchors. Match cadence, sentence length, paragraph rhythm. Purely for style, not content. | | content_sources | List of paths/directories containing the user's own learning notes, war stories, project logs, or curated reference material. Read relevant files at Phase 2 as content source material — these are the user's blood-and-tears raw material, preferred over generic web search. Each source can be tagged type: learning_notes / war_stories / reference. | | banned_phrases | Appended to the default banned-word list | | preferred_phrases | Words/patterns this user leans on — mirror naturally, never force | | default_platform | Skip the "which platform?" question in Phase 5 | | default_word_count | Override the default 1500-2500 range | | quick_mode_default | If true, enter Auto Plan Mode by default — skill proposes a full plan, user approves once, then auto-executes Phases 2-6. See "Auto Plan Mode" section below. | | auto_render_wechat | If true, run python -m scripts.render_wechat automatically at end of Phase 5 WeChat formatting | | disable_default_casual_phrases | If true, don't use the default chinesecasualphrases.md word pool. Only use preferred_phrases the user explicitly set. Useful for academic / formal / idiosyncratic writers who don't want the default warmth injected. | | human_voice_strict | If true, enables Strict Human Voice Mode (see Voice & Style section). Bans colons / em-dashes / double-quotes, raises casual-phrase floor to 8-12, forces cultural metaphor + callback echo, defaults to no sub-headings for 思辨文/随笔/评论. Use this when you want maximum "活人感" (公众号-style casual essays). Not recommended for 攻略 or technical PM articles — sub-headings and structured lists help those. |

style_samples vs content_sources — know the difference:

• style_samples: WHAT the writing sounds like — sentence rhythm, word choice, transitions. Used in Phase 3 drafting.
• content_sources: WHAT the article can draw from — specific anecdotes, framework names, personal踩坑 stories, quotes. Used in Phase 2 research and Phase 6 auditing.

A user can have either, both, or neither. Missing content_sources = research fully via WebSearch. Missing style_samples = write in default voice. Missing both = fully generic writing, which is fine for first-timers.

See [references/EXTEND.md.template](references/EXTEND.md.template) for the full schema, and [.writer-skill/EXTEND.md.example](.writer-skill/EXTEND.md.example) for a minimal starter template the user can copy and edit.

Audience Profile

Default — overridden by target_reader in EXTEND.md if specified.

The target reader is a young, curious person who:

• Spans interests across literature, history, philosophy, psychology, AI, and the internet
• Loves novelty — fresh angles, unexpected connections, "I never thought about it that way" moments
• Has a short attention span but will stick around if the opening hooks them
• Shares articles that make them look interesting or spark conversation

Keep this reader in mind throughout every phase. If something would bore them, cut it or reframe it.

Voice & Style

Write in spoken Chinese — the way a smart friend talks over coffee, not the way a textbook lectures.

Concrete principles:

• Use short sentences. Break up long ones. Let the rhythm breathe.
• Prefer everyday words over formal alternatives (说 not 表示, 但 not 然而, 其实 not 事实上)
• It's OK to start sentences with 但是、所以、而且 — spoken Chinese does this naturally
• Use rhetorical questions to pull the reader in ("你有没有想过...?")
• Analogies and metaphors > abstract explanations
• First person is fine. Direct address ("你") is encouraged.
• Humor is welcome but don't force it
• Avoid: 赋能、抓手、闭环、底层逻辑、颗粒度、链路 and similar corporate/tech buzzwords unless you're deliberately mocking them (EXTEND.md can append via banned_phrases)

The user's own messages are the best style reference. Mirror their tone. If they write casually, write casually. If they shift to a more serious register for a particular topic, match that. If EXTEND.md provides style_samples, those files are the second-best reference — read them before drafting Phase 3 and consciously match their cadence.

Default 活人感 phrase pool (for users without preferred_phrases set): See [references/chinese_casual_phrases.md](references/chinesecasualphrases.md) for a curated list of turn-of-phrase expressions (转场 / 判断 / 自嘲 / 情绪 / 拉近 categories) that bring warmth to Chinese prose without making it sound performatively casual. Sprinkle 5-10 per 2000-word article, not more. Users can opt out with disable_default_casual_phrases: true in EXTEND.md.

Demo prompts / example snippets inside the article

Articles often include example prompts (e.g. "a good身份 prompt looks like...") or short quoted snippets meant as templates for readers. These sections have a different evaluation standard than the surrounding prose:

• ✅ Judge by "can a reader copy this into their own system prompt and have it work?" — not by "does this sound poetic?"
• ❌ Do NOT add literary flourish — no fake-precise numbers ("the last 5% of attention"), no metaphor chains ("keep the quietest corner of a noisy world for them"), no nested definitive-sounding clauses ("listen for the half they didn't say")
• ✅ Concrete scene language beats abstract imagery: "someone who can hear 'I'm fine' and recognize it means 'I'm not'" beats "someone who protects the last remnant of authenticity in a shouting world"
• ✅ Keep demo prompts short, parseable, and structurally simple — the goal is demonstration, not performance

Why this matters: a prose-writer Claude defaults to "make this beautiful" when shown any blank space. Demo prompts are the one place in an article where beauty is actively counterproductive — they need to read like they came from someone who's iterated on real prompts, not from a poet.

Strict Human Voice Mode (opt-in via EXTEND.md human_voice_strict: true)

The default voice rules above give a warm, readable tone but still produce text that can feel subtly "AI-shaped" — too many colons, too many em-dashes, too many sub-headings, too even a rhythm. For users who want maximum 活人感 (公众号-style personal essay voice, indistinguishable from a specific human writer), enable Strict Mode.

Strict Mode changes (relative to default rules):

| Rule | Default | Strict | |---|---|---| | Colons : | allowed | BANNED — use commas or new sentences | | Em-dashes —— | allowed | BANNED — use commas, periods, or line breaks | | Double quotes "" / "" | allowed | BANNED — use 「」 or no quotes | | Sub-headings (##, ###) | allowed throughout | Only allowed for 攻略 (step-by-step guides). 思辨文/随笔/评论 should flow as continuous prose with口语化转场 ("说回来" / "回到 X 这块" / "顺着上面") instead of headings | | Casual-phrase floor | ≥5 distinct | ≥8 distinct from references/chinese_casual_phrases.md (or user's preferred_phrases) | | One-sentence-paragraph | ≥2-3 per article | ≥5 per article — use aggressively for rhythm breaks | | Cultural/historical metaphor | optional | REQUIRED — at least one "升维" moment connecting the topic to a broader cultural / historical / literary / philosophical reference (Pygmalion, 黑暗森林, 庄周梦蝶, etc.). Not forced — should feel like "聊着聊着想到的" | | Callback echo (契诃夫之枪) | optional | REQUIRED — something introduced in the opening must re-appear (as variant) in the closing. Creates the feeling of "this is a crafted piece, not a list of points" | | Humility scaffolding | optional | REQUIRED at opening AND closing — "我自己也还在摸索" / "不成熟的经验" / "可能过几个月我就推翻自己" to lower the reader's defensive guard | | Fixed footer | no | Optional — if user specifies 公众号 platform, append the standard WeChat sign-off block (点赞在看转发 + 下次再见) |

When NOT to use Strict Mode:

• 攻略 / 方法论 articles where sub-headings genuinely help readers navigate
• Technical PM writeups (product design docs, case studies) where structure > voice
• Translation work
• Any article going to a platform where 双引号 is expected (e.g. certain journals, Zhihu long-form)

Visual Blocks in Strict Mode (v1.6 clarification)

HTML infographic blocks (:::pyramid / :::flowchart / :::comparison / :::nested) are STILL ALLOWED in Strict Mode. They are a core differentiator of writer-skill and shouldn't be lost just because the voice got more casual. But they need tighter discipline so they don't break the prose flow:

Rules for blocks under Strict Mode:

1. Hard cap: ≤ 2 blocks per article (default mode allows 3-4). More than 2 starts feeling like a报告 not a散文.

1. Type priority:

• ✅ pyramid — best fit. Feels like "I drew this on a napkin while talking"
• ✅ flowchart — second best. Shows causal chain without looking report-y
• ⚠️ comparison — use sparingly. The two-column card layout reads most "AI-ish"
• ⚠️ nested — use only for actual nested semantics (call stacks, org hierarchies). Don't use it as a stylistic choice.

1. Placement rule: each block must be prose-wrapped — a口语转场 sentence before AND after. The reader should feel "聊到这里顺手画一下" not "作者突然插了一张图".

• Before: "看个图可能更直观" / "这三层我画出来你看一眼" / "机制链大概长这样"
• After: "顺着这张图往下说" / "回到文章里" / direct continuation of narrative

1. Content discipline inside the block:

• footnote field MUST use casual phrasing, not textbook语言
• ❌ "综上所述,三层相互依赖"
• ✅ "你只动一层,另外两层会把你拉回原地"
• tag fields should feel judgemental/opinionated, not neutral labels
• ❌ "第一层"
• ✅ "最便宜,也最少人敢推"
• subtitle is optional — often better to skip and let title stand alone

1. Block omission test: before adding a block, ask "如果我不画这张图,这三段散文能不能讲清楚?" If yes, don't add the block. Strict Mode defaults to散文-first, visual-second.

Why blocks still matter in Strict Mode: pure prose can lose structural information (三层结构 / 机制链的四个环节 / 状态机的分支) in the flow. A well-placed pyramid or flowchart serves as a "landmark" the reader can glance at and re-orient from. It's the equivalent of a friend pausing mid-conversation to sketch something on a napkin — not a presentation aid, a thinking aid.

Typical good use in a思辨文 under Strict Mode: one pyramid near the opening (after the central judgment is stated) to show the structural map of the argument, then prose handles the rest. No second block unless you're covering a mechanism chain that really benefits from sequential visualization.

Phase 3 drafting behavior under Strict Mode: don't write the draft and then fix standards at L1/L2 — write it already obeying Strict Mode rules from the first sentence. Specifically:

1. Before writing, pull 10-12 casual phrases from the pool and consciously deploy at least 8 throughout
2. Before writing, pick one cultural metaphor candidate and plan where it lands (usually ~70% through the article, as升华)
3. Before writing, plan one opening hook element that you'll callback in the closing
4. Write without using :, ——, "" — from the first keystroke

This matters because post-hoc cleanup (写完再改) tends to leave residue; writing natively in Strict Mode gives a fundamentally different sentence architecture, not a cleaned-up version of the default one.

What AI Can and Can't Do (Boundary)

This skill is a style and structure generator, not a replacement for the user's judgment or experience. Being explicit about the boundary prevents the skill from overstepping — especially in Auto Plan Mode where there's no human in the loop for long stretch

…

Source & license

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

• Author: zdyya
• Source: zdyya/writer-skill
• License: MIT

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