writeup
/writeup
Use to turn finished work into a published post: Medium, blog, essay, announcement, or launch, especially one needing diagrams. Triggers on: 'write this up', 'write the post for this', 'make a Medium post', 'blog post about X', 'I need images for the post', 'article + diagrams', 'translate the post to Spanish', 'make the post shorter', 'use writeup', 'writeup and debrief'. Finds the argument in the code, drafts it in the author's voice, generates SVG diagrams from the project's own model so they cannot drift, rasterizes to PNG where SVG is rejected, runs an AI-writing detox that leaves the voi
- Author
- lucianoadonis ↗
- Repository
- neorgon-forge ↗
- Licence
- MIT
- Last repository change
- 26.09.2026
Assessment and security
- Files in this package
- 7
- Scripts
- 3
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 26.09.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- 3 scripts in this package. Review them before installing, as Claude may execute them.
Scripts: scripts/check-writeup.sh, scripts/diagram-kit.mjs, scripts/rasterize.mjs
What it does and when to use it
Use to turn finished work into a published post: Medium, blog, essay, announcement, or launch, especially one needing diagrams. Triggers on: 'write this up', 'write the post for this', 'make a Medium post', 'blog post about X', 'I need images for the post', 'article + diagrams', 'translate the post to Spanish', 'make the post shorter', 'use writeup', 'writeup and debrief'. Finds the argument in the code, drafts it in the author's voice, generates SVG diagrams from the project's own model so they cannot drift, rasterizes to PNG where SVG is rejected, runs an AI-writing detox that leaves the voi
Triggers from the description
Arguments
/writeup [draft|diagrams|detox|translate|check] [project]
Original author description
Use to turn finished work into a published post: Medium, blog, essay, announcement, or launch, especially one needing diagrams. Triggers on: 'write this up', 'write the post for this', 'make a Medium post', 'blog post about X', 'I need images for the post', 'article + diagrams', 'translate the post to Spanish', 'make the post shorter', 'use writeup', 'writeup and debrief'. Finds the argument in the code, drafts it in the author's voice, generates SVG diagrams from the project's own model so they cannot drift, rasterizes to PNG where SVG is rejected, runs an AI-writing detox that leaves the voi
How it works
- Commands
- Step 1: Find the argument in the code
- Step 2: Draft in the author's voice
- Step 3: Generate diagrams from the model
- Step 4: Rasterize
- Step 5: Detox, without flattening the voice
- Step 6: Translate (neutral Spanish)
- Step 7: Verify
- When asked to make it shorter
- Invariants
SKILL.md preview
---
name: writeup
description: "Use to turn finished work into a published post: Medium, blog, essay, announcement, or launch, especially one needing diagrams. Triggers on: 'write this up', 'write the post for this', 'make a Medium post', 'blog post about X', 'I need images for the post', 'article + diagrams', 'translate the post to Spanish', 'make the post shorter', 'use writeup', 'writeup and debrief'. Finds the argument in the code, drafts it in the author's voice, generates SVG diagrams from the project's own model so they cannot drift, rasterizes to PNG where SVG is rejected, runs an AI-writing detox that leaves the voice intact, and optionally produces a neutral-Spanish version. Often wanted together with debrief: run both when the user asks for docs about finished work without naming a format. Not for README/docs prose (crafting-effective-readmes for structure, penname for voice) or a deck alone (use debrief)."
argument-hint: "[draft|diagrams|detox|translate|check] [project]"
user-invocable: true
license: MIT
---
# writeup: work into a publishable post, with diagrams that cannot drift
Turns a finished piece of work into something a person would actually read. Two things make
this different from asking a model to "write a blog post": the argument is extracted from the
code rather than invented, and the diagrams are **generated by a script that imports the
project's own model**, so a diagram cannot quietly disagree with the thing it illustrates.
Output lands in `<project>/post/`:
```
post/
├── POST.md # the draft
├── POST.es.md # optional translation
├── build-visuals.mjs # generates the SVGs, imports the project's model
├── rasterize.mjs # SVG → 2x PNG
├── NN-name.svg # generated, do not hand-edit
└── png/NN-name.png # generated
```
## Commands
Default (no command) = the full pipeline in order. Named commands run one stage.
| Command | Does |
|---|---|
| `draft` | Steps 1–2: find the argument, write the prose |
| `diagrams` | Steps 3–4: build and rasterize the visuals |
| `detox` | Step 5: strip machine patterns without flattening the voice |
| `translate` | Step 6: neutral-Spanish version |
| `check` | Step 7: run the verification script |
---
## Step 1: Find the argument in the code
A post about work should be able to point at the line that makes its claim true. Before writing
a sentence, read the project's instruction file (`CLAUDE.md` / `AGENTS.md`), its model or data
module, `.forge/brief.md` if the work went through `task`, and any `docs/*-review.md`. You are
looking for:
- **The one claim the work exists to make.** Usually a single sentence, often already written
down in an invariants section. If you cannot find it, ask the user rather than inventing one.
- **The numbers.** Whatever the post asserts numerically must come from a function you can
call, not from memory. A brief's `## Measured` section is the other legitimate source.
- **The concessions.** Anything the project already admits it gets wrong. These make the
strongest section of the post and they are already written; do not soften them.
If the work has an "open concerns" or "known gaps" doc, or a brief with an `## Open` section,
the post's honest-limitations section is mostly a rewrite of that. Reuse it.
## Step 2: Draft in the author's voice
Ask for a voice sample if you do not have one: an earlier post, a raw brain-dump, a long Slack
message. If the user supplies a raw draft, **that is the voice**, your job is structure and
compression, not replacement.
Match their register. If the sample says "let me cook" and "if the shoe fits", those survive
every later pass. Idiosyncratic hedges and slang are the *opposite* of an AI tell, and removing
them is the most common way this task goes wrong.
Structure that reliably works for a work write-up:
1. Why you're bothering (short, in voice)
2. The frame or metaphor
3. The core claim, with its diagram
4. The counter-argument someone will actually raise, answered
5. Where it breaks: the concessions from step 1
6. Link + credits
## Step 3: Generate diagrams from the model
**Import the model. Do not restate it.** A diagram with hardcoded numbers is a second source of
truth that will silently go stale the first time the model changes.
```js
// post/build-visuals.mjs
import { TYPES, efficiency, withAI } from '../js/data.js';
```
Then compute every number in the diagram by calling those functions. If a value cannot be
imported: a caption, a short label, keep it in one clearly-named map at the top of the file so
there is a single place to check when something changes.
`scripts/diagram-kit.mjs` bundles the reusable parts: a dark-canvas frame, heading and footnote
helpers, palette constants, a labelled bar with an optional ceiling tick, polygon vertices, a
legend row, and the write loop. Copy both scripts into `post/` and import from the kit, so a new
generator is the content and not 200 lines of SVG scaffolding:
```bash
cp "$FORGE/skills/writeup/scripts/diagram-kit.mjs" <project>/post/
cp "$FORGE/skills/writeup/scripts/rasterize.mjs" <project>/post/
```
The kit's palette is Neorgon's. **Outside that monorepo, change the palette constants first**,
see `reference/neorgon.md` for what they are and why.
Design rules that hold across diagrams:
- **One claim per diagram.** If it needs two captions to explain, it is two diagrams.
- **Draw the wall, not just the bar.** When the argument is about a limit, render the limit as a
tick the fill stops at. A reader gets that in one glance and no caption.
- **Label in the reader's vocabulary.** Domain names go in the heading; the nodes get the words
the audience already uses.
## Step 4: Rasterize
Medium, LinkedIn and most newsletters reject SVG. `rasterize.mjs` renders every `.svg` in `post/`
at 2x and flattens it onto the canvas background, because these platforms composite on white and
a transparent dark diagram picks up light halos around its edges.
```bash
node post/build-visuals.mjs && node post/rasterize.mjs
```
It resolves `sharp` from the current working directory; if that fails, set
`SHARP_FROM=/path/to/dir/with/node_modules/`.
**The `-bare` convention:** a file named `*-bare.svg` keeps its alpha channel instead of being
flattened. Use it for a diagram the user wants to composite into another image. Two things to
get right in a bare variant, both learned the hard way:
- Keep node and disc fills opaque. Without them, connecting lines run straight through the nodes
once a new background shows.
- Push side labels further out than the on-canvas version needs. Glows that look fine against a
dark background bleed over text once the backdrop changes.
Verify a bare export actually has transparency and is not clipped:
```bash
node -e "const s=require('sharp');s('post/png/X-bare.png').trim({threshold:1}).toBuffer({resolveWithObject:true}).then(({info})=>console.log('content',info.width+'x'+info.height))"
```
Content smaller than the canvas means nothing is touching the edges.
## Step 5: Detox, without flattening the voice
If the **`ai-writing-detox`** or **`humanizer`** skill is installed, run it for the banned-word
and banned-structure lists rather than restating them here.
What those do not cover, and what matters most: **the author's voice is not an AI pattern.**
Apply the detox to machine tells: throat-clearing, empty hedges, "not just X but Y", triads of
near-synonyms, title-case headings, em-dash pileups. Leave alone:
- Slang and memes the author actually uses
- First-person asides and self-deprecation
- Deliberate sentence fragments
- One or two "honestly" / "I know it's a bit-" hedges that read as a person thinking
If you cannot tell whether a phrase is voice or slop, ask. Guessing wrong in the direction of
"remove it" produces prose that passes every checker and sounds like nobody.
`scripts/check-writeup.sh` greps for the mechanical patterns so you spend your attention on the
judgment calls.
**Exit contract: 0 clean, 1 findings, 2 usage.** It counted findings and exited 0 regardless until 2026-08-29, so it was safe to chain behind `&&` in a publishing path, which was the opposite of the truth. Treat a non-zero exit as a stop.
## Step 6: Translate (neutral Spanish)
Only when asked. Neutral means it reads naturally to a reader in Mexico, Colombia, Argentina and
Chile alike. The full rules, the regionalism blacklist that has actually caught mistakes, the
loanwords to keep, and the voice-mapping table are in **`reference/spanish.md`**, read it before
translating.
The two rules worth carrying without opening it: `tú` throughout, never `vos` or `vosotros`; and
translate the *voice*, not the words: a literal translation of informal English reads stiff in
Spanish, which is the failure mode to watch for.
## Step 7: Verify
```bash
bash "$FORGE/skills/writeup/scripts/check-writeup.sh" <project>/post
```
Reports word count and read time, flags detox hits, flags Spanish regionalisms, confirms every
image reference resolves to a file that exists, and warns when the generator is newer than every
SVG it produces. A broken image path is the most common defect and the cheapest to catch.
## When asked to make it shorter
Cut structure, not substance. In order: throat-clearing paragraphs, sentences that restate the
previous sentence, and adjacent short paragraphs that merge cleanly.
If the post cannot reach the target without dropping a section the user asked for, **say so and
name the section you would cut**, rather than quietly shipping something 10% shorter and calling
it done. Word count is easy to measure and easy to be honest about.
## Invariants
- **Diagram generators import the model.** A hardcoded number in a generator is a bug waiting
for the next model change.
- **Generated files are generated.** Never hand-edit an `.svg` or `.png` in `post/`; edit the
generator and rebuild, or the next build silently reverts you.
- **Voice survives every pass.** Detox removes machine patterns, not personality.
- **Claims trace to code.** If the post asserts a number, you should be able to produce the
function call that returns it.
Files in this package (7)
- SKILL.md 10 KB
- agents/openai.yaml 1 KB
- reference/neorgon.md 2 KB
- reference/spanish.md 4 KB
- scripts/check-writeup.sh 4 KB
- scripts/diagram-kit.mjs 6 KB
- scripts/rasterize.mjs 2 KB
Versions
The database has no other skills named writeup.
Database snapshot: 13.11.2026 · package version fc36d81a34a3 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 90write-post
Guided 7-phase blog post writing. Use when writing a long-form blog post from scratch or from a pipeline-generated outline. Triggers: write post, blog post, write article. - 100turn-this-feature-into-a-blog-post
Generates a technical blog post from code implementation. Use when asked to write a blog post about a feature, explain an implementation for a blog, document code as a blog article, or create technical content from source code. Triggers on phrases like "write a blog post about",… - 100write-blog-post
Writes, critically reviews, illustrates, and ships a post for the LoreKit blog (packages/web/src/content/blog) end to end: researches the topic, checks every LoreKit claim against the code and every outside claim against sources, drafts in the house voice, runs a skeptic's… - 100video-to-articles
Convert a recorded video (talking-head, build-along, tutorial, demo, essay, vlog) into a ready-to-post article or post for X (Twitter), Medium, or LinkedIn: a copy-paste pack (markdown + paste-ready HTML twin) plus a fresh cover image, in the creator's own voice. Use whenever… - 100blog-post-writer
Writes engaging technical blog posts with a strong hook, clear structure, concrete examples, and a memorable takeaway. Use this skill when the user asks to "write a blog post", "draft an article", "turn this into a blog post", "write up a tutorial", "explain X in a post",… - 100write-blog
Generate a full SEO-optimized blog post. Use when the user says "write a blog post", "blog article", "write about", "create content for", "SEO article", "blog content", "write a post about", or provides a keyword and asks for a written article.