ai-devblog
Turn coding, debugging, research, architecture, migration, deployment, or product work into a clear, evidence-backed technical post in an existing publishing system. Use when Codex should reconstruct primary evidence, decide whether the material deserves a note or article, align on the intended reader, choose among field-report, explainer, reversal, origin-story, hands-on, or evidence-led argument forms, write and edit the piece, inspect its rendered presentation, and publish it at the requested visibility. Pair with blog-system-design for changes to the shared blog system.
swyxio · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add swyxio/skills --skill ai-devblog技能说明
name: ai-devblog description: Turn coding, debugging, research, architecture, migration, deployment, or product work into a clear, evidence-backed technical post in an existing publishing system. Use when Codex should reconstruct primary evidence, decide whether the material deserves a note or article, align on the intended reader, choose among field-report, explainer, reversal, origin-story, hands-on, or evidence-led argument forms, write and edit the piece, inspect its rendered presentation, and publish it at the requested visibility. Pair with blog-system-design for changes to the shared blog system.
AI Devblog
Write a technical story that changes what a particular reader understands, believes, or can do. Keep the empirical honesty of a good engineering report, but make comprehension and human interest the organizing priorities.
Use this order of attention:
route the genre → align with the reader → choose the angle → explain → support with evidence → edit → cold-read → present → publish
For substantial work, read the human-writing review and the story modes before proposing an angle. Use these writers as structural inspiration, not as personas to imitate.
Use blog-system-design with this skill when the task changes the shared blog
index, taxonomy, article shell, typography, navigation, search, responsive
behavior, or reusable components. A post must not silently redesign its
publication.
Route the material
First decide whether a devblog is the right container:
- Put a routine shipped fact in a changelog or release note.
- Put durable project onboarding, commands, API guidance, and contributor
instructions in a README; use
ai-readmewhen available. - Put an exhaustive roadmap, product plan, design specification, API reference, or component inventory in documentation.
- Continue here for reconstructed technical work, a tested argument, a consequential origin story, or a mechanism worth teaching.
Apply an interestingness gate. A shipped capability alone is not enough. The material needs at least one reader payoff: a non-obvious finding, consequential decision, useful technique, measurable result, corrected belief, surprising failure, illuminating mechanism, or reusable model. Recommend a smaller form when the work does not earn a post.
Choose one primary story mode:
- Field report: a change, incident, migration, or measured result.
- Short lab note: one useful experiment, release, artifact, or strange fact.
- Mechanism explainer: a system made understandable through one example.
- Incident or reversal: a reasonable belief that reality disproved.
- Evidence-led argument: several concrete cases that revise a common belief.
- Hands-on argument: a stance earned through a small reproducible exercise.
- Origin story: turning points that explain why a system has its current shape.
- Product announcement: what changed, why it helps, the hidden hard part, and the exact constraint.
A post may borrow a secondary move, but do not turn every available fact into an omnibus article. See story modes for structures, title families, and Dan Luu/Fly.io-inspired angle prompts.
Choose a weight that fits the idea:
- Note: about 300–800 words; one narrow finding and little ceremony.
- Standard: about 800–2,000 words; the default for a developed story.
- Feature: over 2,000 words only for a stated editorial reason; consider splitting work that grows beyond roughly 4,000 words.
These are editing signals, not quotas. Never inflate a useful note or compress a mechanism until it no longer makes sense.
Align with the reader
Before a standard or feature post, determine what the skill user expects the
reader to be, know, and want. If this is not already explicit, ask
one compact batch in the align-me shape:
- State each belief as a numbered decision.
- Give lettered, mutually exclusive choices with concrete consequences.
- Recommend one choice for each decision.
- End with
Reply approve all to accept 1A, 2B, 3A, or give changes such as 2C.Then wait.
Use the reader-and-angle checkpoint for the exact questions. Default to a smart adjacent engineer who knows the domain but not the project and wants a useful mental model or decision. Do not ask what the user has already answered. For a short note with an obvious readership, state the inferred assumptions briefly and proceed.
Then write privately:
- Before: what the reader probably believes or cannot yet do.
- After: what the evidence should make them believe, understand, or try.
- Spine: the one question the post answers.
- Not this post: two or three tempting facts that belong elsewhere.
For a standard or feature post, offer two or three genuinely different angles unless only one honest angle exists. Keep each option compact: title, promise, and tradeoff. Recommend one and wait. Never hide a single thesis behind cosmetic title variants.
Establish the evidence boundary
Reconstruct the work before writing:
- Inspect the relevant source, diff, issue, transcript, experiment, incident, or primary external research.
- Identify exact revisions, versions, data, configuration, dates, and environment when they affect the claim.
- Re-run or read the decisive tests and measurements when reasonably cheap.
- Separate source change, commit, push or merge, deployment or migration, and live user-facing verification.
- Preserve failed attempts, unfavorable results, reversals, and uncertainty when they explain the final conclusion.
- Identify evidence that challenges the preferred thesis, especially for an evidence-led argument.
Distinguish what this agent observed from repository history, another agent's work, human decisions, and inference. Attribute material ideas and firsthand observations. Do
阅读完整来源 ↗