README

Natural German technical register for Jira comments and descriptions, internal German-language wiki/spec pages, and team-chat messages to German-speaking colleagues.

Catches literal English→German anglicisms (brechen, gefangen, returnen, triggern, failen) and substitutes the canonical technical lexicon (werfen, abfangen, zurückgeben, auslösen, fehlschlagen) while accepting ecosystem-standard Denglisch loanwords (der Commit, die Pipeline, die Exception).

🔌 Compatibility

This is an Agent Skill following the open standard originally developed by Anthropic and released for cross-platform use.

Supported Platforms:

✅ Claude Code (Anthropic)
✅ Cursor
✅ GitHub Copilot
✅ Other skills-compatible AI agents

Skills are portable packages of procedural knowledge that work across any AI agent supporting the Agent Skills specification.

Features

Anti-pattern detection: ~60 false-friends catalogued — brechen, gefangen, returnen, failen, triggern, hitten, plus calqued idioms (am Ende des Tages, Low-hanging Fruit) and pseudo-anglicisms (Handy, Beamer)
Technical lexicon: preferred German forms with gender for Exceptions, Tests, Git, CI/CD, HTTP, Frontend, Data, and Architecture domains
Register enforcement: Präsens-Indikativ default, impersonal voice, no first-person in artifacts, sentence-length and compound-noun rules
Artifact-specific conventions: Jira ticket descriptions, Jira comments, internal German wiki/spec pages
Comprehension over brevity: unambiguous references instead of siehe oben, conditions and exceptions kept while shortening, sentence structure checked rather than words counted
Worked examples: 8 paired bad-vs-good cases with annotations

Installation

Marketplace (Recommended)

Add the Netresearch marketplace once, then browse and install skills:

# Claude Code
/plugin marketplace add netresearch/claude-code-marketplace
/plugin install german-technical-writing@netresearch-claude-code-marketplace

Without a marketplace

Since Claude Code 2.1.157 a plugin directory under your personal skills directory loads on its own:

mkdir -p ~/.claude/skills
git clone https://github.com/netresearch/german-technical-writing-skill.git \
  ~/.claude/skills/german-technical-writing

It loads as german-technical-writing@skills-dir on the next session. Update with git -C ~/.claude/skills/german-technical-writing pull and start a new session; remove it by deleting the directory. This route has no claude plugin update.

npx (skills.sh)

Install with any Agent Skills-compatible agent:

npx skills add https://github.com/netresearch/german-technical-writing-skill --skill german-technical-writing

Download Release

Download the latest release and extract to your agent's skills directory.

Git Clone

git clone https://github.com/netresearch/german-technical-writing-skill.git

Composer (PHP Projects)

composer require netresearch/german-technical-writing-skill

Requires netresearch/composer-agent-skill-plugin.

npm (Node Projects)

npm install --save-dev \
  @netresearch/agent-skill-coordinator \
  github:netresearch/german-technical-writing-skill

Requires @netresearch/agent-skill-coordinator, which discovers the skill in node_modules and registers it in AGENTS.md via a postinstall hook. For pnpm, also allowlist the coordinator's postinstall:

{
  "pnpm": {
    "onlyBuiltDependencies": ["@netresearch/agent-skill-coordinator"]
  }
}

Usage

The skill triggers automatically when composing German prose longer than one sentence for a German-audience artifact — Jira tickets and comments, internal German wiki/spec pages, or team-chat messages to German-speaking colleagues.

Example queries:

"schreib bitte einen Jira-Kommentar auf OROSPD-692: der cart-merge-on-login Test failt weil ..."
"HMKG-2202 ticket beschreibung muss neu geschrieben werden — problem/ziel format auf deutsch"
"kurze Slack-Ankündigung ans HMKG team auf deutsch: Pipeline CI-383 ist grün"
"drei-satz blurb auf deutsch fürs internal-wiki über das MeyerBaselineBundle"

The skill does not trigger for commit messages, MR/PR descriptions, release notes (all English at Netresearch and most agencies delivering customer projects), conversational chat replies, single-word acknowledgements, or English artifacts that happen to contain German identifiers.

Structure

skills/german-technical-writing/
├── SKILL.md              # Trigger description, process, top-anti-pattern table
├── references/
│   ├── anti-patterns.md            # ~60 false-friends catalogue with explanations
│   ├── lexicon.md                  # Technical term lexicon with gender
│   ├── register.md                 # Tense/voice/person, artifact conventions
│   ├── typografie-rhythmus.md      # Typography and the AI-rhythm tells
│   ├── cognitive-accessibility.md  # Comprehension priority over brevity
│   ├── no-editorializing.md        # Inform, don't sell
│   └── examples.md                 # 8 paired cases with annotations (Case 8 synthetic)
└── evals/
    └── evals.json                  # 29 evals; newer entries carry self-check samples

Contributing

Issues and pull requests welcome at https://github.com/netresearch/german-technical-writing-skill/issues.

When proposing new anti-pattern entries or lexicon additions, please include:

The English concept
The literal-translation form to avoid
The preferred technical German form
A brief explanation of why the literal form reads as anglicism

See skills/german-technical-writing/references/examples.md for the style of explanation we expect.

Tests and checks

The repository ships no executable code: the skill is Markdown prose plus evals/evals.json, and SKILL.md requests only the Read tool. What runs on a change are validators, not a behavioural test suite.

Check	What it verifies	CI workflow
`validate-skill.sh`	SKILL.md front matter and description, layout of the reference files, README sections and install targets	`lint.yml` (Skill Validation)
markdownlint, yamllint, actionlint, JSON syntax, version parity	File syntax; the version in `plugin.json`, `.claude-plugin/plugin.json` and SKILL.md `metadata.version` agrees	`lint.yml` (Skill Validation)
`validate-evals.sh`	Structure of every eval in `evals/evals.json`; for evals that carry `samples`, each assertion is run against `samples.passing` (must be accepted) and `samples.failing` (each failing sample must be rejected by at least one assertion)	`eval-validate.yml` (Eval Validation)
AGENTS.md checks	AGENTS.md exists, has at most 150 lines, and every relative link in it points to an existing file (external links are not checked)	`harness-verify.yml` (Harness Verification)

All four run on pull requests; Harness Verification runs only for pull requests to main. The validators come from netresearch/skill-repo-skill at main.

Run them locally:

pre-commit install --install-hooks   # once; most Skill Validation checks, markdownlint on every *.md (CI: root files only)
pre-commit run --all-files

git clone https://github.com/netresearch/skill-repo-skill.git /tmp/skill-repo-skill
bash /tmp/skill-repo-skill/skills/skill-repo/scripts/validate-skill.sh .
bash /tmp/skill-repo-skill/skills/skill-repo/scripts/validate-evals.sh skills/german-technical-writing/evals/evals.json

validate-evals.sh prints one PASS:, WARN: or FAIL: line per check (plus INFO: context lines) and ends with Results: N passed, N failed, N warnings; it exits non-zero when any line is FAIL:. A FAIL: naming a sample points at the sample or the assertions, for example: an assertion does not accept the passing answer, a failing sample satisfies every assertion (the assertions are too permissive), or a sample is empty or malformed. validate-skill.sh prints ERROR:, WARNING: and OK: lines, ends with an Errors: and a Warnings: count, and exits non-zero on errors only.

A new eval, or an eval whose assertions change, needs samples.passing: in pull requests the validator compares against the copy on main and fails such an eval without it, unless none of its assertions has a pattern the validator can run. Add samples.failing answers as well; the validator checks them when they are present. See AGENTS.md for what each kind of contribution must contain.

Governance and policies

This repository follows the Netresearch organisation policies:

Governance: who owns and maintains the project, the roles, how decisions and disputes are settled.
Roadmap: planned and excluded work for the coming year.
Handling of dependency and code analysis findings: thresholds, deadlines and exceptions for dependency and static-analysis findings.
Secret management: how CI and release credentials are stored, accessed and rotated.
Access roster: the people and teams with admin, maintain and write access to this repository.

Checks that run on pull requests here: Skill Validation (lint.yml) and Eval Validation (eval-validate.yml) on every pull request; for pull requests to main also Betterleaks secret scanning, zizmor workflow analysis, dependency review, Composer Audit with an Opengrep static-analysis scan (all security.yml), Harness Verification (harness-verify.yml) and Template Drift (check-template-drift.yml).

The security assurance case (requirements, trust boundaries, threats and countermeasures, limits) is in docs/SECURITY-ASSURANCE.md.

License

Code (composer.json, plugin.json, configs): MIT
Prose (SKILL.md, references, README): CC-BY-SA-4.0

netresearch / german-technical-writing-skill

Package info

Security

Statistics