Editorial Guidelines

Editorial Guidelines

Interview the user and produce a single editorial-guidelines.md at the project root. Every other content skill in this library reads that file as its source of truth for voice, tone, and formatting.

Setup

No API keys required. Optional: if the user provides example article URLs and a scraper is configured (see _shared/firecrawl-jina-playwright-helpers.md), this skill cross-checks the stated guidelines against real on-brand writing.

Inputs

Conduct the interview below. Ask one question at a time; use AskUserQuestion with 2–4 options where the choice is constrained, otherwise ask conversationally. If the user says "skip" or "use defaults", fall back to the seed values in {SKILL_BASE}/../_shared/b2b-saas-voice-reference.md.

1. Brand name + one-sentence positioning. ("Acme is the RevOps platform for Series B+ SaaS companies that have outgrown spreadsheets.")
2. ICP / primary audience. Role, seniority, main pain. Ask for 1–3 segments.
3. Content goals (multi-select): SEO rankings, thought leadership, demand generation, support deflection, product education, community.
4. Voice attributes. Offer: direct, opinionated, peer-level, playful, authoritative, warm, provocative, analytical, empathetic, irreverent. Pick 3–5.
5. Tone sliders. Formal ↔ casual (1–5). Serious ↔ playful (1–5).
6. Reading level target. Flesch range or grade level (default: Flesch 60–70, grade 8).
7. POV. We / You / I / Third person. Can be mixed — ask which in which contexts.
8. Banned words and phrases. Collect a list. Seed with the banned list in b2b-saas-voice-reference.md.
9. Preferred words and product-naming conventions. Capitalization quirks, competitor product names, acronyms to spell out on first use.
10. Formatting rules. Serial comma (Y/N), numerals vs. words, headings case (title ↔ sentence), code fences, link style, emoji policy, contractions.
11. Structural defaults per format. For each of how-to, comparison, opinion/POV, case study — ask for preferred section order or accept the defaults in the voice reference.
12. Example articles. Ask for 2–3 URLs the user considers "on brand" and 1–2 they consider "off brand". Optional.

Process

1. Check for existing file. Use Glob for editorial-guidelines.md at the project root. If it exists, ask: overwrite, update in place, or save a new version with date suffix.
2. Run the interview. Ask the 12 questions above, one at a time. For any question the user skips, record the seeded default and note (default) next to it in the output.
3. Optional cross-check. If the user provided example URLs and a scraper is available:
   • For each URL, fetch the article via the fallback chain in _shared/firecrawl-jina-playwright-helpers.md.
   • Extract observable patterns: median sentence length, heading cadence, paragraph length distribution, top 20 content words excluding stopwords, presence of first-person vs second-person, use of contractions, emoji count.
   • If any stated rule contradicts observed patterns (e.g. user says "formal" but examples are casual), surface the contradiction and ask which to trust.
4. Render the file. Write editorial-guidelines.md using the template below.
5. Confirm. Print the path and a 5-line summary (brand, audience, voice attributes, top 3 banned words, reading level).

Output template

# Editorial Guidelines — {Brand}

_Last updated: {YYYY-MM-DD}_

## Brand positioning

{One sentence.}

## Audience

{Segment 1}
- Role / seniority:
- Primary pain:
- What they already know:
- What they're skeptical of:

{Repeat for each segment.}

## Content goals

- {goal 1}
- {goal 2}

## Voice

**Attributes:** {attr1}, {attr2}, {attr3}, {attr4}

{One paragraph describing how these combine in practice. Include one "we sound like X, not Y" contrast.}

## Tone

- Formal ↔ casual: {1–5} — {1-sentence rationale}
- Serious ↔ playful: {1–5} — {1-sentence rationale}
- POV: {we / you / I / third}
- Contractions: {yes / no}
- Emoji: {never / headlines only / body OK}

## Reading level

Target: Flesch {x}–{y} (grade {n}). Sentences median {m} words, max {max}.

## Structural defaults

### How-to
{ordered sections}

### Comparison
{ordered sections}

### Opinion / POV
{ordered sections}

### Case study
{ordered sections}

## Formatting

- Serial comma: {Y/N}
- Numerals: {rule}
- Headings: H1 {case}, H2/H3 {case}
- Links: {inline / footnote}, new tab {Y/N}
- Code: inline `monospace`, fenced blocks with language tag
- Lists: {bullet style, when to use numbered}
- Dates: {format}

## Banned words and phrases

- {word 1}
- {word 2}

## Preferred words and naming

- {Product} — always written as `{exact casing}`
- {Acronym} — spell out on first use as `{expansion}`

## Examples

**On brand:**
- {URL 1} — {what makes it on brand, 1 line}

**Off brand:**
- {URL 1} — {what makes it off brand, 1 line}

## Quality bar

Before shipping, every piece must pass:

1. {rule 1 — default: "Would I send this to a practitioner friend unprompted?"}
2. {rule 2 — default: "Does it contain at least one thing not in the top 3 ranking articles?"}
3. {rule 3 — default: "Is every claim linked to a source or showing its work?"}
4. {rule 4 — default: "Does the closer tell the reader a specific next action?"}

Fallbacks

• No scraper available: skip the cross-check step and note in the output that examples were not validated against observed patterns.
• User refuses interview: write a file using 100% defaults from b2b-saas-voice-reference.md, prefixed with a note that the file is a starting point and should be edited.
• Existing file, user wants update: diff the old file against new interview answers, only change fields the user updated, preserve everything else.

Verification

1. editorial-guidelines.md exists at the project root.
2. It contains all sections from the template.
3. Run proofreading-style-check against any article using this file — it should return at least one voice/tone finding that references a rule in the guidelines.