القائمة
Writes non-release DorkOS blog posts - feature posts, decision essays, ecosystem posts, and release recaps - from the repo's own ADRs, specs, research reports, and changelog fragments. Use when drafting, researching, or reviewing anything in blog/ that is not a version release note.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
Keeps skill definitions aligned between Claude Code and Codex. Use when creating, migrating, renaming, or updating skills that must work across `.claude/skills` and `.agents/skills`, or when auditing drift between the two systems.
When to open a pull request in the DorkOS repo (review the pushed branch first, open the PR after it converges) and how the automated review behaves, including its controls (skip-review, review:light/deep, re-review). Use when finishing a branch, opening a PR, deciding how much review a PR should get, or requesting a re-review after addressing feedback.
Decides when agent work needs an isolated git worktree and how to create, enter, and clean one up safely. Use when starting code changes in a checkout that may be shared with another agent, dispatching a Linear task, executing a spec, or running any parallel work that mutates tracked files.
Guides writing concise, effective Architecture Decision Records. Use when creating ADRs, extracting decisions from specs, or reviewing ADR quality.
Patterns for adding, renaming, removing, or retyping fields in DorkOS user config. Use when editing UserConfigSchema, MarketplacesFileSchema, or any conf-backed store — walks the Zod field → defaults → conf migration → docs → test lifecycle end-to-end.
Writes human-friendly changelog entries and release notes. Use when populating changelog, preparing releases, or reviewing release notes quality.
| name | writing-blog-posts |
| description | Writes non-release DorkOS blog posts - feature posts, decision essays, ecosystem posts, and release recaps - from the repo's own ADRs, specs, research reports, and changelog fragments. Use when drafting, researching, or reviewing anything in blog/ that is not a version release note. |
The blog at blog/*.mdx holds 61 posts and every one of them is a release note. The tutorial, announcement, and news categories are declared in the schema, styled with their own colors, and have never been used. Whatever you are about to write is the first of its kind, not the sixty-second of an existing kind.
A blog post is exactly where an unverified claim slips out. AGENTS.md:7:
"In user-facing copy, docs, and release notes, never state that a still-unverified surface or pillar ... works (the demo-claim gate:
meta/positioning-202607/09-gtm-plan.md§2.0)."
Under the gate right now, per that same line:
| Surface | Status |
|---|---|
| Obsidian plugin | Built but under-tested |
| Windows x64 desktop | Early alpha, never confirmed by a real end-user install |
| Mesh+Relay multi-agent coordination | Shipped, unverified end to end |
| Marketplace Claude-Code-superset compatibility | Shipped, unverified end to end |
| Linux desktop | Does not exist. Not gated, absent |
Room slash commands, post_to_room everywhere | Designed, not built (specs/rooms/02-specification.md:628-706) |
Clear of the gate: the web cockpit via CLI install, and the macOS desktop app (signed, notarized, downloadable).
AGENTS.md is the live list. 09-gtm-plan.md §2.0 is the rule behind it and is older, so where the two disagree, AGENTS.md wins.
The instruction, and it is not optional. Go through the finished draft one capability claim at a time. For each one, name the artifact that proves it shipped and was verified: a merged PR, a changelog fragment, a browser test, a docs page describing it as it works today. If you cannot find one, rewrite the sentence in the future tense or cut it. "DorkOS agents coordinate across machines" and "we are building toward agents that coordinate across machines" are different claims, and only one of them is currently true.
The same rule applies to your own numbers. Every threshold in the rooms design is self-declared unsourced (meta/agent-etiquette.md:219, "Every number in this space is unsourced."). Publishing one as a researched finding is the same failure in a smaller package.
Release posts. /system:release Phase 6.7 (.claude/commands/system/release.md:395-428) scaffolds blog/dorkos-X-Y-Z.mdx, and the release commit stages it. Entry quality inside it comes from writing-changelogs. If a release post needs to be better, edit that phase's template. Do not build a second authority over a file another command writes, because the two will drift the way the hand-written ## Install / Update section already has.
The writing-for-humans skill sets the sentence-level standard for everything here: the readability contract, the punctuation rule, the failure modes, the honesty gate. Read it first. Everything below is what is specific to a blog post.
A post argues from a position. A neutral explainer is a docs page, and we already have docs.
The position comes from three places:
meta/dorkos-litepaper.md:298: "Intelligence doesn't scale. Coordination does." Most posts here are an instance of it. The manifesto line is licensed on this surface and almost nowhere else (see Voice below), which makes an essay the one place the argument can be stated outright rather than implied.AGENTS.md:15 names Jobs, Ive and Rams as the design mentors and states what they imply: every element justifies its existence, so if a paragraph would not be missed, cut it. The product "feels like a control panel, not a consumer app," and meta/brand-foundation.md:425 says the same. The prose is instrument-panel prose, not lifestyle copy.| Post type | Usually for |
|---|---|
| Feature post | Kai (meta/personas/the-autonomous-builder.md), running many agents, asking whether this does something his current setup cannot |
| Decision essay | Priya (the-knowledge-architect.md), who reads the source before adopting and is really evaluating our judgment |
| Ecosystem post | Kai plus the other project's users, who arrived because of that project and not because of us |
| Release recap | People already running DorkOS, who want to know what changed and whether it was worth the upgrade |
A feature that removes the need to write code is Ikechi's (the-ai-native-founder.md), not Kai's. Pick one and write to them.
The test: if the post could have been written by a competitor about their own product, it has no point of view. Rewrite it or do not publish it.
| Type | Argues | Typical length |
|---|---|---|
| Feature post | Here is one capability and why it is built this way | 800 to 2,500 words |
| Decision essay | We chose X over Y, or we did not use Z | 1,500 to 3,000 words |
| Ecosystem post | Someone else's project matters, and here is what we did about it | 300 to 800 words |
| Release recap | Several releases add up to one thing | Whatever the arc needs |
Do not default to long. Fly.io is the company most associated with the long dense technical post, and their own retrospective (fly.io/blog/a-blog-if-kept) walks it back toward shorter and more frequent. Length follows the argument. A decision essay is the one type where length genuinely buys credibility, because its whole claim to authority is showing the work.
One capability, why it exists, why it is built the way it is.
Research method:
changelog/unreleased/, or the compiled section in CHANGELOG.md). These are already written to the readability bar, and the covers: frontmatter maps each bullet back to its commits when you need depth.decisions/manifest.json on specSlug for the spec that drove the work.git log --oneline <tag>..HEAD gives the order things actually shipped in, which is usually the order the post should explain them in.docs/ before writing an explainer. If a concepts page already covers it, link the page and spend your words on the argument instead.Shape: a concrete moment, what was broken, what was tried and rejected, what shipped, what it costs. Not a spec sheet.
A verbatim operator complaint beats any invented hook. The real one, at specs/rooms/02-specification.md:570:
"I can't figure out how to add agents to channels… The fact that I can't figure it out means the UI/UX could be better."
Nothing you invent will be that good, and you do not have to invent it.
Why we chose X over Y, or why we did not use Z.
Research method:
writing-adrs). They give you the frame and none of the narrative.## Alternatives Considered sections, the two ADRs that survive as documents with status: rejected, and struck-through Open Questions in specs, which keep the rejected option inline with its reasoning rather than deleting it.decisions/0070-per-agent-tool-filtering-via-allowedtools.md:21-23 states the principle: "an ADR is a record of what was believed, not a page to be quietly corrected." Those passages are the most trustworthy prose in the repo. Use them.research/ first, then re-verified. See Sourcing below.Shape: context, what was tried, why it did not fit, what was chosen, what it costs. Concede a real negative in your own choice. PlanetScale's Vitess post names its own dependency's "operational complexity," "shortage of Vitess experts," and "steep learning curve" and reads more credible for it, not less.
Someone else's project, covered by a party that is not neutral.
Research method:
research/ first. AGENTS.md makes this a standing rule for research generally and it applies here with force: roughly 60 of the 335 reports are publishable landscape or competitor analysis. The teardown you are about to commission probably exists.status: active on a research report is a default, not a freshness guarantee. Star counts, pricing, and feature claims go stale fastest.Keep it short and low-ceremony. This is the type to publish often.
Several releases as one narrative. Distinct from a release post, which belongs to /system:release.
Research method:
CHANGELOG.md including each version's theme blockquote, git log between tags, and apps/site/public/product/archive/ for frozen media./product/archive/vX.Y.Z/...), never the live /product/ path, which repoints on the next capture and would silently change what an old release shows.Titles. What travels with a technical audience is plain, declarative, first person, and carries either a specific number or a direct answer to a question the reader already holds. The patterns, taken from posts that actually traveled:
| Pattern | Example |
|---|---|
| Answer the question they already have | Ably, "No, we don't use Kubernetes" |
| A movement plus a number | Segment, "Goodbye Microservices: From 100s of problem children to 1 superstar" |
| Plain first person, zero adjectives | 37signals, "Why We're Leaving the Cloud" |
| The procedural frame | Anthropic, "How we built our multi-agent research system" |
Failure modes: adjectives and superlatives ("powerful", "revolutionary", "the future of"), a question posed as bait rather than one the post answers in its first line, and a bare proper noun. Fly.io can title a post "Corrosion" and be read on the strength of the byline. We cannot, because nobody knows us yet.
And the mechanical trap from Mechanics below: any x.y.z in the title turns the post into a release card.
Hooks. The opening has one job, which is to earn the second paragraph. The strongest opening available to us is a verbatim quote from a real person, and the operator complaint at specs/rooms/02-specification.md:570 quoted above is the proof. It is better than anything you would invent, and you do not have to invent it. The technique generalizes:
Openings to avoid: throat-clearing history ("Since the dawn of..."), defining a term the reader already knows, and announcing what the post will cover instead of starting it. Open on a concrete moment or a number. The one exemplar in the research that opens on a category definition is also the one whose central claim its own audience contested hardest.
Every external claim needs a primary source you actually fetched. Not an aggregator summarizing one, not a search snippet, not memory. Then:
research/ is not publication grade as written. Reports flag single-sourced claims, and that is adequate for an internal decision. It is not adequate for something with our name on it. Re-verify before a claim leaves the building.The repo has no anti-disparagement rule. What it has is surface-scoped: brand surfaces (homepage, hero assets) never mention competitors (meta/brand-foundation.md:386), and comparison content is planned elsewhere and required to be "honest about their strengths" (meta/positioning-202607/06-marketing-tactics.md:31). A blog post sits between the two, so this skill settles it:
Name them, name a specific strength and where it comes from, then narrow the rejection to our own context.
Ably's "No, we don't use Kubernetes" credits Kubernetes's Borg lineage, its vendor ecosystem, and specific "commendable design choices" in EKS networking before narrowing the rejection to their own workload. The move that keeps it from reading as a hit piece is the scoping: good in general, wrong for us specifically. A general claim that the other thing is bad invites the fact-check you will lose.
Two limits:
meta/brand-foundation.md:112: "The villain isn't a company or a competitor. The villain is a missing layer." That is the framing to reach for instead of an opponent.Publish design reasoning, including rejected alternatives and corrections made during design. This is the strongest material we have and it is unusually plentiful: ADRs with errata admitting their own overclaims, specs that correct an earlier draft in the shipped document, decisions reversed with the original argument left standing.
Do not publish operational failures or incidents. The research is clear that admitting failure builds credibility, and equally clear that every exemplar was a company with an existing reputation to spend. GitLab live-streamed a database outage recovery and came out ahead. GitLab had years of standing first. DorkOS is a pre-launch alpha with roughly zero outside users, and there is no documented precedent for a product in that position spending credibility it has not yet earned. When we have a track record, revisit this. Until then the line is design reasoning yes, incidents no.
meta/brand-foundation.md:434 reserves the manifesto line for "essays, the litepaper, comparison/anti-positioning surfaces, and the Show HN comment thread." A blog essay is that surface, and the only writing surface here where the line belongs.DorkOS Team, which is right for a release note and wrong for an opinion piece. A corporate byline on an argument reads as content marketing. The evidence is a consistent pattern across every strong exemplar in the research rather than a controlled finding, and it is worth following anyway: no one signs an essay "the team."Forced humor is worse than none, and worse than dryness.
Fits this brand: dry understatement, precise observation of something genuinely absurd, self-deprecation about our own mistakes. Does not: puns, exclamation marks, memes, quirky-startup voice, jokes at a competitor's expense, and anything you would have to explain to a reader in another timezone or language.
Apply the lens to ourselves first. decisions/0070-per-agent-tool-filtering-via-allowedtools.md:45 on a security option we misread and shipped wrong for three months: "The option was misread on day one. Nothing drifted underneath us." That is dry, self-deprecating, funny, and true, and no part of it is phrasing. It is the shape to aim for.
Then outward, carefully. The Buzz reply storm in the worked example below contains no joke either. Every agent was politely announcing that it would stop replying, and the announcing is what kept the conversation alive. It is funny because it is precisely described and true. But it is somebody else's production failure, so the frame is analysis, not mockery: it belongs in a post because it teaches something true about multi-agent systems, and anyone reusing it owes Block the same honesty about what they got right that the competitor rule above demands. Precision about a failure is the technique. A named competitor is not the punchline.
So: the humor comes from accuracy, not decoration. If a line is funny because of how it is phrased rather than what it observes, cut it. If the funny version of a sentence is less true than the plain version, it is not funny, and the sentence loses. One test before you keep a joke: would this still read well in six months, to someone who does not know us?
Frontmatter is validated by a Zod schema at apps/site/source.config.ts:14-28. Unknown keys pass silently and do nothing; a missing required field or a category outside the enum fails the site build.
| Field | Required | Notes |
|---|---|---|
title | yes | Also the version source. See the semver trap below |
date | yes | YYYY-MM-DD. Rendered as UTC everywhere |
description | no | Set it. See below |
author | no | A name. Absent, the JSON-LD author switches from Person to Organization (page.tsx:152-159; publisher is always Organization) |
category | no | release | tutorial | announcement | news. Never release for these posts |
tags | no | string[]. Feeds the OG tags and renders as pills |
image | no | Declared in the schema and read by nothing. Use inline markdown images instead |
Five things that will otherwise bite you:
description is the entire body of the RSS item. apps/site/src/app/blog/feed.xml/route.ts emits title, link, date, and description, and no post body at all. It is also the OG description, the Twitter description, the JSON-LD description, and the subtitle on the page. It is the highest-leverage field in the file and it is not a subtitle. Write the sentence that has to work alone in a feed reader.releaseVersion() pulls any x.y.z out of the title (apps/site/src/lib/blog-order.ts:12-18), and the OG image treats a parsed version as proof this is a release. An essay titled "What we learned shipping 0.56.0" renders as a giant version number on a release card. Keep bare semver out of non-release titles.page.data.toc.length > 2 (page.tsx:307) and is hidden below the xl breakpoint. Two headings gets you nothing.ReleaseInstallFooter is category-gated (page.tsx:258) and stays silent for anything that is not category: release. Nothing breaks. Do not hand-write an install section to compensate.The mechanism, because the obvious one is a trap. The image frontmatter field is declared in the schema and read by nothing (DOR-650), so setting it does nothing at all. Images go in the body, two ways:
, pointing at a frozen release archive.<ProductShot id="…" alt="…" />. The blog template renders MDX with getMDXComponents() (page.tsx:253), the same set the docs get, so this component works in a blog post and plays a loop where the shot has one. Two catches: it throws on an unregistered id, and the guard test only scans docs/ (shots.test.ts, DOCS_ROOT), so nothing catches a bad id in blog/ before the build breaks. Check the id against apps/e2e/capture/shots.ts yourself.Never hand-place a file in apps/site/public/product/. That directory belongs to the capture pipeline, and resetOutputDir() (apps/e2e/capture/optimize.ts:493-501) deletes every .png and .webm at its top level before each capture:process run. Your image disappears at the next capture and nobody will connect the two events. Product media is capturing-product-media's job end to end: registry, capture, human overrides, frozen archives. A post that needs a shot of the product asks that pipeline for one. A post that needs its own non-product image puts it under apps/site/public/blog/<post-slug>/, which nothing else writes to.
What to reach for, in this order.
capturing-product-media already captures from real UI on seeded data, and its loops are two-pass encoded to roughly 1.35MB against a 1.5MB budget.Three rules that matter more than the order above.
capturing-product-media enforces on the pipeline, and it does not relax because you are writing prose instead of running a capture.changelog/unreleased/260726-004945-composer-shows-its-own-shortcut.md:17). Describe what is in the image and why it is in the post, not "screenshot".Size. A 12MB loop is a worse experience than no loop. Hold anything you produce by hand to the pipeline's 1.5MB budget. Prefer a webm through the capture pipeline over a hand-made GIF, which is far larger for the same seconds. Markdown ![]() cannot play a webm, so a loop in a post means <ProductShot>.
Everything this post needs already exists on disk.
| Need | Where |
|---|---|
| Opening | specs/rooms/02-specification.md:570, the operator complaint quoted above |
| Conceptual payoff | specs/rooms/02-specification.md:606: "a session is about a directory, a DM is about who you are talking to, and a channel is about what you are talking about" |
| Shipped spine | 18 changelog fragments in changelog/unreleased/ dated 07-26 to 07-28, already at the readability bar |
| The "why" | Six ADRs, 260726-170125 through 260728-022013: the room primitive, opaque author identity, the cascade guard, the naming of "channel", the community server, threads as relations |
| PR order | git log --oneline for #502 through #536, which runs primitive, sidebar, replies, composer, avatars, multi-agent DMs, menus, docs |
| Closing argument | meta/agent-etiquette.md, the published standard |
The strongest narrative asset in the repo is research/20260727_buzz-conversational-behavior.md:284-301, a first-hand postmortem of a production agent-to-agent reply storm in someone else's product, 21 replies deep. The finding at :294:
"The content was the tell: every agent was trying to end the conversation, and announcing it is what kept it alive."
The root cause at :296-301 is two individually correct prompt rules composing into perpetual motion: always reply, and tag whoever tagged you. On a mutual mention the circuit closes and never opens. That is the whole argument for building the cascade guard as a mechanism rather than a sentence in a prompt, made by someone else's failure rather than our assertion.
Three constraints on this specific post, and they generalize:
docs/concepts/rooms.mdx already exists. Link it, do not restate it.post_to_room across every runtime is an open question. Both are gate territory.Under the competitor rule above, naming Buzz in an analytical essay is fine, and it obliges you to be honest about what they got right and to not put their failure in a pull quote.
apps/site/public/product/ unless the capture pipeline put it there.description works alone in a feed reader.author is a person.writing-for-humans have been run on the finished prose.