create-article

Files (1)

• SKILL.md

SKILL.md (first lines)

# Write Article

Produces a high-quality article from a target audience definition and a set of relevant sources.
Adapts tone, depth, and structure to fit the audience.

## Prerequisites

- **Target audience**: Who will read this article (e.g., "senior backend engineers", "product managers unfamiliar with ML", "general tech enthusiasts")
- **Relevant sources**: URLs, file paths, or inline content to draw from (research papers, blog posts, docs, notes, etc.)
- **Topic** (optional): If not inferable from sources, state the article topic explicitly

If sources are not yet gathered, run `/research-article` first to discover the state of the art and produce a research brief whose key sources feed this skill.
If you decide not to run it, say so and give your reasoning before proceeding, so the user can course-correct.

This applies to **every** article, including opinion and perspective pieces.
An opinion piece is not exempt from research: before taking a position, gather the sources that inform it (the strongest arguments for and against, relevant data, prior writing on the topic) and cite them.
Research is the difference between a supportable position and an unsupported hot take, and it is what the reader uses to judge the argument.
If a perspective piece genuinely has no external sources (for example, it reports on the author's own first-hand experience), say so explicitly and note what the argument is based on instead.

## Planning

For a **long-form article** (roughly four or more sections, or any article whose structure is not already fixed by a template), settle the argument and structure before drafting by running the [`create-article-plan`](../create-article-plan/SKILL.md) skill, which writes `plan.md` next to the article.
Skip it for a **short templated piece** (for example a research note on a fixed skeleton), where the template is the plan, and for a revision that does not change the argument or section structure.
The plan's format and self-check live in that skill; this skill owns drafting and revision.
Draft from `plan.md` when one exists, so the article delivers the planned argument.

## Steps

1. Read all provided sources thoroughly.
   If none were provided, including for an opinion piece, research the topic first (see Prerequisites) rather than writing from prior belief alone.
2. Identify the core insight or argument the article should convey.
3. Calibrate tone and depth to the target audience.
4. **Plan the article** (see "Planning" above).
   For a new long-form article, run the [`create-article-plan`](../create-article-plan/SKILL.md) skill to write `plan.md` next to the target article file.
   Skip it for a short templated piece (the template is the plan), and for a revision that does not change the argument or structure.
5. Draft the article from the plan (or from the core insight and audience when no plan was written), using the structure below and following the formatting rules.
6. Add visualizations where they aid comprehension (see "Visualizations" below).
7. Verify all links: curl every URL in the article and replace any that return 4xx, 5xx, or connection errors.
8. Discover related articles in the same repository (see "Finding Related Articles" below) and add a "See also" section.
9. Revise for clarity, flow, and conciseness.
10. Include an `agent_sessions` list in the frontmatter, holding the identifiers of every LLM/agent session that contributed to the article (use the current session ID from context, and append to the existing list when revising an article).
   The list may contain zero entries: if no session ID is available, omit the field entirely.

## Formatting Rules

- **Shared writing rules**: Apply [`../communication-guidelines/references/writing-rules.md`](../communication-guidelines/references/writing-rules.md) to every sentence.
  It owns the catalog of machine-writing patterns to remove.
- **One sentence per line**: Each sentence occupies its own line in the markdown source.
  This produces cleaner git diffs since changes to one sentence don't affect adjacent lines.
  Paragraphs are separated by a blank line, with sentences within a paragraph on consecutive lines (not separated by blank lines).
- **Link all sources**: Every source referenced in the article body must include a verified hyperlink, not just a textual citation (e.g., `[Author, "Title"](https://...)` not just `Author, "Title"`).
- **Verify links**: After drafting, curl every hyperlink and replace any that return 4xx or connection errors before finalizing the article.
- **Bold important statements**: Highlight the most important statements, key claims, and takeaways in **bold** so readers scanning the article still capture the core message.
  Be selective: bold sentences or phrases that carry the argument, not routine sentences.
  Avoid bolding more than one statement per paragraph on average.
- **Plain language**: Write so the reader grasps the meaning on the first pass.
  Prefer common, everyday words over less frequent synonyms (for example, "use" over "utilize", "help" over "facilitate", "show" over "elucidate"), short sentences over long ones, and active voice over passive.
  Write literally: no metaphors, similes, idioms, or other figurative language, since the reader must decode the comparison before reaching the meaning.
  Keep technical terms where they are the precise and expected choice; the goal is to avoid uncommon or showy words, not to lose precision.
  Calibrate this to the audience: write simpler for general readers, and allow more domain terms for expert readers.
- **No prose, state things directly**: Write straight to the point.
  Every sentence must convey information.
  Avoid metaphorical, idiomatic, or ornamental phrasing that the reader must decode before reaching the meaning, and avoid filler that adds rhythm but no content.
  For example, write "Four governance problems present themselves when multiple agents work for you" rather than "Four governance problems become top priorities when multiple agents work for you".
  If a phrase paints a picture instead of saying the thing, replace it with the plain statement.
- **Name the referent**: Avoid bare referential words like "this", "that", "these", and "those" when the referent could be ambiguous, since they force the reader to backtrack and resolve what is meant.
  Prefer naming the thing directly.
  For example, write "the parser fails on nested generics" rather than "this fails on nested generics", or "that approach trades latency for throughput" rather than "that trades latency for throughput".
  Referential words are acceptable when the referent is unambiguous and immediately adjacent, or when repeating the noun would be clunky.

## Visualizations

Generate a few visualizations per article whenever they aid comprehension.
A visualization earns its place when it communicates an idea faster than prose: diagrams for structure and flow, charts for data, illustrations for concepts, annotated figures, comparisons, or timelines.
Skip visualizations for short or purely narrative pieces, and never add one that only restates what the surrounding text already says clearly.

**Choosing a format:**

- **SVG (default)**: Write each visualization as an SVG file stored next to the article, and reference it with a repository-relative path.
  Follow the `create-svg-image` skill for creating the SVG.
  SVG is the most expressive option: full control over layout, color, typography, and annotations, and it looks consistent in any viewer.
  It covers everything from charts and annotated illustrations to precise technical diagrams.
  Verify the referenced file exists before finalizing the article.
- **Mermaid**: Use a fenced code block marked `mermaid` for any Mermaid diagram type (flowcharts, sequence diagrams, state diagrams, ER diagrams, Gantt charts, mindmaps, timelines, and more) where the built-in layout is enough and a hand-built SVG would add little.
  Follow the `create-mermaid-visualization` skill for diagram type selection, syntax, and validation.
  It renders on GitHub and most markdown viewers, keeps the article self-contained, and diffs cleanly.
  Example:

  ```mermaid
  flowchart LR
      A[Sources] --> B[Research brief]
      B --> C[Draft article]
      C --> D[Review]
      D -->|findings| C
  ```

**Rules:**

- Keep each visualization focused on one idea, and label every element.
- Place the visualization immediately after the paragraph that introduces the concept, preceded by a one-sentence lead-in.
- Mermaid code blocks are exempt from the one-sentence-per-line rule.
- Calibrate technical depth to the audience: conceptual overviews for general readers, precise labels and types for experts.

## Audience Calibration

| Audience type | Tone | Depth | Jargon |
|---|---|---|---|
| Technical experts | Peer-to-peer, direct | Deep, assume fundamentals | Domain terms fine |
| Practitioners (non-expert) | Instructional, approachable | Moderate, explain non-obvious concepts | Define on first use |
| General / non-technical | Accessible, engaging | Conceptual, avoid implementation details | Avoid or translate |
| Decision-makers | Business-focused, outcome-oriented | High-level, emphasize impact | Minimal |

## Article Structure

```markdown
---
audience_notes: >
  [one line on any assumptions made about the audience's prior knowledge]
agent_sessions:

From tomzx/agents, MIT.

More from tomzx/agents