# Editorial Guidelines

> Use when the user wants to create, update, or overhaul brand editorial guidelines, voice and tone rules, or a style guide for their content. Runs an interview and produces a reusable editorial-guidelines.md that all other content skills read.

- Skill: `busyeugene/editorial-guidelines` (Agent Skill)
- Install (CLI): `npx skillmds@latest add busyeugene/editorial-guidelines`
- Raw SKILL.md: https://api.skillmd.com/api/skills/busyeugene/editorial-guidelines/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: busyeugene (https://skillmd.com/u/busyeugene)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/busyeugene/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

```markdown
# 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.