{"id":66,"date":"2026-10-18T09:00:00","date_gmt":"2026-10-18T07:00:00","guid":{"rendered":"https:\/\/hoja.in\/blog\/writing-a-claude-code-skill-for-your-typo3-coding-rules\/"},"modified":"2026-10-16T14:00:12","modified_gmt":"2026-10-16T12:00:12","slug":"writing-a-claude-code-skill-for-your-typo3-coding-rules","status":"publish","type":"post","link":"https:\/\/hoja.in\/blog\/writing-a-claude-code-skill-for-your-typo3-coding-rules\/","title":{"rendered":"Writing a Claude Code skill for your TYPO3 coding rules"},"content":{"rendered":"

Before I used skills, my prompts to Claude Code kept starting with the same paragraph. “Use ConnectionPool, not raw SQL. Use dependency injection, not makeInstance<\/code> for services. Site sets, not static includes. PHP 8.2.” Copy, paste, every time. And when the paragraph is missing, you can easily get a ViewHelper with renderStatic()<\/code>, which was deprecated in TYPO3 13.3, because a lot of older example code still uses it.<\/p>\n

Skills fix this. A skill is a folder with a SKILL.md<\/code> file that Claude Code loads when the task matches its description. Your rules are there when they are needed, and they cost almost nothing when they are not. This post builds one for TYPO3 conventions.<\/p>\n

How a skill is loaded<\/h2>\n

Understanding this one thing makes the rest easy. Claude Code keeps only the name and description<\/strong> of every available skill in its context. The body of SKILL.md<\/code> is loaded when the skill is invoked, either by Claude because the task matches the description, or by you with \/skill-name<\/code>. Additional files in the folder are read only when the body points to them and the task needs them.<\/p>\n

So the description decides whether<\/em> the skill is used, the body decides how<\/em>, and the reference files hold the details. Three layers, three different jobs.<\/p>\n

Step 1: Create the folder<\/h2>\n

Project skills live in .claude\/skills\/<name>\/SKILL.md<\/code> and can be committed, so the whole team gets them. Personal skills live in ~\/.claude\/skills\/<\/code>.<\/p>\n

.claude\/skills\/typo3-rules\/\n\u251c\u2500\u2500 SKILL.md\n\u2514\u2500\u2500 references\/\n    \u251c\u2500\u2500 viewhelpers.md\n    \u251c\u2500\u2500 database.md\n    \u2514\u2500\u2500 site-sets.md<\/code><\/pre>\n
Step 2: Write a description that triggers<\/h2>\n
A description like “TYPO3 coding standards” sounds right but rarely triggers. The model does not ask itself “do I need coding standards now?” when somebody says “add a ViewHelper that formats a price”. The description must say what<\/strong> the skill does and when<\/strong> to use it, in words that appear in real requests.<\/p>\n
---\nname: typo3-rules\ndescription: Project rules for writing TYPO3 v14 extension and site package code (PHP, Fluid, TypoScript, TCA, Services.yaml, site sets). Use whenever you create or change a controller, ViewHelper, repository, event listener, middleware, command, TCA file or TypoScript in this project, even for small edits.\n---<\/code><\/pre>\n
Notice the list of concrete things: controller, ViewHelper, repository. Those are the nouns people type. The docs also say to put the key use case first, because a long description is cut in the skill listing.<\/p>\n
Step 3: Keep the rules short<\/h2>\n
The body is not a TYPO3 tutorial. The model knows TYPO3. It needs to know your<\/em> choices and the places where its training data is older than your project. Mine fits on one screen:<\/p>\n
# TYPO3 rules for this project\n\nTarget: TYPO3 14.3, PHP 8.2+, Composer mode, DDEV.\n\n## Always\n- Constructor injection with `private readonly`; no `GeneralUtility::makeInstance()`\n  for services that the container can inject.\n- Database access through `ConnectionPool` \/ QueryBuilder with named parameters.\n- Event listeners with `#[AsEventListener]`, not Services.yaml tags.\n- TypoScript and TSconfig belong in the site set `Configuration\/Sets\/Sitepackage\/`.\n- `declare(strict_types=1);` and native return types everywhere.\n\n## Never\n- `$GLOBALS['TSFE']` (removed in v14). Read request attributes instead.\n- `renderStatic()` in ViewHelpers (deprecated 13.3). Implement `render()`.\n- New hooks in `$GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']` when a PSR-14 event exists.\n\n## Before you say done\n- Run `ddev composer gate` and show its output.\n\n## Details, read when relevant\n- ViewHelpers: [references\/viewhelpers.md](references\/viewhelpers.md)\n- Database and Extbase: [references\/database.md](references\/database.md)\n- Site sets and settings: [references\/site-sets.md](references\/site-sets.md)<\/code><\/pre>\n
“Always” and “Never” lists work better for me than long prose. Each line is something I have really corrected in AI output before. If a rule never needed a correction, it does not go in.<\/p>\n
Step 4: Reference files for the details<\/h2>\n
Details that matter only for one kind of task go into separate files. Here is a part of references\/viewhelpers.md<\/code>:<\/p>\n
# ViewHelpers (TYPO3 14, Fluid 5)\n\n- Extend `TYPO3FluidFluidCoreViewHelperAbstractViewHelper`\n  (or `AbstractTagBasedViewHelper` for HTML tags).\n- Register arguments in `initializeArguments(): void`; Fluid 5 validates types strictly.\n- Declare the return type of `render()`.\n- Need the request? `$this->renderingContext->getAttribute(ServerRequestInterface::class)`,\n  check `hasAttribute()` first. `getRequest()` does not exist any more.\n- Output is escaped by default. Set `$escapeOutput = false` only for trusted HTML and\n  say why in a comment.\n- Add a functional or unit test next to it.<\/code><\/pre>\n
Every line here has a source I can point to: the Fluid 5 breaking change entries in the TYPO3 changelog and the deprecation of RenderingContext::getRequest()<\/code>. When a rule changes with the next TYPO3 version, I change one file.<\/p>\n
Step 5: Test it on a real task<\/h2>\n
A skill that does not trigger is just a Markdown file. So I test it in a fresh session, with a request that does not<\/em> mention the skill:<\/p>\n
Add a ViewHelper my:price that formats an integer amount in cent as a price\nin the current site language, e.g. 1999 -> \"19,99 \u20ac\" for German.<\/code><\/pre>\n
What I check, in this order:<\/p>\n
    \n
  1. Did the skill load?<\/strong> Claude Code shows when a skill is used. If it did not load, the description is the problem, not the rules.<\/li>\n
  2. Did it open the right reference file?<\/strong> For this task viewhelpers.md<\/code> should be read, database.md<\/code> not.<\/li>\n
  3. Is the code following the rules?<\/strong> render(): string<\/code>, typed arguments, the language read from the request attribute, no renderStatic()<\/code>.<\/li>\n
  4. Did it run the gate<\/strong> and show the output before saying it is finished?<\/li>\n<\/ol>\n
    When one of these fails, I change one thing and run the same request again. Most of the time the description is the problem. Sometimes a rule is ambiguous: “avoid makeInstance” alone does not say what to do with a value object, where new<\/code> or makeInstance()<\/code> is perfectly fine. That is why my rule says “for services that the container can inject”.<\/p>\n
    You can also call the skill by hand with \/typo3-rules<\/code> at the start of a message. That is useful when you want it for sure, but I treat it as a fallback. A good description should make it unnecessary.<\/p>\n
    Mistakes to avoid<\/h2>\n