agentleFS
leekleek/agent-skills/skills/blog-writing/SKILL.md

blog-writing

Skill5 starsChanged 6 days agoMITView on GitHub

Write, review, or improve a blog post against this repo's own blog style guide (voice, banned language, post types) and a shared set of craft rules. Use when drafting or reviewing a blog post, announcement, or engineering write-up, or when the user states a blog-writing preference to record as a style rule.

9 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

8 rules. 0 are common, 6 are distinctive, and 2 are very specific to this project.

  • 0

    Common

    Most of the 4 edited versions we read keep these.

  • 6

    Distinctive

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Read .agents/blog-style.md before you write or review.

    line 18
  2. Distinctive:

    If the file does not exist, this repo has not set the skill up.

    line 20
  3. Distinctive:

    Check the draft twice:

    line 37
  4. Distinctive:

    Technical pass: Check each claim against the code or its source: numbers, benchmarks, architecture descriptions.

    line 39
  5. Distinctive:

    Editorial pass: Check every craft rule and every style-guide rule.

    line 40
  6. Distinctive:

    When the user states a blog-writing preference, corrects a draft's voice, or bans a phrase:

    line 46
  7. Very specific:

    Look in .agents/blog-style.md for a rule that already covers it, and sharpen that rule rather than adding a near-duplicate.

    line 48
  8. Distinctive:

    Keep the author's voice through the whole post, with first-person asides in the middle ("this is the part that tripped me up") as well as …

    line 94

“Common” is measured: kept by at least 6 in 10 of the 4 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Blog Writing

Two layers of rules decide what a good post is:

  • The style guide holds this repo's own decisions: reader, voice, banned language, formatting, post types, closing, and non-negotiables. It lives in the target repo at .agents/blog-style.md, and the user owns it.
  • The craft rules below hold for any blog.

Where the two disagree, the style guide wins.

Load the style guide

Read .agents/blog-style.md before you write or review. A section the guide leaves out means only the craft rules apply there.

If the file does not exist, this repo has not set the skill up. Ask the user before any other work (a structured question (harness-tools), otherwise in chat):

  • Set it up now (recommended): bootstrap the guide per STYLE-GUIDE-FORMAT.md, then continue the task.
  • Skip this time: continue with the craft rules alone, and say in your report that the repo has no style guide yet.

Done when you can name the reader and the voice in one line each, or the user chose to skip.

Write

  1. Pick the post. Choose the post type from the style guide, and state in one sentence what the reader can do or decide after reading. If you cannot, the material is too thin for a post: tell the user what is missing and stop.
  2. Gather the facts. Collect the numbers, code, rejected alternatives, and limitations from the repo, the conversation, and the sources the user gave. A fact you cannot source is a question for the user: it goes in the draft as TODO(author): <what is needed>, never as an invented number, quote, or benchmark. Done when every claim the post will make has a source or a TODO.
  3. Draft. Apply every craft rule and every style-guide rule. Save the draft where the guide's posts: glob puts posts, with the frontmatter those posts use. With no posts: glob, save to .scratch/blog/<slug>.md.
  4. Review your own draft per Review and fix what it finds.
  5. Report the draft path, the title, each open TODO(author), and any code sample you did not run.

Review

Check the draft twice:

  • Technical pass. Check each claim against the code or its source: numbers, benchmarks, architecture descriptions. Run each code sample, or name it as not run. Flag a simplification an expert would call wrong.
  • Editorial pass. Check every craft rule and every style-guide rule.

Report one finding per weak passage: quote it, name the rule it breaks, and give the rewrite. A rule the draft meets stays silent. Done when every rule in both layers was checked against the whole draft, title and closing included.

Record a rule

When the user states a blog-writing preference, corrects a draft's voice, or bans a phrase:

  1. Look in .agents/blog-style.md for a rule that already covers it, and sharpen that rule rather than adding a near-duplicate.
  2. Otherwise add it under the section it fits, in the shape that section uses in STYLE-GUIDE-FORMAT.md. A preference that would hold for any blog still goes in this repo's guide: the craft rules change only in this skill's own repo.
  3. Show the user the added or changed text in your reply.

Craft rules

Opening

The first two or three sentences state the problem or state the conclusion. Background, company history, and announcements of what the post will cover come later or not at all.

  • Before: "We are always looking for ways to improve the experience. Today we want to share some updates to our import tool."
  • After: "Importing a 2 GB CSV used to take 40 minutes and fail one time in five. We rebuilt the importer around streaming, and the same file now loads in 3 minutes."

Structure follows the reader's questions

Order the post by what the reader is wondering:

  1. What problem does this solve? (one or two paragraphs)
  2. How does it work underneath? (most of the post)
  3. What were the trade-offs and the alternatives you rejected?
  4. How do I use it or try it?

A post about engineering work also answers: what did you try that failed, and what are the known limits?

Title

The title makes a specific claim, tells a story, or promises a specific payoff. "How we cut deploy time from 22 minutes to 4" does; "Deployment improvements" does not.

Headings carry information

A reader who reads only the headings learns the argument. "Why pre-aggregation loses the detail you debug with" does this; "Background", "Architecture", and "Conclusion" do not.

Paragraphs

One idea per paragraph. Start a new paragraph where the text turns ("but", "however", a change of subject), so the turn sits at the start of a block where a skimming reader sees it. A one-sentence paragraph is fine for emphasis.

Evidence

  • Numbers over adjectives. A performance claim carries its number: "p99 fell from 340 ms to 45 ms", in place of "significantly faster".
  • Code works. A sample includes its imports and configuration, and its comments say why, since the code already says what.
  • Diagram a system. More than two interacting components get a diagram, labelled with the real component names.
  • Honest claims. State limits and beta status. Describe what a feature does with the verb that is true: "suggests a likely cause" and "finds the cause" are different claims.
  • Decisions show the alternative. A decision is explained with what was not chosen and why.

Written by a person

Keep the author's voice through the whole post, with first-person asides in the middle ("this is the part that tripped me up") as well as at the start and end. Rewrite these machine-prose patterns as plain connected sentences:

PatternExample to rewriteRewrite
Dramatic fragments"No errors. No warnings. Everything green.""There were no errors or warnings, and everything looked fine."
Aphorism"You can't fix what you can't see.""Without the full request path, you are guessing."
Three-beat reveal"Not a config issue. Not a code bug. The deploy was stale.""It was not a config issue or a code bug. The deploy was stale."
Smug simplicityA code block, then "That's it. That's all you need."Say what the code does, or move on.
Ad-copy parallelism"Metrics tell you what broke. Traces tell you why.""Metrics show what broke, but you will find the reason in the traces."

Closing

End on something the reader can use: the docs, the source, a way to try it, or a request for feedback. Tie it to the problem the post opened with. A recap of the post or a line of hype is not a closing.

Worth sharing

A post earns publishing when it holds at least one of: a technical decision with its trade-offs, original data, a debugging story with specifics, an honest account of a failure, or a how-to that saves the reader real time. A post with none of these needs more depth, or belongs in the changelog. When unsure about length, go deeper: thin is the more common failure than long.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.