How do I install the Bench Rule Enable skill?

Run npx skillmds@latest add markuplint/bench-rule-enable in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Bench Rule Enable safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Bench Rule Enable?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Bench Rule Enable free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Bench Rule Enable?

markuplint (@markuplint) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Bench Rule Enable by markuplint — Agent Skill

Name: Bench Rule Enable
Author: markuplint

Bench Rule Enable

Enable an existing or newly-added markuplint rule on the nu-validator bench by editing tests/external/bench/config.ts. Covers the flat-rule case (rules: { '<name>': true }) and the severity override case (rules: { '<name>': { severity: 'error' } }) that bench-virtual-rule does not. Use when a rule exists in the registry but the relevant nu fixtures stay nu-only because the rule is not enabled in the bench config, or when a rule's default severity is warning but the spec text it mirrors is a MUST / MUST NOT. Trigger keywords: enable bench rule, bench config flat rule, severity override bench, rule not flagging on bench, warning vs error in bench, escalate severity bench, no-contradictory-aria-prop bench, bench coverage missing rule.

markuplint db72b49 4.4 KB Updated Sep 17, 2026

File contents

Bench Rule Enable Skill

tests/external/bench/config.ts curates rules explicitly (no extends: ['markuplint:html-standard']). A rule that exists in the markuplint registry will not affect bench verdicts until it is added to that file. This skill covers the two non-virtual-rule patterns:

Flat enable: adding '<rule-name>': true for a rule whose default behaviour matches the bench's spec-conformance lens.
Severity override: adding '<rule-name>': { severity: 'error' } for a rule whose default severity is 'warning' but whose underlying assertion is a MUST / MUST NOT in the spec text.

For preset-defined virtual rules (nodeRules[] selectors), use bench-virtual-rule instead.

When to add a rule to the bench

The bench is the spec-conformance comparison surface. A rule belongs in bench/config.ts only when its assertions map onto a nu-validator capability. Use this checklist:

The rule is registered in packages/@markuplint/rules/src/index.ts.
The rule reports diagnostics with severity 'error' (or you intend to override severity — see the next section).
Either:
- nu-validator currently fires on the same markup pattern, OR
- the spec the rule cites contains MUST / MUST NOT language and the discrepancy in nu's coverage is documented in bench-triage's audit log.

If both nu and the spec are silent, do not enable the rule in the bench — it would inflate ml-only without producing a spec-aligned signal.

Pattern 1: flat enable

Most new conformance rules ship as flat enable: add '<rule-name>': true to rules in tests/external/bench/config.ts (entries kept alphabetical). After editing:

yarn build --scope @markuplint/rules
yarn bench:update --target markuplint --filter '<bench fixture path>'

Expect the targeted fixtures to flip from nu-only to match-error. If a fixture stays nu-only, the rule is not matching that specific HTML (re-read the rule and the fixture).

Pattern 2: severity override

A rule whose default meta.defaultSeverity is 'warning' does not contribute to bench verdicts (see compare.ts#judgeMlState — only errors flip ml state). Override for the bench-only run by adding '<rule-name>': { severity: 'error' } to bench/config.ts.

The inline comment on the override must include:

The spec citation that justifies treating the rule as error
A reason why the user-facing default stays at 'warning' (so the next maintainer does not "harmonise" by raising the user-facing default unconditionally)

Side-effect check

Severity overrides have ripple effects: fixtures that previously were match-clean (both clean) may flip to ml-only (ml strict, nu lax). This is not a regression when:

The spec the rule cites is a MUST / MUST NOT, and
The fixture's filename includes -haswarn (nu fires only a warning, not an error)

Confirm by inspecting tests/external/snapshots/diff/markuplint-only.json after the bench run: filter entries[] to those whose ruleIds include the rule.

Each affected fixture should be a legitimate "ml strict, nu lax" case per the bench-triage SKILL ml-only readings. Anything else is a real over-detection — back out the severity override.

Verification

yarn bench:update --target markuplint
yarn bench:compare

Compare tests/external/snapshots/diff/summary.md:

Per-category match-error count for the rule's domain should rise
nu-only count should fall by the same amount (within nu-validator parallel-load flicker)
ml-only delta should match the side-effect analysis above

Pin against --concurrency 1 before filing for a stable verdict.

---name: bench-rule-enabledescription: Enable an existing or newly-added markuplint rule on the nu-validator bench by editing tests/external/bench/config.ts. Covers the flat-rule case (rules: { '<name>': true }) and the severity override case (rules: { '<name>': { severity: 'error' } }) that bench-virtual-rule does not. Use when a rule exists in the registry but the relevant nu fixtures stay nu-only because the rule is not enabled in the bench config, or when a rule's default severity is warning but the spec text it mirrors is a MUST / MUST NOT. Trigger keywords: enable bench rule, bench config flat rule, severity override bench, rule not flagging on bench, warning vs error in bench, escalate severity bench, no-contradictory-aria-prop bench, bench coverage missing rule.---# Bench Rule Enable Skill`tests/external/bench/config.ts` curates rules explicitly (no`extends: ['markuplint:html-standard']`). A rule that exists in themarkuplint registry will not affect bench verdicts until it is addedto that file. This skill covers the two non-virtual-rule patterns:- **Flat enable**: adding `'<rule-name>': true` for a rule whose default behaviour matches the bench's spec-conformance lens.- **Severity override**: adding `'<rule-name>': { severity: 'error' }` for a rule whose default severity is `'warning'` but whose underlying assertion is a MUST / MUST NOT in the spec text.For preset-defined virtual rules (`nodeRules[]` selectors), use`bench-virtual-rule` instead.## When to add a rule to the benchThe bench is the spec-conformance comparison surface. A rule belongsin `bench/config.ts` only when its assertions map onto anu-validator capability. Use this checklist:1. The rule is registered in `packages/@markuplint/rules/src/index.ts`.2. The rule reports diagnostics with severity `'error'` (or you intend to override severity — see the next section).3. Either: - nu-validator currently fires on the same markup pattern, OR - the spec the rule cites contains MUST / MUST NOT language and the discrepancy in nu's coverage is documented in `bench-triage`'s audit log.If both nu and the spec are silent, do **not** enable the rule inthe bench — it would inflate `ml-only` without producing aspec-aligned signal.## Pattern 1: flat enableMost new conformance rules ship as flat enable: add`'<rule-name>': true` to `rules` in `tests/external/bench/config.ts`(entries kept alphabetical). After editing:```shyarn build --scope @markuplint/rulesyarn bench:update --target markuplint --filter '<bench fixture path>'```Expect the targeted fixtures to flip from `nu-only` to`match-error`. If a fixture stays `nu-only`, the rule is notmatching that specific HTML (re-read the rule and the fixture).## Pattern 2: severity overrideA rule whose default `meta.defaultSeverity` is `'warning'` does notcontribute to bench verdicts (see `compare.ts#judgeMlState` — onlyerrors flip ml state). Override for the bench-only run by adding`'<rule-name>': { severity: 'error' }` to `bench/config.ts`.The inline comment on the override must include:- The spec citation that justifies treating the rule as error- A reason why the user-facing default stays at `'warning'` (so the next maintainer does not "harmonise" by raising the user-facing default unconditionally)## Side-effect checkSeverity overrides have ripple effects: fixtures that previouslywere `match-clean` (both clean) may flip to `ml-only` (ml strict, nulax). This is **not a regression** when:- The spec the rule cites is a MUST / MUST NOT, and- The fixture's filename includes `-haswarn` (nu fires only a warning, not an error)Confirm by inspecting`tests/external/snapshots/diff/markuplint-only.json` after the benchrun: filter `entries[]` to those whose `ruleIds` include the rule.Each affected fixture should be a legitimate "ml strict, nu lax"case per the bench-triage SKILL ml-only readings. Anything else is areal over-detection — back out the severity override.## Verification```shyarn bench:update --target markuplintyarn bench:compare```Compare `tests/external/snapshots/diff/summary.md`:- Per-category match-error count for the rule's domain should rise- nu-only count should fall by the same amount (within nu-validator parallel-load flicker)- ml-only delta should match the side-effect analysis abovePin against `--concurrency 1` before filing for a stable verdict.

Frequently asked questions