netresearch/typo3-docs-skill / skills/typo3-docs
typo3-docs
FlaggedUse when TYPO3 extension documentation has to render on docs.typo3.org, which builds a manual from Documentation/guides.xml and reads no Settings.cfg (a single README.rst serves an extension too small for one): when an extension has no documentation yet, or when creating, editing or reviewing Documentation/*.rst, guides.xml, README.md or XLF translations, rendering docs with Docker, TYPO3 RST directives, screenshots, or XLIFF 2-space indentation (TYPO3 v14+).
references/canonical-sources.md
View on GitHub<!-- SPDX-License-Identifier: CC-BY-SA-4.0 -->
<!-- SPDX-FileCopyrightText: Netresearch DTT GmbH -->
# Canonical Sources — who owns which truth
The official TYPO3 How-to-Document manual is the canonical source for TYPO3
documentation standards. This skill legitimately carries three things:
- **workflow, scripts, and extraction/validation tooling** (its own procedure),
- **agent-specific failure patterns** observed in real sessions — for instance
the height check that reveals a backend screenshot stopped at the outer
frame. Note what that example is *not*: the `fullPage` behaviour itself went
upstream on 2026-08-15 and the copy here was pruned the same day. What stays
is the tell, because upstream describes the trap and not how to notice you
fell into it,
- **deliberately stricter Netresearch policy**, labelled as such.
Everything else is a *reference* to upstream, not a copy. A duplicated
upstream rule needs justification and evidence; an agent-specific rule needs
an observed failure mode; a Netresearch rule must be labelled as Netresearch
policy — anything else is removed or referenced.
## On conflict, the live upstream page wins
Do not enforce a cached skill rule against current official documentation:
follow the live manual, then **report the drift** (e.g. via `/retro`) so the
skill gets fixed. Where upstream itself is wrong or incomplete, propose an
upstream PR instead of widening the local copy — see
`upstream-docs-contribution.md`.
**And when such a PR is accepted, the local copy shrinks the same day.** A copy
kept after its fact has a canonical home is no longer a stopgap: it is a second
source that drifts, and the checkpoints keep it green while upstream moves on.
Prune it to a reference plus whatever genuinely remains agent-specific — the
executable recipe, the failure tell, the case upstream does not cover — and say
in the file which date it became `[upstream]`, so the next reader can see the
copy was retired deliberately rather than forgotten. Done for the screenshot
viewport/iframe rules and the `Documentation/` symlink rule on 2026-08-15,
accepted upstream the same day.
## Topic → canonical source
| Topic | Canonical source |
|---|---|
| RST coding guidelines (indentation, wrapping, headings) | [CGL for ReST files](https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Reference/CodingGuidelines/Index.html) |
| Images and screenshots (formats, necessity, dimensions) | [Guidelines for images](https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Advanced/GuidelinesForImages.html) |
| `guides.xml` settings and their allowed values | [guides.xml reference](https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Reference/GuidesXml.html) |
| File structure and naming | [File structure](https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Reference/FileStructure.html) |
| Directives, text roles, content elements | [reStructuredText reference](https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Reference/ReStructuredText/Index.html) with per-topic subpages (Confval, Phpdomain, Cards, Tabs, Versions, Accordion, Tables, ViewHelper, Diagrams) |
| Image/figure directives, CSS classes, zoom modes | [Images](https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Reference/ReStructuredText/Graphics/Images.html) and [Image zoom](https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Reference/ReStructuredText/Graphics/ImageZoom.html) |
| Rendering (container, init, watch mode) | [Rendering container](https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Reference/RenderingContainer.html) and [Rendering howto](https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Howto/RenderingDocs/Index.html) |
| Webhook/Intercept deployment | [Webhook setup](https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Howto/WritingDocForExtension/Webhook.html) and [Documentation for extensions](https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Howto/WritingDocForExtension/Index.html) |
| Extension file/directory anatomy | [Core API: Files and locations](https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ExtensionArchitecture/FileStructure/Index.html) |
| Auto-provided interlink inventories | [render-guides: Interlink inventories](https://docs.typo3.org/permalink/t3renderguides:interlink-inventories) |
| Screenshot container setup | [Screenshot container](https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Reference/ScreenshotContainer/Index.html) |
| TYPO3 core behaviour cited in docs | TYPO3 core **source** (raw GitHub, see `upstream-docs-contribution.md`) — never rendered HTML, never memory |
| The extension's own values (version, CLI flags, API signatures) | The extension's code and manifests (`ext_emconf.php`, `Command::configure()`, `Classes/`) |
## Provenance labels
Rules in this skill's references and `checkpoints.yaml` carry one of four
provenance classes (schema: automated-assessment-skill,
`references/checkpoints-schema.md` §Provenance):
| Label | Meaning | Price of entry |
|---|---|---|
| `[upstream]` | Restates the official manual | Source link; re-verify on any conflict |
| `[NR policy]` | Deliberate Netresearch rule at or beyond upstream | Named rationale; never presented as "the TYPO3 standard" |
| `[heuristic]` | Quality preference | Lowest severity; never presented as a normative rule |
| `[regression]` | Guards an observed agent failure | The observed failure (session/issue/PR) |
Known deliberate deviations from upstream:
| Rule | Upstream says | Netresearch says | Class |
|---|---|---|---|
| `project-contact` / email addresses | `mailto:` explicitly allowed (it is the documented example) | No `mailto:`/email in public docs — spam and PII exposure; use Issues/Discussions URLs | `[NR policy]` |
| Screenshot format | PNG **or AVIF** | PNG preferred for consistency; AVIF acceptable | `[NR policy]` (soft) |
| RST page length | No limit exists | Aim for ≤ ~250 lines, split with `toctree` | `[heuristic]` |
| Screenshots for backend modules/config | "Consider if one is necessary" | Strongly encouraged where they aid understanding — never blind, necessity check first | `[heuristic]` |
| Image location | Examples use `/_Images/` | `Documentation/Images/`, organized by section | `[NR policy]` |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |