agentleFS
peterbamuhigirepeterbamuhigire/business-plan-skills/skills/writing-content/content-writing/SKILL.md

content-writing

Skill4 starsChanged 19 days agoMITView on GitHub

Use when drafting or editing website copy of any kind. Use content-writing for general copy and blog-writer for a complete article.

5 other projects use a version of this, 1 of them edited.

Adopted by

Most recently taken up by

The file

Show its rules and text

We split this skill into the rules it gives an agent

31 rules. 0 are common, 31 are distinctive, and 0 are very specific to this project.

  • 0

    Common

    Most of the 3 edited versions we read keep these.

  • 31

    Distinctive

    This author's own choices. Worth a look.

  • 0

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Use this skill as the general copywriting and editing standard for websites and marketing content.

    line 16
  2. Distinctive:

    Use when drafting or editing website copy of any kind.

    line 20
  3. Distinctive:

    Use when the task needs stronger headlines, flow, readability, or persuasive structure.

    line 21
  4. Distinctive:

    Use as a cross-cutting writing standard alongside more specific content skills.

    line 22
  5. Distinctive:

    Do not use to invent missing strategy, positioning, or proof.

    line 26
  6. Distinctive:

    Do not override a more specific skill that already owns the artifact.

    line 27
  7. Distinctive:

    Do not confuse polished copy with message clarity or business logic.

    line 28
  8. Distinctive:

    Every word exists for the reader, not the writer.

    line 99
  9. Distinctive:

    Why: should they care? What benefit do they gain?

    line 102
  10. Distinctive:

    Write for the reader all the time.

    line 104
  11. Distinctive:

    Write the headline AFTER the content: Only then do you know the full scope and best angle.

    line 119
  12. Distinctive:

    ALL CAPS for entire headlines (harder to read)

    line 134
  13. Distinctive:

    No throat-clearing: Do not warm up, set the scene, or provide background before the point.

    line 145
  14. Distinctive:

    Lead with the most important information: Use the inverted pyramid who, what, where, when, why first.

    line 147
  15. Distinctive:

    Question lede: Ask what the reader is already wondering.

    line 155
  16. Distinctive:

    Write at a reading level your audience can easily absorb.

    line 168
  17. Distinctive:

    Short words: Prefer one- and two-syllable words.

    line 182
  18. Distinctive:

    Cut mercilessly: If a word adds nothing, delete it.

    line 185
  19. Distinctive:

    If readers must look up a word, you've interrupted the flow and may lose them entirely.

    line 189
  20. Distinctive:

    Every topic has essential words and phrases that naturally appear in expert-written content.

    line 208
  21. Distinctive:

    Use them naturally: Do not force keywords. Write as an expert would the vocabulary emerges from genuine knowledge.

    line 213
  22. Distinctive:

    Do not stuff keywords repeatedly (old SEO Google penalises this)

    line 219
  23. Distinctive:

    Do not create separate pages for minor keyword variations (one thorough page beats five thin ones)

    line 220
  24. Distinctive:

    Do not sacrifice readability for keyword inclusion

    line 221
  25. Distinctive:

    Every page must answer: Why should I read this instead of the hundred other pages on the same topic?

    line 247
  26. Distinctive:

    More thorough coverage: If competitors cover 5 points, cover 10 with more depth.

    line 254
  27. Distinctive:

    Never regurgitate information available elsewhere without adding a new angle, deeper analysis, or practical guidance.

    line 257
  28. Distinctive:

    Always translate features into reader benefits.

    line 263
  29. Distinctive:

    Never write more than 3 paragraphs without a subhead

    line 347
  30. Distinctive:

    Keep paragraphs to 4 lines maximum on screen

    line 350
  31. Distinctive:

    Before publishing any page or post, verify:

    line 378

“Common” is measured: kept by at least 6 in 10 of the 3 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
<!-- dual-compat-start -->

Content Writing Skill

Overview

Use this skill as the general copywriting and editing standard for websites and marketing content. It applies structure, clarity, persuasion, and scannability across page copy, blog text, and other website content.

Use When

  • Use when drafting or editing website copy of any kind.
  • Use when the task needs stronger headlines, flow, readability, or persuasive structure.
  • Use as a cross-cutting writing standard alongside more specific content skills.

Do Not Use When

  • Do not use to invent missing strategy, positioning, or proof.
  • Do not override a more specific skill that already owns the artifact.
  • Do not confuse polished copy with message clarity or business logic.
  • Route to content-writing instead for general copy, or blog-writer for a complete article.

Required Inputs

InputSource / providerRequired?If absent
Content Writing brief and decision audienceClient, plan owner, or approved project filesYesStop before making a recommendation; state the missing decision context.
Claims, assumptions, and supporting evidenceSource register, model, research notes, interviews, or operating recordsYesSeparate known facts from assumptions and return a qualified gap list.
Authority and delivery constraintsRequesting owner and repository instructionsYesRemain read-only and produce a draft or review only.
  • Draft copy or a clear content brief
  • Audience, page purpose, and conversion goal
  • Brand, language, and tone context
  • Any adjacent pages or content whose wording must stay aligned

Workflow

  1. Identify what the page or piece of content must achieve.
  2. Clarify the reader, promise, and next action.
  3. Draft or revise the copy for clarity, persuasion, and scanability.
  4. For premium service pages, sales pages, authority content, SEO/AI-search pages, or high-stakes conversion copy, apply premium-commercial-writing.
  5. Reconcile tone and terminology with the brand and surrounding content.
  6. Tighten weak sections, headlines, and transitions.
  7. Flag where better inputs or stronger evidence are needed.

Decision, stop, and recovery controls

  • Decision point: confirm that the requested output is the reader-ready content draft and that the decision concerns which structure and language help the reader complete the task.
  • Stop condition: halt the affected conclusion if required evidence is missing (page purpose, reader task, facts, voice, and conversion path) or if the work could lead to this identified risk: polishing generic copy that lacks proof or a usable next step.
  • Recovery: obtain the missing record or reviewer, repeat the affected check, and update the exception record before release.

Quality Bar

  • The copy is clear, useful, and conversion-aware.
  • Headlines and structure make the content easy to navigate.
  • Tone matches the intended audience and brand.
  • The writing supports the business goal of the page.

Anti-Patterns

  • Vague marketing language with no concrete meaning.
  • Long paragraphs that hide the main point.
  • Writing that sounds polished but says nothing new.
  • Copy choices that conflict with other live pages.
  • Treating a generic content writing template as a conclusion. Correction: tie each choice to the named audience, evidence, and operating constraint.
  • Applying the wrong neighbouring route to content writing. Correction: confirm the decision and route to the named neighbour before analysis.
  • Treating an assumption as verified evidence. Correction: label it, cite its source or owner, and assign a verification action.
  • Recommending action without a decision threshold. Correction: state the measurable acceptance condition and review trigger.
  • Recording an unavailable check as passed. Correction: mark it not assessed and state the consequence for the decision.
  • Mutating or publishing during an analysis-only task. Correction: remain read-only until the owner gives explicit authority.

Outputs

ArtefactConsumerObservable acceptance condition
Content Writing deliverableNamed decision-maker or plan authorThe recommended choice, assumptions, countercase, and next action are explicit.
Evidence and exception registerReviewer, funder, board, or implementation ownerEvery load-bearing claim is sourced or labelled as an assumption; missing checks are not shown as passes.
  • Improved or newly drafted website copy
  • Stronger headings, flow, and calls to action
  • Any messaging gaps that need strategic clarification

Professional copywriting standards for website copy, blog posts, articles, and all written content. This is a cross-cutting skill apply these principles whenever creating or editing text for any page.

The Reader-First Rule

Every word exists for the reader, not the writer. Before writing anything, answer:

  • Who is the reader? What do they already know?
  • What are they looking for? What problem brought them here?
  • Why should they care? What benefit do they gain?

Write for the reader all the time. That is what separates content that converts from content that gets ignored.


Headlines & Titles

The headline is the most important element. Five times as many people read the headline as read the body. If the headline fails, everything below it is wasted.

Headline Rules

  1. Promise a benefit. Headlines that promise benefits outperform those that don't.
  2. Give news. Readers seek new information new products, new methods, new insights.
  3. Select your reader. Flag down the people you want. If writing for banana farmers, put "banana farmers" in the headline.
  4. Be specific. "How to Increase Banana Yield by 40%" beats "Tips for Better Farming."
  5. Long headlines that say something outpull short headlines that say nothing. Never sacrifice clarity for brevity.
  6. Write the headline AFTER the content. Only then do you know the full scope and best angle.
  7. Telegraph in simple language. Readers do not stop to decipher obscure headlines.

Headline Formulas That Work

  • How to [achieve desired result]: "How to Store Bananas for Maximum Shelf Life"
  • [Number] Ways/Reasons/Steps: "7 Steps to Higher-Quality Matooke Flour"
  • Question that mirrors the reader's problem: "Is Your Banana Crop Vulnerable to Fusarium Wilt?"
  • News/announcement: "New Banana Cultivar Resists Black Sigatoka Disease"
  • Direct benefit: "Reduce Post-Harvest Losses by Half with These Storage Methods"

What to Avoid in Headlines

  • Clever wordplay the reader won't get
  • Headlines that could apply to any topic (too generic)
  • ALL CAPS for entire headlines (harder to read)
  • Clickbait that the content cannot deliver on

The Lede (Opening)

Your first 10 words are more important than the next 10,000. The lede must sell the reader on continuing.

Lede Rules

  1. No throat-clearing. Do not warm up, set the scene, or provide background before the point. Get to the substance in the first sentence.
  2. Maximum 11 words in the opening paragraph (Ogilvy's rule). Short opening paragraphs draw the eye in.
  3. Lead with the most important information. Use the inverted pyramid who, what, where, when, why first. Details follow in descending order of importance.
  4. Create a reason to keep reading. The lede either promises useful information, provokes curiosity, or states something surprising.

Lede Types

  • News lede: State the key fact. "BIRDC has released three new banana cultivars resistant to Fusarium TR4."
  • Problem lede: Name the reader's pain. "Post-harvest banana losses in East Africa exceed 40% most of it preventable."
  • Story lede: Brief, vivid scene (2-3 sentences max, then get to the point). "A farmer in Bushenyi watched half her harvest rot in three days. The cause was a storage mistake that costs Uganda millions annually."
  • Question lede: Ask what the reader is already wondering. "What makes East African highland bananas different from every other cultivar on the planet?"

Ledes to Avoid

  • Starting with "In today's world..." or "Since the dawn of time..."
  • Background history before the point
  • Definitions from the dictionary
  • Throat-clearing: "This article will explore..." or "It is important to note that..."

Readability

Write at a reading level your audience can easily absorb. For general web audiences, target grade 8 readability (Gunning Fog Index of 8).

The Fog Index Formula

Fog Index = 0.4 x (average words per sentence + percentage of words with 3+ syllables)

  • Target: 8 or below for general audiences
  • 10-12 for educated professional audiences
  • Above 12 means you are losing readers

Readability Rules

  1. Short sentences. Average 15-20 words per sentence. Mix lengths some 5-word sentences, some 25-word, but never above 30.
  2. Short paragraphs. 1-4 sentences. One idea per paragraph. A single-sentence paragraph is powerful.
  3. Short words. Prefer one- and two-syllable words. "Use" not "utilise." "Help" not "facilitate." "Start" not "commence."
  4. Active voice. "The farmer harvested the crop" not "The crop was harvested by the farmer."
  5. Concrete nouns and strong verbs. "Banana yields dropped 30%" not "There was a significant reduction in production output."
  6. Cut mercilessly. If a word adds nothing, delete it. "In order to" "to." "At this point in time" "now." "Due to the fact that" "because."

Words That Lose Readers

If readers must look up a word, you've interrupted the flow and may lose them entirely. Prefer the simple alternative:

Instead ofWrite
ameliorateimprove
commencestart, begin
endeavourtry
facilitatehelp, enable
implementdo, carry out
subsequentnext, later
utiliseuse
approximatelyabout
in the event thatif
with regard toabout

Niche Vocabulary (Thematic Depth)

Every topic has essential words and phrases that naturally appear in expert-written content. Google and readers both recognise this "niche vocabulary" it signals authority and depth.

How to Use Niche Vocabulary

  1. Identify the core terms for your topic. For banana research, these might include: cultivar, Musa, highland banana, matooke, tissue culture, Fusarium, Black Sigatoka, post-harvest, value chain, smallholder, East African highland.
  2. Use them naturally. Do not force keywords. Write as an expert would the vocabulary emerges from genuine knowledge.
  3. Cover the topic thoroughly. A page on "banana tissue culture" that never mentions propagation, plantlets, sterile media, or acclimatisation looks thin to both readers and search engines.
  4. Different subtopics need different vocabulary. A page on banana diseases uses different core terms than a page on banana food products.

What NOT to Do

  • Do not stuff keywords repeatedly (old SEO Google penalises this)
  • Do not create separate pages for minor keyword variations (one thorough page beats five thin ones)
  • Do not sacrifice readability for keyword inclusion

Scannable Formatting

Readers scan before they read. If scanning reveals nothing useful, they leave.

Formatting Rules

  1. Subheadings every 2-3 paragraphs. Subheads are the signposts readers should understand the page's content by reading only the subheads.
  2. Bullet points for lists of 3+ items. Bullets are faster to scan than embedded lists in prose.
  3. Bold key phrases within paragraphs the words a scanner's eye should catch.
  4. Pull quotes or callout boxes for critical statistics or insights.
  5. Images or visuals every 200-300 words to break up text and provide visual rest.
  6. Captions under images captions are read 2x more than body copy (Ogilvy).
  7. White space is content. Generous margins and padding help the eye focus.

Above the Fold

The content visible without scrolling must immediately answer: "Am I in the right place?" and "What's in it for me?" Place the strongest headline, the clearest value proposition, and (on landing pages) a CTA above the fold.


Unique Value Proposition

Every page must answer: Why should I read this instead of the hundred other pages on the same topic?

How to Create Unique Value

  1. Original data or research. Primary research that readers cannot find elsewhere.
  2. Expert perspective. Analysis, not just facts what does this mean for the reader?
  3. Practical application. Show how to apply the information, not just what it is.
  4. More thorough coverage. If competitors cover 5 points, cover 10 with more depth.
  5. Better formatting. A well-structured, scannable page beats a wall of text with the same information.

Never regurgitate information available elsewhere without adding a new angle, deeper analysis, or practical guidance. Content that merely restates existing material adds no value.


Features vs Benefits

Always translate features into reader benefits. Features describe what something is; benefits describe what it does for the reader.

FeatureBenefit
Disease-resistant cultivarYour crop survives when others fail
Tissue culture propagationUniform plants, faster establishment, guaranteed disease-free
18-month research programmeProven results before you invest
Laboratory-tested quality standardsConfidence that your product meets export requirements

Rule: For every feature you mention, immediately follow with the benefit using "so that," "which means," or "this gives you."


Structure Templates

Blog Post / Article Structure

Headline (benefit-driven, specific)

Lede (1-2 short paragraphs  hook + promise)

Context (why this matters now  1-2 paragraphs)

Main content (subheaded sections, each with:
  - Subhead (tells the story on its own)
  - 2-3 short paragraphs
  - Bullet points where applicable
  - Image/visual if relevant)

Takeaways (bulleted summary of key points)

CTA (what should the reader do next?)

Service/Product Page Structure

Headline (what it does for the reader)

Problem statement (the pain the reader has)

Solution overview (how this solves it  2-3 sentences)

Key benefits (3-5, bulleted, benefit language)

How it works (simple steps or process)

Evidence (data, testimonials, credentials)

CTA (clear next action)

About Page Structure

Mission statement (what you do and why it matters)

Story (brief origin  problem you saw, what you did)

What makes you different (credentials, approach, values)

Team / People (humanise the organisation)

CTA (connect, partner, learn more)

Keeping Eyes Moving

Even strong prose needs visual help to keep readers engaged through the full page.

Visual Touchpoints

  • Subheads the primary eye-catcher when attention drifts
  • Bold text highlights key phrases within paragraphs
  • Bulleted/numbered lists faster to scan than prose
  • Images with captions captions read 2x more than body copy
  • Pull quotes featured text that draws the eye
  • Short paragraphs white space between paragraphs creates entry points

Paragraph Discipline

  • Never write more than 3 paragraphs without a subhead
  • Vary paragraph length (1 sentence, then 3 sentences, then 2)
  • A one-sentence paragraph is powerful emphasis use it for key points
  • Keep paragraphs to 4 lines maximum on screen

Writing Styles

Choose the appropriate voice for each piece:

  1. Journalistic/factual impartial, evidence-based, authoritative. Best for: research summaries, industry reports, technical content.
  2. Storytelling/personal real experience, named people, specific details. Best for: case studies, farmer success stories, about pages.
  3. Combined facts presented through a narrative lens with expert commentary. Best for: blog posts, innovation updates, most website copy.

The storytelling style builds trust because readers connect with real experiences. But it must always serve the content never use story as padding.


Takeaways

End substantial content (blog posts, articles, long pages) with bulleted takeaways:

  • Summarise the 3-5 most important points
  • Each takeaway should stand alone useful even without reading the full piece
  • Busy readers may only read the headline and takeaways make both complete

Content Quality Checklist

Before publishing any page or post, verify:

  • Headline promises a specific benefit or gives news
  • Lede hooks within the first 10 words no throat-clearing
  • Readability at target level (Fog Index 8-10 for general content)
  • Niche vocabulary used naturally topic covered with authority
  • Subheads every 2-3 paragraphs scannable on their own
  • Short paragraphs (4 lines max), short sentences (avg 15-20 words)
  • Benefits, not just features "so that / which means" test
  • Unique value what does this page offer that competitors don't?
  • CTA present reader knows what to do next
  • No jargon without explanation every word earnable by the reader
  • Active voice predominates strong verbs, concrete nouns
  • Images/visuals break up text at appropriate intervals
  • Captions on all images (read 2x more than body copy)
  • Proofread grammar, spelling, factual accuracy checked

Integration with Other Skills

This skill is cross-cutting it applies alongside:

  • language-standards tone, grammar, and formality per language (British English, formal French, East African Kiswahili)
  • premium-commercial-writing premium commercial purpose, differentiation, proof, objection handling, CTA logic, and SEO/AI-search visibility for high-stakes copy
  • page-builder implements these writing standards in Astro page content
  • seo headlines and niche vocabulary directly support search visibility
  • brand-alignment content voice must match brand identity
  • sector-strategies industry-specific content angles and trust signals

Evidence Produced

EvidenceFormatAcceptance condition
Reader-ready content draft decision traceSources, calculations, assumptions, countercase, and selected actionA reviewer can trace the selected action and rejected alternatives to the cited inputs.
Exception recordFailed and not-assessed checks with owner and due actionThe register exposes every unresolved exception that could lead to polishing generic copy that lacks proof or a usable next step.

Capability and Permission Boundaries

Read supplied records and use non-mutating checks to produce the reader-ready content draft; editing supplied copy without publishing it is permitted when requested. Do not publish, contact third parties, alter live systems, commit funds, or claim legal, tax, audit, valuation, ESG, or investment assurance without the owner's explicit authorisation and the appropriate reviewer.

Degraded Mode

If page purpose, reader task, facts, voice, and conversion path cannot be obtained, return a qualified reader-ready content draft covering only the checks that remain supportable. Leave this decision unresolved: which structure and language help the reader complete the task. Record the evidence owner and next check; an inaccessible source, tool, or reviewer is never a pass.

Decision Rules

Decision conditionActionFailure or risk avoided
Evidence is sufficient to decide: which structure and language help the reader complete the taskRecord the conclusion, source trail, owner, and review trigger in the reader-ready content draft.Risk of polishing generic copy that lacks proof or a usable next step
Material evidence conflicts or remains uncertainTest the competing structure against the reader's task and required next action, keeping the shorter version when both carry the same proof.Selecting an option without resolving the decision-relevant uncertainty
Required evidence is missing: page purpose, reader task, facts, voice, and conversion pathMark the decision on which structure and language help the reader complete the task not assessed in the reader-ready content draft, and send it to the editor and page owner.Otherwise, the work risks polishing generic copy that lacks proof or a usable next step

Quality Standards

Accept the reader-ready content draft only when evidence is sufficient for this decision: which structure and language help the reader complete the task. Assumptions and countercases remain visible, calculations and cross-references reconcile, and the reviewer can see how the recommendation addresses the risk of polishing generic copy that lacks proof or a usable next step.

Worked Example

A landing page lists twelve features before explaining the buyer's task. Reorder it around the problem, supported outcome, objections, and next action; remove claims the source pack cannot prove.

References

  • AGENTS.md - repository routing, evidence, finance, and release rules.
  • Article and blog phrase guidance - read while drafting web pages, articles and posts: headline, lede, evidence phrasing, transitions and before-and-after rewrites.
  • Business-plan phrase bank - read for the verb bank, precision words and evidence-class phrasing when content makes commercial or market claims.
<!-- dual-compat-end -->

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.