Przejdź do treści
Biblioteka skilli
Dokumenty i biuro · Przegląd i audyt

writing-guidelines

/writing-guidelines

Sprawdza dokumenty i prozę pod kątem ogólnych zasad pisania i zgłasza ustalenia w formie plik:linia z poprawką.

Repozytorium
The-Insectoids ↗
Licencja
MIT
Ostatnia zmiana repozytorium
12.11.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
1
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 12.11.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Sprawdza dokumenty i prozę pod kątem ogólnych zasad pisania i zgłasza ustalenia w formie plik:linia z poprawką.

Oryginalny opis (EN)

Review docs and other prose against general writing rules (planning, voice, banned filler and hype words, sentence patterns, headings, lists, code samples, numbers and units, typography, links, accountability) and report findings as file:line lines with a fix. Use when asked to review docs, check writing style, audit prose, or check voice and tone.

Jak działa

  1. When to use
  2. When not to use
  3. How to review
  4. Rules
  5. Output format
Sekcje z nagłówków SKILL.md, w oryginale · 120 linii, 1 249 słów
Podgląd SKILL.md
---
name: writing-guidelines
description: Review docs and other prose against general writing rules (planning, voice, banned filler and hype words, sentence patterns, headings, lists, code samples, numbers and units, typography, links, accountability) and report findings as file:line lines with a fix. Use when asked to review docs, check writing style, audit prose, or check voice and tone.
metadata:
  kind: skill
  castes: [writer, documenter, reviewer]
  tags: [writing, docs, review, style]
  version: 1
  status: vetted
  sources:
    - repo: vercel-labs/agent-skills
      path: skills/writing-guidelines/SKILL.md
      license: MIT
    - repo: vercel-labs/agent-skills
      path: README.md
      license: MIT
    - repo: vercel-labs/agent-browser
      path: .agents/skills/technical-writer/references/editorial-standards.md
      license: Apache-2.0
---

# Writing Guidelines

Check prose against rules that make it clear, direct and accurate. Report problems precisely; do not rewrite the document unless asked.

## When to use

- A card asks to review docs, check writing style, audit prose, or check voice and tone.
- Before shipping a page written by another agent.
- As the style pass at the end of `technical-writing`.

## When not to use

- Checking whether technical claims are true: that is part of `technical-writing` (verification).
- Agent-to-agent messages: those follow `compact-output`, not these rules.

## How to review

1. Get the target files or pattern from the card. If none is given, report `blocked` and ask the Queen which files.
2. Read each file in full. Identify its content type (tutorial, how-to, reference, explanation, troubleshooting, README, release note) and its destination.
3. Check for a project style guide or house rules. They override these defaults where they conflict.
4. Apply the rules below. Judge in context: a listed word is a signal to check, not proof of a problem.
5. Never flag exact names, code, quoted errors, UI labels or quotations because they contain a listed word.
6. Output findings in the format at the end.

## Rules

### Planning
- The page has one clear purpose and one content type. Do not mix tutorial, reference and explanation.
- Titles describe the reader's task or question ("Deploy a preview branch"), not the feature's internals.
- The page opens with the answer or outcome (a short summary first on long pages).

### Voice and tone
- Address the reader as "you". Use imperative verbs for steps.
- Active voice and present tense. Passive voice only when the actor is unknown or irrelevant.
- Contractions are fine where natural. Use "we" only for real commitments by a named team.
- Professional, direct, specific; like a knowledgeable colleague.
- Tone fits the type: tutorials encourage and explain; how-tos are brisk; references are neutral and exact; troubleshooting is calm and diagnostic.
- Keep real uncertainty. Remove hedges from verified instructions, but never turn a conditional behavior into a guarantee.

### Words to cut or replace
- **Unsupported ease and quality claims:** easy, simple, simply, quick, seamless, effortless, powerful, innovative, comprehensive, robust. Replace with what the reader does or what the system provides.
- **Inflated words:** delve, foster, leverage, utilize, facilitate, empower, streamline, cutting-edge, game changer, paradigm shift, tapestry, realm, beacon, multifaceted, meticulous, intricate, paramount, transformative, elevate, embark, supercharge, harness, ever-evolving. Check inflected forms too.
- **Empty intensifiers:** just, very, basically, obviously, literally, honestly, actually, truly, fundamentally, importantly, crucially, inherently. Keep a qualifier only if it carries real scope or uncertainty.
- **Filler phrases:** "it's worth noting", "at the end of the day", "when it comes to", "at its core", "in today's world", "the reality is", "going forward", "let's dive in". "In order to" becomes "to". Do not swap one filler for another.
- **Vague metaphors** that hide a mechanism: substrate, nexus, flywheel, north star. Keep precise domain terms.

### Sentence and paragraph patterns

| Pattern | Example | Fix |
|---|---|---|
| Negation-and-reveal | "This isn't X. It's Y." / "not just X, but Y" | State Y directly; keep negation only for a real limit |
| Throat-clearing | "Here's the thing", "Let me be clear" | Start with the information |
| Dramatic reveal | Self-answered question or staged colon | State the answer |
| Importance claim | "plays a vital role", "this distinction matters" | Describe the role and its effect |
| Trailing significance | "..., highlighting the need for X" | Name the consequence or cut it |
| Vague authority | "experts agree", "studies show" | Cite the source or remove the claim |
| Inflated verb | "serves as a centralized hub" | Use the action: "stores", "routes" |
| Synonym cycling | one component called tool, platform, system | One term per thing |
| Forced triplets | lists padded to three items | Use the natural number of items |
| Coverage announcement | "This guide covers X, Y and Z" | Delete; headings already navigate |
| Decorative ending | aphorism or recap closing a section | End on the useful fact or action |
| Fake human touch | invented anecdotes or opinions | Remove; voice comes from relevant detail |

Also check across the whole document: repeated sentence openings and shapes, explanations repeated across sections, a connected explanation chopped into abrupt fragments, and sentences so dense the reader must backtrack.

### Headings and structure
- Sentence-case headings, no terminal periods, logical hierarchy without skipped levels.
- Descriptive subheadings: question headings for real questions, imperative headings for tasks.
- One concept per section. Keep required instructions in the main flow, not hidden in callouts.

### Lists and tables
- Bullets for parallel, distinct items; numbered lists for ordered steps; tables for items that share attributes.
- Keep connected reasoning as paragraphs; bold labels cannot fix disconnected prose.
- List items share one grammatical form. If items use a bold label plus description, every item does.

### Code samples
- Every fenced block has a language tag.
- Examples are complete (imports, config) or clearly labelled as excerpts with where they go.
- Lead with the project's primary language when several are shown; keep variants consistent.
- Keep blocks short and narrow (aim for about 25 lines and 80 columns) unless the destination says otherwise.
- Inline code for paths, commands, identifiers, env vars and literal values.
- No secrets; use env vars and descriptive placeholders.

### Placeholders, numbers and units
- Placeholders are descriptive `snake_case` text (`your_project_id`), used consistently. Avoid `<name>` forms in shell commands.
- Numbers as numerals with units, separated by a space: `64 KB`, `200 ms`. Keep units consistent; distinguish bytes from bits and KB from KiB.
- Expand unfamiliar abbreviations on first use. Common developer terms (API, URL, HTTP, HTML, CSS) need no expansion for developers.

### Typography and source formatting
- No em dashes as sentence punctuation in new prose; rebuild the sentence or use a colon for lists, labels and examples.
- One quote style per document, following the destination. Never change quotes inside code or exact quotations.
- No decorative emoji. Bold for exact UI labels; other emphasis sparingly.
- Source files: do not hard-wrap prose lines, no decorative `---` rules, one blank line between blocks.

### Links
- Descriptive link text. No "click here", no "this link", no sentence that only announces a link.
- Never fabricated URLs. Link the specific page that supports the claim.

### Accountability (AI-assisted writing)
- The author is accountable for every claim, whoever drafted it. Unverified claims are flagged, not shipped.
- Plan the page (type, reader, outline) before drafting.
- Disclose AI assistance where the destination's policy requires it.
- Change descriptions (PRs, changelogs) say what changed and why, in the author's own review.

## Output format

One finding per line, grouped by file, in line order:

```
<file>:<line>: <severity> [<rule>] <problem>. Fix: <replacement or action>.
```

Severity:
- `error`: misleading, wrong, or blocks the reader (vague authority, broken structure, missing language tag on a command block).
- `warn`: clear rule breach that weakens the page (hype word, passive step, synonym cycling).
- `nit`: minor polish.

End with one summary line per file: `<file>: <n> error, <n> warn, <n> nit.` If a file has no findings, write `<file>: clean.` Do not pad the report with praise or general advice.

Wersje

RepozytoriumWynikLicencja
Ta strona · Sanit-mann/The-Insectoids100MIT
fcakyon/claude-codex-settings100Apache-2.0
FrancoStino/opencode-skills-collection100MIT
nexu-io/open-design100Apache-2.0
sickn33/agentic-awesome-skills100MIT
PracticalSwan/agent-skills100MIT
joe-bell/cva100Apache-2.0

Migawka bazy z 13.11.2026 · wersja paczki ddcdc8f3a198 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100lemma-writing-guidelines
    Sprawdza dokumentację i teksty pod kątem zgodności z wytycznymi pisania: ton, głos i styl, na przykład przy przeglądzie stron względem podręcznika pisania.
  • 100review-guidelines
    Sprawdza zmiany w kodzie pod kątem zgodności z wytycznymi z CLAUDE.md.
  • 100docs-writing-style
    Ustala styl prozy dokumentacji Dagger w docs/current_docs: głos, zakres, nazewnictwo i dokładność, uzupełniając STYLE_GUIDE.md.
  • 100web-design-guidelines
    Sprawdza kod UI względem wytycznych Vercel i podaje naruszenia w formie plik:linia, obok kontroli tokenów i WCAG.
  • 90ring:reviewing-docs
    Przegląda jakość dokumentacji użytkownika i produktowej pod kątem tonu, struktury, kompletności, jasności i poprawności technicznej, z priorytetyzowanymi ustaleniami i werdyktem zaliczone lub do poprawy.
  • 100avoid-ai-writing
    Przegląda tekst pod kątem typowych wzorców pisania AI przy redakcji treści, zachowując fakty i głos autora.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.