--- title: "Write documentation with AI assistance" manual: "How to Document" version: "main" permalink: "https://docs.typo3.org/permalink/h2document:ai-assistance" source: "Howto/WritingWithAi.rst" rendered: "2026-10-11T13:49:52+00:00" --- # Write documentation with AI assistance {#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](https://docs.typo3.org/permalink/h2document:you-are-responsible-for-the-result) - [The commit message in official documentation](https://docs.typo3.org/permalink/h2document:the-commit-message-in-official-documentation) - [Instructions in the repository](https://docs.typo3.org/permalink/h2document:instructions-in-the-repository) - [Skills for TYPO3 documentation](https://docs.typo3.org/permalink/h2document:skills-for-typo3-documentation) - [Let the assistant read the documentation](https://docs.typo3.org/permalink/h2document:let-the-assistant-read-the-documentation) - [Check the result](https://docs.typo3.org/permalink/h2document:check-the-result) ## You are responsible for the result {#ai-assistance-responsibility} 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](https://docs.typo3.org/permalink/h2document:anchor-persistence). ## The commit message in official documentation {#ai-assistance-commit-message} A change to the official TYPO3 documentation follows the [rules for commit messages](https://docs.typo3.org/permalink/h2document:commit-messages-format), 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: ` 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** ```text [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 Signed-off-by: Jane Doe ``` 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 {#ai-assistance-agents-md} 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](https://docs.typo3.org/permalink/h2document:write-doc-extensions-agents-md) for an example. ## Skills for TYPO3 documentation {#ai-assistance-skills} This guide provides two skills in the folder [skills/](https://github.com/TYPO3-Documentation/TYPO3CMS-Guide-HowToDocument/tree/main/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](https://agentskills.io/) format. Every tool that supports this format can use them. ### Install the skills in Claude Code {#ai-assistance-skills-claude-code} Run the following commands in Claude Code: **Install the skills as the plugin typo3-docs** ```text /plugin marketplace add TYPO3-Documentation/TYPO3CMS-Guide-HowToDocument /plugin install typo3-docs@typo3-docs-guide ``` 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 {#ai-assistance-skills-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: ```bash git clone https://github.com/TYPO3-Documentation/TYPO3CMS-Guide-HowToDocument.git ``` 1. 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 {#ai-assistance-reading} 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](https://docs.typo3.org/permalink/h2document:rendered-artifacts). ## Check the result {#ai-assistance-check} Check every change of an assistant before you commit it: 1. Run `make test-docs` and fix every warning. 1. Read the rendered pages that changed. The render does not catch everything, for example a role that runs on into the following text. 1. 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. 1. Read the diff once more, see [You are responsible for the result](https://docs.typo3.org/permalink/h2document:ai-assistance-responsibility).