Plugin & skill authoring standards

Read this before writing or editing a SKILL.md or agent file anywhere under plugins/.

Craft vs. content

This doc is opinionated about how a skill/agent is built (frontmatter shape, progressive disclosure, writing voice, structure, wiring) and deliberately agnostic about what any given skill's output should contain (the sections a report/rule-card should have, the domain vocabulary — that's the author's per-plugin call, made with real evidence, not a fixed template imposed from here).

That split, and most of the rules in references/craft-standards.md, are adapted from Wirasm/prp's prp-meta-skill — a real, dispatchable skill for authoring/refactoring skills that ships inside the prp-core plugin already installed in this Claude Code session (pinned to commit 11427384c7609227f20c1d57e6c39de47ccf73c5 — see references/output-shape-findings.md §2e for how that identity was confirmed). The dispatchable form of these standards is the nacharbeit plugin: its rubric turns the rules below into script-checked and model-judged rules over seven surfaces (run plugins/nacharbeit/scripts/nacharbeit_lint.py --count for the current split), and its fix pass applies the tiers a model can apply. This document stays the craft rationale behind that rubric, restructured to match prp-meta-skill's anatomy (a lean entry point + references/) rather than one long flat file, because a flat file is exactly the "prose instead of structure" pattern the craft rules below argue against.

Resources

• references/craft-standards.md — the universal rules (skill types, anatomy, frontmatter spec, progressive disclosure, writing voice, no-duplication, structure-implies-a-maintainer, wiring references, portability), each checked against what werkstoff's thirteen plugins actually do today, not assumed. Read this before starting any new skill/agent, or when something about an existing one feels off and you're not sure why.
• references/output-shape-findings.md — the content-side case study: a comparative audit against anthropics/skills, anthropics/claude-plugins-official, obra/superpowers, and Wirasm/prp, grounding one specific, now-largely-fixed finding (werkstoff describes output shape in prose instead of showing it) with real file citations on both sides. Read this when you want the evidence behind a craft-standards.md rule, or when deciding whether a new skill/agent needs a fenced output example.
• plugins/nacharbeit/references/rubric.md — the frozen rule set nacharbeit grades every skill, agent, command, workflow prompt, hook, script, viewer, manifest, README and docs page against: the mechanical rules a sabotage-tested linter enforces, the judgement rules a calibrated finder applies (run plugins/nacharbeit/scripts/nacharbeit_lint.py --count for the current totals), and the settled answers to the seven places the official and third-party sources disagree. Read this before arguing about a finding in docs/prompt-quality-findings.md, and change it (not the finder) when a rule is wrong.
• references/report-viewer-standard.md — the rules for the 16 self-contained HTML reports (one per plugin, two for matrize, arbeitsplan and cupertino) under plugins/*/assets/*-viewer.html: state the verdict in words, never print a number twice, an actionable number must not look inert, colour is never the only channel, height derives from content — plus the required <head>, the three legitimate page archetypes, and how a screenshot and its demo data get committed so the image is reproducible. Read this before editing any viewer or its build_*_html.py.
• tools/report-kit/ (its README.md in the repo) — the shared report components (CSS, JS, a Python renderer and a worked example) vendored into every plugin through .rrt.toml's artifact_targets. A viewer starts from the kit rather than from scratch; A-REPORT-KIT in the rubric flags a half-finished migration. The content tier (R6–R8) in report-viewer-standard.md is what the kit's evidence, filters, search and deep links exist to satisfy.
• references/design-tokens.md — the corporate design usage rules scripts/ci/check_design_tokens.py enforces over the docs theme and every viewer: no literal hex/color-function/font-family/radius where a token exists, a shrink-only baseline, and how the source chain runs from tools/design-tokens/tokens.css through the vendored copies to the DTCG file matrize derives from it. Read this before adding a colour, font, or radius anywhere the check covers.
• references/judge-contract.md — the one LLM-as-judge contract every plugin follows when a model, not a command, has to decide: command first, one rubric judge per item scored 0.0-1.0 per criterion with a stated threshold, abstain never a pass, calibration against a sealed known-answer set, and a spot-check sample shown to the user each run. Also maps the existing tribunals and panels onto it, or records them as kept-unmeasured. Read this before adding or changing any model-judged step; the vendored copies are held by scripts/ci/check_judge_contract.py.
• references/judge-calibration.md — how three kept judges (arbeitsplan's candidate-referee, matrize's decode-referee, andon's tribunal) were measured against command-derived known answers. It covers the tune and sealed sets, a record whose agreement is the weakest of six figures (precision included), the results and how little a perfect n=10 proves, and the three paired measurements of the tribunal against a single contract judge, with their key and instrument errata. Read it before calibrating any other judge.

The headline finding

werkstoff's skills and agents are strong on enforcement prose (MUST/refuse language, gates, validators) but were weak on showing the shape of the output — describing a schema in a sentence instead of showing a worked, fenced instance. That gap is now closed for every befund and zeugnis auditor agent (see output-shape-findings.md §4.2) and partially closed structurally for befund-extract-rules (a three-file schema/example/report split, §4.6). What's still open, and the general rules to apply when extending any of the thirteen plugins, live in craft-standards.md.