Skip to content
Skills Library
Documents & office · Writing

authoring-documentation

/authoring-documentation

Guidelines for writing documentation files including 11ty templates, Eleventy shortcodes, JSDoc annotations, and markdown content. Use this skill whenever the user works with documentation markdown files, Vale prose linting errors, Eleventy shortcodes (dodont, example), frontmatter, JSDoc annotations that must pass Vale, or the documentation site. Also trigger when the user mentions Vale errors, adding terms to the vocabulary, suppressing Vale rules, or writing and fixing prose in .md or .ts files.

Repository
elements ↗
Licence
Apache-2.0
Last repository change
27.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
2
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What to check before installing
  • SKILL.md zawiera komentarze HTML (2). Nie widać ich w podglądzie Markdown, a model je czyta.

What it does and when to use it

Guidelines for writing documentation files including 11ty templates, Eleventy shortcodes, JSDoc annotations, and markdown content. Use this skill whenever the user works with documentation markdown files, Vale prose linting errors, Eleventy shortcodes (dodont, example), frontmatter, JSDoc annotations that must pass Vale, or the documentation site. Also trigger when the user mentions Vale errors, adding terms to the vocabulary, suppressing Vale rules, or writing and fixing prose in .md or .ts files.

Original author description

Guidelines for writing documentation files including 11ty templates, Eleventy shortcodes, JSDoc annotations, and markdown content. Use this skill whenever the user works with documentation markdown files, Vale prose linting errors, Eleventy shortcodes (dodont, example), frontmatter, JSDoc annotations that must pass Vale, or the documentation site. Also trigger when the user mentions Vale errors, adding terms to the vocabulary, suppressing Vale rules, or writing and fixing prose in .md or .ts files.

How it works

  1. When to Use This Skill
  2. Key Principles
  3. Prose Linting (Vale)
  4. References
Original SKILL.md headings · 71 lines, 390 words
SKILL.md preview
---
name: authoring-documentation
description: Guidelines for writing documentation files including 11ty templates, Eleventy shortcodes, JSDoc annotations, and markdown content. Use this skill whenever the user works with documentation markdown files, Vale prose linting errors, Eleventy shortcodes (dodont, example), frontmatter, JSDoc annotations that must pass Vale, or the documentation site. Also trigger when the user mentions Vale errors, adding terms to the vocabulary, suppressing Vale rules, or writing and fixing prose in .md or .ts files.
---

# Documentation (`*.md`)

You MUST review @projects/site/src/docs/internal/guidelines/documentation.md before making any documentation changes.

## When to Use This Skill

- Creating or updating markdown documentation files
- Working with 11ty templates in the documentation site
- Using or creating Eleventy shortcodes
- Writing API documentation or component guides
- Updating internal guidelines or developer documentation
- Fixing Vale prose-linting errors in markdown or JSDoc

## Key Principles

1. **Frontmatter Required**: All documentation files must include proper frontmatter with title and layout
2. **Eleventy Shortcodes**: Use built-in shortcodes for common patterns (code examples, callouts, etc.)
3. **Clear Structure**: Use proper heading hierarchy and table of contents for long documents
4. **Code Examples**: Include working code examples with proper syntax highlighting
5. **Cross-References**: Link to related documentation and guidelines using proper paths

## Prose Linting (Vale)

### How Vale Runs

- **Pre-commit** (via lint-staged): automatically lints staged non-test `*.ts` and `*.md` files
- **CI**:runs as part of `pnpm run ci`
- **Manual**:`pnpm run lint:vale` from the repo root (pass specific files as args to narrow scope)

### Rule Sets by File Type

- `*.md`:Vale, Google, write-good, Elements (full rule set)
- `*.ts`:Vale, write-good, Elements (no Google rules or spelling checks to reduce noise on code identifiers)
- `*.examples.ts`:same as `*.ts` plus three summary rules: `SummaryStyle`, `SummaryActionable`, `SummaryGerund`

### Common Errors and Fixes

| Rule                    | Trigger                                       | Fix                                                                          |
| ----------------------- | --------------------------------------------- | ---------------------------------------------------------------------------- |
| `Google.Latin`          | `e.g.`, `i.e.`                                | Use "for example," "that is"                                                 |
| `Google.Passive`        | Passive voice                                 | Rewrite in active voice                                                      |
| `Google.Quotes`         | Punctuation outside quotes                    | Move commas/periods inside quotation marks                                   |
| `Elements.Branding`     | `nvidia`, `Nvidia`                            | Always use `NVIDIA`                                                          |
| `Elements.Terminology`  | `web component`                               | Use `Web Component` / `Web Components`                                       |
| `Vale.Spelling`         | Unknown term                                  | Add the term to `config/vale/styles/config/vocabularies/Elements/accept.txt` |
| `Elements.SummaryStyle` | Weak openers like "This example demonstrates" | Lead with what the example does or when to use it                            |

### Suppressing Rules

Use sparingly, and re-enable immediately after the affected content:

```markdown
<!-- vale Google.Quotes = NO -->
content here
<!-- vale Google.Quotes = YES -->
```

### Key Files

- `.vale.ini`:root config (rule toggles, file-type scopes, token ignores)
- `config/vale/styles/Elements/`:custom rules (Branding, Terminology, Summary\*)
- `config/vale/styles/config/vocabularies/Elements/accept.txt`:approved vocabulary

## References

- [Documentation Guidelines](/projects/site/src/docs/internal/guidelines/documentation.md)
- [Examples Guidelines](/projects/site/src/docs/internal/guidelines/examples.md)
- [Vale Config](/.vale.ini)
- [Custom Vale Rules](/config/vale/styles/Elements/)

Versions

The database has no other skills named authoring-documentation.

Database snapshot: 13.11.2026 · package version 7491f4e1c042 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 2 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100vale
    Run Vale prose linter and auto-fix issues. Use when linting or proofreading markdown/text.
  • 100setup
    Install Vale, write a .vale.ini, sync styles, and get a first run. Use when the user says "set up vale", "add vale", "add prose linting", or "lint our docs" in a repository that has no Vale config yet.
  • 100fix
    Run Vale, fix error-level alerts, and open a pull request per file. Use when the user says "run vale", "fix vale errors", "lint the docs", "fix the linter", or "make vale pass". Fixes errors only; leaves warnings and suggestions for a person.
  • 100vale
    Install, repair, and validate Vale prose linting. Use when users need Vale config, style sync, docs lint gates, or broken Vale workflow diagnosis.
  • 100vale
    Guide for Vale prose linting — the eleven extension points, .vale.ini scoping and section globs, alert-level burn-down, and suppression comments. Use when authoring or editing a Vale style rule, debugging a prose-lint false positive, or choosing which extension point fits a new…
  • 100docs-site
    This skill should be used when scaffolding a Markdown-based Eleventy documentation site: base layout, data files, GitHub Pages deployment workflow, and passthrough copy configuration.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.