Write documentation with AI assistance 

You can use an AI assistant to write or change TYPO3 documentation, for example a coding agent in your editor or terminal. The same rules apply as for every other contribution. This page shows how to give the assistant these rules, and how to check its work.

You are responsible for the result 

The assistant writes a draft. You submit the change, so check it as if you had written it yourself:

  • Read every line of the diff before you commit it.
  • Verify every technical fact against the source code: class names, method signatures, option names, defaults, and the version that added or removed something. An assistant often writes a fact from memory, and that memory can be out of date.
  • Check the facts against the TYPO3 version of the branch that you write on. On the main branch of a manual, this is the main branch of the TYPO3 Core, the version in development.
  • Make sure that no anchor was deleted. See Keeping anchors working.

The commit message in official documentation 

A change to the official TYPO3 documentation follows the rules for commit messages, also when an assistant wrote it. One of these rules is about AI assistance:

  • End with a Signed-off-by: Your Name trailer. Add an Assisted-by: <tool/model name> <contact> trailer too, if you used AI assistance for more than a basic spelling or grammar check.

The Signed-off-by trailer names you, the contributor. The Assisted-by trailer names the tool or the model:

Example commit message 
[TASK] Add missing alt text for screenshots

Screen reader users could not tell what the two new screenshots showed.
Add descriptive alt text to both.

Assisted-by: Claude Sonnet 5 <noreply@anthropic.com>
Signed-off-by: Jane Doe
Copied!

The AGENTS.md of a repository can add trailers of its own, such as Releases: in a manual with a branch per TYPO3 version.

Instructions in the repository 

Most official TYPO3 manuals have a file AGENTS.md at the root of their repository. Most coding agents read this file by themselves when they start to work in the repository. It names the structure of the repository, the commands to render and test it, its branches, and its commit trailers. For the writing rules, it links to this guide and does not copy them.

Some repositories also have a file CLAUDE.md. It only points to AGENTS.md, because Claude Code looks for this file name.

You can add an AGENTS.md to the repository of your extension in the same way. See Instructions for AI assistants for an example.

Skills for TYPO3 documentation 

This guide provides two skills in the folder skills/ of its repository:

typo3-docs-writing
Makes the assistant read the rules of this guide for the content that it is about to write. The skill names the page and the anchor for each kind of content. After writing, the assistant checks the result with make test-docs and reads the rendered pages.
typo3-docs-style-check
Checks changed files against the rules of this guide and reports each violation with the rule and a fix. It does not change the files.

The skills do not copy the rules. They read them from the current version of this guide: from a local clone of the guide, or from GitHub if there is none. A change to a rule therefore reaches the skills without an update of the skills.

The skills follow the open Agent Skills format. Every tool that supports this format can use them.

Install the skills in Claude Code 

Run the following commands in Claude Code:

Install the skills as the plugin typo3-docs 
/plugin marketplace add TYPO3-Documentation/TYPO3CMS-Guide-HowToDocument
/plugin install typo3-docs@typo3-docs-guide
Copied!

Claude Code then uses the skill typo3-docs-writing when a task changes reST files of a TYPO3 manual or of an extension. You can also ask for a skill by its name.

Use the skills in other tools 

Each tool reads skills from a folder of its own. See the documentation of your tool for this folder.

  1. Clone the repository of this guide:

    git clone https://github.com/TYPO3-Documentation/TYPO3CMS-Guide-HowToDocument.git
    Copied!
  2. Link the folders skills/typo3-docs-writing and skills/typo3-docs-style-check into the skills folder of your tool.

A link instead of a copy keeps the skills up to date when you pull the clone. The skills can also read the rules from this clone.

Let the assistant read the documentation 

An assistant that needs a fact from a TYPO3 manual should read the page, not answer from memory. Give it the permalink of the section. Every page on docs.typo3.org is also published as Markdown, and every manual has an llms.txt that lists its pages. See What a render publishes beside the pages.

Check the result 

Check every change of an assistant before you commit it:

  1. Run make test-docs and fix every warning.
  2. Read the rendered pages that changed. The render does not catch everything, for example a role that runs on into the following text.
  3. Run the skill typo3-docs-style-check on the changed files, or check them against the rules yourself. The render does not check the line length, sentence case, the serial comma, or the wording.
  4. Read the diff once more, see You are responsible for the result.