A skill that imposes quality standards on Japanese technical blog articles. The target is the entire article on personal blogs, Zenn, Qiita, and corporate tech blogs. It is used for article planning, structuring, new writing, whole-article review, large-scale rewriting, and consideration of titles and headings.
As a rule, it is not used for About pages, READMEs, AGENTS.md, skill definitions, social media posts, emails, short descriptions, front matter-only edits, tag organization, code comments, or minor polishing of just a single sentence or paragraph within an article.
If sentence-level improvement of Japanese is needed even for out-of-scope text, in an environment where it is available, writing-ja can be used.
This skill handles article planning, structure, titles, headings, introductions, conclusions, SEO decisions, article-level quality bars, and review.
writing-ja In environments where it exists, leave sentence-level polishing (facts, logic, concreteness, tone adjustment) to that. In environments where it does not exist, check sentence-level matters as well using this article-level standard. In either case, do not skip that stage.
Quality Standards
Aim for an article that a senior engineer would want to paste into their team's Slack. An article that has even a slight chance of making it onto Hatena Bookmark or Zenn trends. If it does not meet this standard, it lacks depth or unique insight.
Write the article that your past self, who was trying to solve that problem, would have wanted to read. When in doubt, go deeper. The risk of being too shallow is far greater than the risk of being too detailed.
Voice
Write in the voice of an engineer talking about something they genuinely found interesting at a conference reception. Technically accurate, opinionated, and candid.
Do not use the voice of a press release, sales deck, or AI-generated summary. Include humor only when it serves the content. One per article is enough.
Structures to avoid throughout the article
If you find them, rewrite. For candidates for sentence-level boilerplate expressions and vocabulary, in environments where it is available, leave it to the checks in writing-ja .
- Instead of a claim, place only the joy of announcing or abstract superiority
- The introduction ends with only a preview that does not serve as material for the reader's judgment
- Increase filler preambles with sentences unrelated to the reader's judgment
Opening (first 2–3 sentences)
Make the opening either "state the problem" or "state the conclusion." Do not start with background explanation, generalities, or hype. "In recent years, ~ has been attracting attention" is forbidden.
■Good examples
リリース2週間前に、作っていたメトリクス製品を丸ごと捨てた。
時系列の事前集計がデバッグでは役に立たない理由と、ゼロから作り直した話を書く。
■Bad examples
技術の変化を簡単に整理してから、本題を紹介します。
この製品に追加した機能をまとめます。
"What you can learn from this article"
Do not use preview text that has no content.
You may use a short "What you will learn in this article" that shows the specific scope covered in the article and the information readers will gain for making judgments. Use it when an article is long and covers multiple points, and the scope is hard to understand from the introduction alone.
Do not add it mechanically to short articles or articles whose scope is clear from the introduction alone. It must not be an abstract bullet list that merely rephrases the body text or headings.
Structure should follow the reader's questions
Before you start writing, decide who the article is for. Then, rather than following your own internal circumstances or chronology, organize it in the order of the questions readers actually have.
- What problem does this solve? (up to 1-2 paragraphs)
- How does it work? Not operating procedures, but the underlying technology (the main body of the article. Write concretely)
- Compared with what, and what was given up? (This is what separates a good article from an excellent one)
- How do you start using it? (a concrete next step)
In technical deep-dive articles, also cover the following.
- Things you tried that did not work (builds trust)
- Known limitations (shows intellectual honesty)
Allocate the depth of each section before you start writing. If you write every section with the same level of intensity, the article will be well made but will not carry anyone's sense of reality. Write more deeply about the main claim you most want to make and the places where you actually got stuck or failed, and finish in one sentence the topics that can be dealt with as premises. If every section looks equal at the outline stage, that is the point to fix.
Do not mix chronology with dramatization
In incident investigations and debugging records, chronology can be kept because the order of occurrence helps understand causality. However, making readers follow the writer's order of discovery is different from staging a "misconception -> anomaly -> reveal -> payoff."
In articles where readers want the result or reproduction steps, present the main result first and use the chronology as its supporting evidence. Keep foreshadowing, setup, reveals, and callbacks at the beginning only when they are necessary for readers to understand causality. If the article has multiple instances of staging with the same role, narrow them down to one.
Handling skimming
Readers scroll. Shorter paragraphs almost always keep them reading longer.
When a contrast or shift in viewpoint comes ("however," "that said," "yet"), split the paragraph immediately before it. Do not bury the turning point inside a paragraph.
■Bad example
従来の監視はリクエストとレイテンシを追う。ステートレスな HTTP サービスならそれで足りる。AIエージェントは違う。1回の実行に複数の LLM 呼び出し、ツール実行、ハンドオフが含まれる。
■Good example
従来の監視はリクエストとレイテンシを追う。
ステートレスな HTTP サービスならそれで足りる。
AIエージェントは違う。
1回の実行に複数の LLM 呼び出し、ツール実行、ハンドオフが含まれる。
Emphasizing a transition with a blank line departs from traditional paragraph rules, but it is a standard technique in online writing.
Put only one topic in one paragraph. Split paragraphs that contain two points. You may also use one-sentence paragraphs for emphasis. Use bullet lists when showing parallel items or comparisons is easier to read than body text. Do not increase them just to ensure completeness or equalize the number of items.
SEO for Japanese blogs
Apply this to articles that clearly aim to attract search traffic.
- Place the conclusion, decision-making material, and solutions that searchers need first in the first half.
- Only include a "what is ~" explanation when the definition of the term is part of the search intent.
- Limit generalities to the scope necessary for readers to understand the implementation or decision.
- Add an FAQ only when there are multiple related questions that cannot be naturally incorporated into the body.
- Do not mechanically add definition sections or FAQs solely for SEO purposes.
- For bug fixes, configuration procedures, migration records, and experience reports, prioritize concrete results and procedures.
- Do not add unnatural repetition or paraphrasing for the sake of search keywords.
Do not dilute actual results from trying things, methods that failed, compromises, dissatisfactions, reasons for choices, and how things went in your own environment with generalities.
Carry the writer's voice throughout the entire article
An AI draft starts with a personal introduction, becomes impersonal for 80% of the body, and closes with a CTA. Keep the writer's voice throughout. Scatter first-person interjections into the body, such as "This is where I got stuck" or "At first I suspected a different service."
The LLM habits that appear at the sentence level (three consecutive noun-ending phrases, sloganization, antithesis, a one-line closer immediately after a code block) are handled by writing-ja .
Headings carry information
- Weak headings: "Background," "Architecture," "Results," "Summary"
- Strong headings: "Why time-series pre-aggregation breaks the debugging context," "Solving distributed GROUP BY with scatter-gather," "This is where it falls apart: the cardinality wall"
Make it so the article's claims can be followed even by skimming only the headings.
Technical quality standards
- Numbers over adjectives. If you claim performance, include numbers. Not "error handling became significantly faster," but "p99 error handling time went from 340ms to 45ms. A 7.5x improvement."
- Only include code that works. Include imports, configuration, and prerequisites. Comments should explain why, not what
- If you explain a system involving three or more components, include a diagram. Mermaid is fine. Label it with actual service names, not generic boxes (for diagramming and alt text conventions, see
blog-opsのreferences/images.md) - Do not exaggerate. Do not write as if something can do what it cannot. If it is beta, say it is beta. It is fine to mention competitors' strengths. "AI suggests a root cause" and "AI identifies a root cause" are different things
Check whether it has become a generality
If the meaning of a paragraph does not change even after removing all proper nouns, numbers, and concrete examples, that paragraph is stuck at the level of generality. A paragraph whose content would be the same no matter who wrote it will not change in substance even if you fix the wording.
This is a matter of material, not of how it is written, so continuing to run a loop of revising the text will not solve it. Stop, gather again the proper nouns, numbers, primary sources, and things you actually did that support that paragraph, and then rewrite it. The writer is the one who has the material, so if it is not at hand, ask. Do not fill it in with plausible-sounding explanations. If you cannot gather it, either drop that point from the article or state that it is a general observation and keep it brief.
Title
The title is the single sentence with the highest leverage in the article. Judge it by whether it can stop the hand of a developer scrolling through RSS or a social media timeline.
A strong title either makes a concrete claim, foreshadows a story, or promises a concrete payoff.
- "The metrics product we built was working. Even so, we threw it away and rebuilt it."
- "How fixing Salt reduced release delays by 5%"
- "47% of your JavaScript bundle is dead code. I'll write about how to find it."
A weak title is a vague announcement.
- "Introducing our new metrics product"
- "Announcement of performance improvements"
- "Debugging with AI"
Conclusion
End with something useful. A link to documentation, source code, a way to try it, a channel for feedback. Either return to the story you started at the beginning and pay it off, or show the reader a concrete next action.
Do not end with generic hype ("Stay tuned for future developments"), a summary of what you just wrote, or a product-page-style CTA ("You can try it for free").
Article types
| Type | Goal |
|---|---|
| Technical deep dive | Explain a technical system or decision so other engineers can learn from it |
| Release announcement | Explain what shipped, why it matters, and how to use it |
| Postmortem | A transparent incident analysis including a timeline and fixes |
| Verification/comparison | Insights from original data or verification results |
| Tutorial | Help readers accomplish a specific task |
For any type, it must include the writer's own experience and judgment. A list of features can go in a changelog or release notes; a blog post should carry more than that.
Length guidelines
Use word count not as a goal but as a ruler for noticing deviations. Being outside the range is not itself a problem, but check whether you can explain why it is outside.
| Type | Guideline (Japanese, body character count) |
|---|---|
| Technical deep dive | 4,000〜10,000 |
| Verification/comparison | 3,000〜8,000 |
| Postmortem | 3,000〜6,000 |
| Tutorial | 2,000〜6,000 |
| Release announcement | 1,500〜3,000 |
If it falls far below the lower bound, it is often missing "what was compared to what and what was discarded" and "what did not go well." Add depth here. If it greatly exceeds the upper bound, either the explanation of the premises is long, or points that should be split into separate articles are coexisting. Reordering them according to the reader's questions makes it clear what is not the main topic.
The "Will it be shared?" test
Ask before publishing. Would a developer share this article with someone? Is there even a slight chance it will do well on Hatena Bookmark? If the answer is No, either add depth or unique insight, or send it to the changelog.
An article that gets shared contains at least one of the following.
- A technical decision explained together with its trade-offs
- Unique data or verification results that cannot be read elsewhere
- A real debugging story with concrete details
- An honest report of what did not go well
- Procedures that actually save the reader's time
When reviewing and editing a draft
references/review.md Start by reading . The reading order, the three checklists, how to respond to feedback, and the completion conditions for review are there.