Przejdź do treści
Biblioteka skilli
Programowanie · Pisanie

technical-writing

/technical-writing

Pisze i przegląda opisy kontraktów, zachowań i decyzji w markdownie, na wiki i w README, sprawdzając, czy czytelnik ma nową informację.

Repozytorium
revit-skills ↗
Licencja
MIT
Ostatnia zmiana repozytorium
08.10.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
4
Adresy URL w SKILL.md
0
Przestarzałość

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

Licencja

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

Co sprawdzić przed instalacją
  • SKILL.md zawiera komentarze HTML (4). Nie widać ich w podglądzie Markdown, a model je czyta.

Co robi i kiedy

Pisze i przegląda opisy kontraktów, zachowań i decyzji w markdownie, na wiki i w README, sprawdzając, czy czytelnik ma nową informację.

Oryginalny opis (EN)

Write or review reference prose in the house register — markdown documents, wiki pages, README and CONTRIBUTING text, and configuration comments. USE FOR: explaining a contract, a behavior, a decision, or an API in human-readable text, and reviewing that a text says something a reader cannot already infer. DO NOT USE FOR: comments inside source code and documentation comments on an API, both of which follow the conventions of the language; or the body of an issue, a pull request, or a comment on one, whose shape and register the workflow standard states.

Jak działa

  1. When to use
  2. Rules
  3. Examples
  4. Validation
  5. Common Pitfalls
Sekcje z nagłówków SKILL.md, w oryginale · 142 linii, 1 620 słów
Podgląd SKILL.md
---
name: technical-writing
description: >
    Write or review reference prose in the house register — markdown documents, wiki pages, README and CONTRIBUTING text, and configuration comments.
    USE FOR: explaining a contract, a behavior, a decision, or an API in human-readable text, and reviewing that a text says something a reader cannot already infer.
    DO NOT USE FOR: comments inside source code and documentation comments on an API, both of which follow the conventions of the language; or the body of an issue, a pull request, or a comment on one, whose shape and register the workflow standard states.
license: MIT
---

# Technical Writing

Write to an enterprise production standard in a strict technical register, never a tutorial or a marketing voice.
Open with the fact the reader needs, describe observable behavior, and cut anything a reader can already infer.
Every reference text follows this standard: a wiki page, a README, a CONTRIBUTING guide, and a comment inside a configuration file.
The standard follows the Microsoft Writing Style Guide: lead with the fact, write short paragraphs, favor the active voice and the serial comma, capitalize a heading in sentence case, spell out a Latin abbreviation in full, and name a person without gender.
The register is third person.
A stranger reads a reference page, and the page never addresses the reader as "you".

## When to use

- Writing or reviewing reference markdown in a repository.
- Reviewing a text that reads as a narration of the change instead of a statement of the result.
- Writing or reviewing a comment that annotates a declaration, a key, or a block of a configuration file.

## Rules

- Use plain technical English and the third-person present indicative in reference prose.
- Write in the active voice: the subject performs the action, and a value is never acted upon by an unnamed actor.
- Write one sentence per line, with one idea per sentence.
- Ignore the line length; a sentence occupies one line however long it runs, and no line is wrapped by hand.
  The IDE reflows the file to the limits configured for it.
- Place a comma before the conjunction in a list of three or more items.
- Spell out `for example`, `that is`, and `and so on`; never `e.g.`, `i.e.`, or `etc.`.
- Name a person, a role, or an audience without gender, and without an idiom tied to one culture.
- Use a heading that names its subject, with a colon where the heading introduces a variant or a qualifier.
  Capitalize it in sentence case, its first word and any proper noun alone, except a section a template fixes or a title matching its file's name.
- Use a list only where the reader acts on, compares, or remembers several items.
- Use a table where several items share the same set of attributes.
- State a negative only where a competent reader would otherwise make a plausible, harmful assumption.
- Link the maintained list of identifiers, endpoints, or values; never copy it.
- State no count and no enumeration the neighbouring source already lists: the rows of a table, the members of an adjoining list, the files of a directory.
  The reader reads them in the source, and a restatement becomes outdated when an item is added.
- Avoid corporate language, filler, meta-preambles, and trailing `including…` examples.
- Comment the intent, the constraint, or the invariant a file cannot state itself; add none where the file already states it.
  The name of a declaration states its meaning, and a comment is added only where a competent reader draws a wrong conclusion without one.
  A comment never restates the name, the value, or the block below it.
- Judge every sentence as final standalone text.
  The reader has the page as it stands, with no previous version, diff, or request to compare against.
- Cut every purpose, result, cause, and comparison clause: `so`, `that makes`, `which makes`, `because`, `rather than`.
  A clause that states a fact the reader needs becomes its own sentence.
- Name every operation with the term its own domain defines.
  A component requests, returns, requires, reports, or selects; a value is passed or assigned; a subscriber receives an event; a person is notified.
- Name every relation with the verb specific to its subject.
  A text states, lists, defines, or describes; a file contains or stores; a type declares or exposes; a method returns; a rule applies to its scope.

## Examples

```markdown
<!-- BAD -->
This page describes external events. We added them because the API is not reachable from a modeless window, which makes a direct call fragile, so a queue was introduced to solve the problem.

<!-- GOOD -->
An external event executes a unit of work in the Revit API context.
A caller constructs the event and raises it from any thread, and Revit invokes the handler inside the API context.
An external event opens no transaction; the handler opens its own.
```

```markdown
<!-- BAD -->
The view model asks the repository for the open document and answers the command with the result.
The binding wants a source that is not null, and the validator decides whether the entry is valid.
An event travels to every subscriber.

<!-- GOOD -->
The view model requests the open document from the repository and returns the result to the command.
The binding requires a source that is not null, and the validator reports whether the entry is valid.
Every subscriber receives the event.
```

A comment on a declaration names the role of that declaration in the system, or the invariant behind a value.

```text
# BAD
# The catalogue viewer, a second process of the frontend group on a port of its own, declared in this same file.
# The internal gateway alone carries this route, and every public gateway resolves the frontend on its plain port, so no public host reaches it.
component "catalogue" {

# GOOD
# The gateway of the public applications and of the internal-only endpoints.
component "gateway" {

# GOOD
# The cache every service of the environment shares.
component "cache" {
```

```text
# BAD
# The instance count, two in production and one everywhere else.
instances = environment == "production" ? 2 : 1

# GOOD
# The second instance serves the route while a rolling deployment replaces the first.
instances = environment == "production" ? 2 : 1
```

## Validation

- [ ] The text describes behavior, not implementation mechanics.
- [ ] Prose follows one-sentence-per-line formatting, and no line is wrapped at a column limit.
- [ ] Every sentence states a fact in the present indicative and the active voice, and none narrates the change or argues why.
- [ ] A list of three or more items takes the serial comma, and no `e.g.`, `i.e.`, or `etc.` appears.
- [ ] Every heading not fixed by a template, and not a title matching its file's name, is sentence case.
- [ ] No term names a gender or an idiom tied to one culture.
- [ ] No list of constants, endpoints, or options is copied where the authoritative source can be linked.
- [ ] No sentence states a count or an enumeration the neighbouring source already lists.
- [ ] The first sentence of a section adds information the heading does not.
- [ ] Every comment states what its file cannot, and none restates the name, the value, or the block below it.
- [ ] Every commented declaration is one a reader would otherwise misread, and the rest have no comment.
- [ ] Every operation and every relation is named by the verb its domain defines: a text states or lists, a file contains or stores, a type declares, a method returns, and a component requests or reports.

## Common Pitfalls

| Pitfall                                                        | Correct approach                                        |
|----------------------------------------------------------------|---------------------------------------------------------|
| A preamble before the point ("This section describes…")        | Lead with the fact the reader needs.                    |
| Copying a list of constants or endpoints into prose            | Link the authoritative source.                          |
| A count or an enumeration the source beside it lists           | Link the source.                                        |
| Restating the heading in the first sentence                    | Add new information.                                    |
| Documenting how the code works today                           | Document the observable contract.                       |
| Narrating the edit ("renamed X to Y because…")                 | State what the code now is.                             |
| A rationale clause ("… so …", "… that makes …", "rather than") | State each fact in its own present-indicative sentence. |
| "The validator decides whether the entry is valid."            | "The validator reports whether the entry is valid."     |
| A paragraph promising work still to come                       | Add a `// TODO:` in the code at the place it belongs.   |
| A paragraph hard-wrapped at 80 or 120 characters               | One sentence, one line, whatever its length.            |
| A comment naming the key below it                              | State the constraint on the key.                        |
| A comment paraphrasing the block it opens                      | Drop it; the block states itself.                       |
| A comment pointing at its own file                             | State the role of the declaration in the system.        |
| A comment above every declaration of a file                    | Comment the one declaration a reader misreads.          |
| A name that needs a comment to be understood                   | Rename the declaration.                                 |
| "The setting is read by the host at startup."                  | "The host reads the setting at startup."                |
| `e.g.`, `i.e.`, or `etc.` in prose                             | Spell out `for example`, `that is`, `and so on`.        |
| `## Common Configuration Options`                              | `## Common configuration options`.                      |
| "The section carries three facts."                             | "The section lists three facts."                        |
| "The fact lives in the readme."                                | "The readme states the fact."                           |
| "The rule reaches every section."                              | "The rule applies to every section."                    |
| "The table holds the supported versions."                      | "The table lists the supported versions."               |
| "The configuration file keeps the connection string."          | "The configuration file stores the connection string."  |
| "The response carries the status code."                        | "The response contains the status code."                |

Wersje

RepozytoriumWynikLicencja
Ta strona · nice3point/revit-skills100MIT
ericrisco/rsc-harness100MIT
sma1lboy/rove100MIT
Calvin-LLC/skills100MIT
chmonitor/chmonitor100GPL-3.0
KyaniteHQ/threadsift100AGPL-3.0
asarelcastellanos/claude-workbench100MIT
guangshinhaha/shinstack100MIT
valsteen/pinboard100MIT

Migawka bazy z 13.11.2026 · wersja paczki aaf628be5505 (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

  • 100writing-xml-doc-comments
    Pisze i przegląda komentarze dokumentacyjne XML w C# dla publicznego API, z opisem parametrów i wartości zwracanych.
  • 90csharp-style
    Pisze i przegląda kod w C# według zasad stylu, pomijając komentarze XML i zwykły tekst.
  • 90ai-write
    Pisze dokumentację techniczną repozytorium (README, strona wiki, dokumentacja produktu, dokumentacja API, wpis techniczny) według jednego standardu pisania frameworka i weryfikuje każdy dokument względem drzewa plików.
  • 100code-documentation
    Pomaga pisać dokumentację kodu: README, dokumentację API, komentarze i przewodniki dla programistów.
  • 100technical-documentation-engineering
    Opisuje praktykę utrzymywania README, krótkich zapisów decyzji i dokumentów zmienianych w tym samym PR co kod.
  • 100repo-docs
    Porządkuje folder docs i wiki repozytorium: strony, nazwy, kolejność i linki, z szablonami dla typów stron i sprawdzaniem linków.

Uwagi i zgłoszenia

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