Pre-computed context
Current branch: !git branch --show-current 2>/dev/null || echo "unknown"
Purpose
A suppression turns a linter or type checker off for one line, one block or one file. Three further
classes switch off the evidence a quality bar rests on, and the scanner lists them the same way:
coverage exclusions (istanbul, c8 and coverage.py), mutation-testing exclusions (Stryker) and
security-scanner suppressions (Bandit, Semgrep and Gitleaks). This skill lists all of them so a reader can see how many there are, which explain themselves, and which switch off
a rule the team counts as correctness rather than style.
It reports and stops: no pass or fail, and the report carries no severity (a --findings file
carries the tier its rule's row sets, below). Whether a suppression should go is the reader's call.
A suppression is justified when its line carries a reason and, for a tool whose syntax can name
a rule, at least one rule id. TypeScript's @ts-ignore, @ts-expect-error and @ts-nocheck
cannot name an error, so a reason alone justifies them. Where a tool has a reason slot of its own,
the text there is the reason (ESLint and RuboCop after --, a Justification argument in C# and
PowerShell); otherwise a further comment on the same line is (a TypeScript directive's trailing
text, a second <!-- --> after a markdownlint directive, a // comment after @SuppressWarnings,
a second # comment after a Python or shell pragma).
Only real comments, pragmas and attributes count. A marker inside a string literal, a Markdown code
span or a fenced code block in a Markdown file is not a suppression.
Run it
"${CLAUDE_SKILL_DIR}/scripts/audit-suppressions.sh" # lines the commits since the merge-base add
"${CLAUDE_SKILL_DIR}/scripts/audit-suppressions.sh" --base release/2.0 # the merge-base with another branch
"${CLAUDE_SKILL_DIR}/scripts/audit-suppressions.sh" --all # every suppression in the tree
"${CLAUDE_SKILL_DIR}/scripts/audit-suppressions.sh" src/ tools/build.sh # explicit paths, whole files
"${CLAUDE_SKILL_DIR}/scripts/audit-suppressions.sh" --json --all # the document instead of markdown
"${CLAUDE_SKILL_DIR}/scripts/audit-suppressions.sh" --findings # the report plus a findings file for /review:fanout fix
The change scope reads committed lines only: a suppression in an uncommitted edit is not in it until
it is committed, so name the file or use --all to see the working tree. scope.exclude and lane
opt-outs apply as in the other audits.
Present the markdown report as printed: the scope, the counts, the correctness list with the layer
that set it, then one row per suppression (correctness rules first, then lines without a reason),
capped at 200 rows with the kept document named for the rest. The --json document
(code-metrics/suppressions/v1) carries scope, counts (suppressions, unjustified,
correctness), correctness_rules (rules, layer) and suppressions, one object per row with
file, line, tool, rules, justified, reason and correctness.
Findings for the review relay (--findings)
--findings runs the same scan in the same scope, prints the same report, then writes one findings
file in the shape /review:fanout fix reads and prints its path. It asks nothing, so a pipeline or
another skill can run it. Bare invocation and --json write no findings file.
- Where it goes.
<memory root>/reviews/<branch-slug>/<UTC stamp>-suppressions.md, the
directory /review:fanout "Shared inputs" names. The memory root is .work under the repository
root; when the project's instructions name another memory root, pass it with --memory-dir. A
memory root with no .gitignore gets one holding *, and the run says so. An existing file is
never overwritten: a second run in the same second takes a -2 suffix.
- No branch, no file. On a detached HEAD or outside a git repository the run stops with exit 2
before scanning and says no findings file was written: the relay reads only a file whose
branch: matches the current branch.
- What becomes a row. A justified suppression is no finding. An unjustified one is a row under
one of two rules:
code-metrics/audit-suppressions/rule-no-reason when the line carries no
reason, and code-metrics/audit-suppressions/rule-no-rule-id when it carries a reason but no rule
id and the tool can name one. Each Finding cell leads with the rule id and what fired (the tool,
its rule ids, and the missing part); Location is the repo-relative file:line. Tier
(IMPORTANT), Confidence (high) and the fact that neither rule is auto-applicable come from
the two rules' rows in the detector-findings convention
(https://raw.githubusercontent.com/melodic-software/claude-code-plugins/main/docs/contracts/detector-findings/README.md,
"The severity crosswalk"), never from the finding. The Action names where this tool keeps its
reason, and asks for a rule id only where the tool can name one and the line names none.
- Coverage.
## Surfaces names the scope and how many suppressions were examined, and counts
each rule's declined candidates by the evidence that declined them: a reason on the line, a rule
id on the line, or a TypeScript directive, which cannot name an error. A run whose scope holds no
file writes no findings file.
Whether a suppression goes or gets its reason is a human's call, so no row is auto-applicable: the
fix pass surfaces the rows rather than applying them.
Correctness rules
suppressions.correctness_rules lists the rule ids whose suppression the team wants to see first,
such as no-floating-promises, SC2086 or CA2000. The plugin ships the list empty, because which
rules guard correctness is the repository's call. Set it in docs/conventions/code-metrics.yaml
(keys in ${CLAUDE_PLUGIN_ROOT}/reference/config.md):
suppressions:
correctness_rules: [no-floating-promises, SC2086, CA2000]
A row is marked when one of its rule ids is listed, compared case-insensitively. A suppression that
names no rule is not matched; for a tool that can name one, it is already unjustified. An invalid
value (a scalar, a number in the list) is named with its file and key, and the key falls back to a
valid higher layer or the empty default; the run continues.
Freezing the count
The scanner behind this skill, scripts/suppression-scan.py, prints the count on its own:
python3 "${CLAUDE_SKILL_DIR}/scripts/suppression-scan.py" --count
# suppressions=<n>
# unjustified=<n>
When /toolchain:ratchet is among the available skills, it can hold that count as a CI ceiling: it
vendors a copy of the scanner into the repository and ratchets the suppressions or unjustified
field. Without it, keep the --json document and compare counts by hand.
The scanner reads no configuration: with no path it scans every tracked and untracked,
not-ignored file in the repository, and suppressions.correctness_rules marks nothing. The caller
passes the audit's resolved scope, so the frozen count and the report count the same files: name
the paths to count and give each scope.exclude glob with --exclude <glob> (repeatable), or
list the globs one per line in a file for --exclude-from <file>:
python3 "${CLAUDE_SKILL_DIR}/scripts/suppression-scan.py" --count \
--exclude 'vendor/' --exclude '**/generated/**' src/ tools/
A glob matches the repository-relative path in the same gitignore dialect scope.exclude uses. With
no --exclude the count is unchanged and includes any path scope.exclude would drop.
Upstream syntax
The marker catalog follows each tool's own directive syntax, read from these pages:
- Pointer: ESLint, disabling rules;
TypeScript 3.9,
@ts-expect-error;
flake8, in-line ignoring;
Ruff, error suppression;
mypy, silencing the checker;
pylint, message control;
Pyright, comments;
ShellCheck, directives;
C# #pragma warning;
.NET, suppressing code analysis warnings;
golangci-lint, false positives;
PSScriptAnalyzer, suppressing rules;
markdownlint, configuration;
RuboCop, source code directives;
Java SuppressWarnings;
istanbul, ignoring code for coverage;
c8, ignoring lines;
coverage.py, excluding code;
Stryker, disable mutants;
Bandit, suppressing individual lines;
Semgrep, ignore code through nosemgrep;
Gitleaks, inline allow.
- As of: 2026-11-03.
- Recheck trigger: a tool on the list adds a suppression form, a reason syntax, or a way to name
a rule; or a team reports a real suppression the report missed.
What this skill does not do
- It does not remove, rewrite or approve a suppression, and it runs no linter.
- It is not the finding-suppression record in
docs/contracts/finding-suppression/, which holds
review findings a team chose to dismiss; this skill reads source comments and attributes.
- It does not judge: no count here is a bar.
/code-metrics:principles explains what each number
in this plugin can and cannot tell you.
Next
- Hold the count in CI so it only falls: /toolchain:ratchet.
- Work through the rows a
--findings run wrote: /review:fanout fix.
- A count needs reading before anyone acts on it: /code-metrics:principles.
Gotchas
- The change scope needs a merge-base with the default branch; outside a git repository, or with no
default-branch ancestor, pass paths or
--all (the usage error says which).
- A multi-line C#, PowerShell or Java attribute is read up to ten lines past its opening line; a
longer one is reported with the rule ids and reason it showed in that span.
- A coverage, Stryker or Gitleaks directive is read only in the comment forms of the languages the
scanner knows; a coverage exclusion kept in a tool's configuration file (a path list, an exclusion
regex) is not reported. Bandit rule ids are read as test ids (
B and digits); a test name after
nosec reads as the reason.
- A tool not on the list (Stylelint, Clippy, SwiftLint) is not reported; nothing in the report says
a file had none of its markers.
- The scanner needs Python 3.11 or later, above the plugin's 3.9 floor; below it the scanner
exits 2 with a one-line message.
- File type comes from the extension, or the shebang for a file without one; a shell script named
*.txt is not read as shell.
1---2name: audit-suppressions3description: "List every lint and type-checker suppression in a change, a path, or the tree (`--all`): eslint-disable, @ts-expect-error, noqa, type: ignore, pylint, pyright, shellcheck disable, C# pragmas and SuppressMessage, nolint, PowerShell SuppressMessageAttribute, markdownlint, rubocop, @SuppressWarnings; and the directives that switch off the evidence a quality bar relies on: coverage exclusions (istanbul, c8, coverage.py), mutation-testing exclusions (Stryker), security-scanner suppressions (bandit nosec, nosemgrep, gitleaks allow). Each row names its rule ids, its reason, and whether it is justified; listed correctness rules are marked. Reports, never gates. Use when: 'how many suppressions', 'find eslint-disable comments', 'which noqa have no reason', 'suppressions added in this change', 'audit lint suppressions', 'count suppressions to ratchet'. Complexity: /code-metrics:audit complexity."4argument-hint: "[--json|--findings [--memory-dir <dir>]] [--all] [--base <ref>] [<path>...]"5user-invocable: true6disable-model-invocation: false7allowed-tools: ["Bash(${CLAUDE_SKILL_DIR}/scripts/audit-suppressions.sh:*)", "Bash(python3 ${CLAUDE_SKILL_DIR}/scripts/suppression-scan.py:*)", "Bash(git branch --show-current:*)"]8shell: bash9metadata:10 source: https://skillmd.com/skills/melodic-software/audit-suppressions11 workflow-stage: anytime12 summary: Suppressions with their rule ids and reasons, no verdict13---1415## Pre-computed context1617Current branch: !`git branch --show-current 2>/dev/null || echo "unknown"`1819## Purpose2021A suppression turns a linter or type checker off for one line, one block or one file. Three further22classes switch off the evidence a quality bar rests on, and the scanner lists them the same way:23coverage exclusions (istanbul, c8 and coverage.py), mutation-testing exclusions (Stryker) and24security-scanner suppressions (Bandit, Semgrep and Gitleaks). This skill lists all of them so a reader can see how many there are, which explain themselves, and which switch off25a rule the team counts as correctness rather than style.26It reports and stops: no pass or fail, and the report carries no severity (a `--findings` file27carries the tier its rule's row sets, below). Whether a suppression should go is the reader's call.2829A suppression is **justified** when its line carries a reason and, for a tool whose syntax can name30a rule, at least one rule id. TypeScript's `@ts-ignore`, `@ts-expect-error` and `@ts-nocheck`31cannot name an error, so a reason alone justifies them. Where a tool has a reason slot of its own,32the text there is the reason (ESLint and RuboCop after `--`, a `Justification` argument in C# and33PowerShell); otherwise a further comment on the same line is (a TypeScript directive's trailing34text, a second `<!-- -->` after a markdownlint directive, a `//` comment after `@SuppressWarnings`,35a second `#` comment after a Python or shell pragma).3637Only real comments, pragmas and attributes count. A marker inside a string literal, a Markdown code38span or a fenced code block in a Markdown file is not a suppression.3940## Run it4142```bash43"${CLAUDE_SKILL_DIR}/scripts/audit-suppressions.sh" # lines the commits since the merge-base add44"${CLAUDE_SKILL_DIR}/scripts/audit-suppressions.sh" --base release/2.0 # the merge-base with another branch45"${CLAUDE_SKILL_DIR}/scripts/audit-suppressions.sh" --all # every suppression in the tree46"${CLAUDE_SKILL_DIR}/scripts/audit-suppressions.sh" src/ tools/build.sh # explicit paths, whole files47"${CLAUDE_SKILL_DIR}/scripts/audit-suppressions.sh" --json --all # the document instead of markdown48"${CLAUDE_SKILL_DIR}/scripts/audit-suppressions.sh" --findings # the report plus a findings file for /review:fanout fix49```5051The change scope reads committed lines only: a suppression in an uncommitted edit is not in it until52it is committed, so name the file or use `--all` to see the working tree. `scope.exclude` and lane53opt-outs apply as in the other audits.5455Present the markdown report as printed: the scope, the counts, the correctness list with the layer56that set it, then one row per suppression (correctness rules first, then lines without a reason),57capped at 200 rows with the kept document named for the rest. The `--json` document58(`code-metrics/suppressions/v1`) carries `scope`, `counts` (`suppressions`, `unjustified`,59`correctness`), `correctness_rules` (`rules`, `layer`) and `suppressions`, one object per row with60`file`, `line`, `tool`, `rules`, `justified`, `reason` and `correctness`.6162## Findings for the review relay (`--findings`)6364`--findings` runs the same scan in the same scope, prints the same report, then writes one findings65file in the shape `/review:fanout fix` reads and prints its path. It asks nothing, so a pipeline or66another skill can run it. Bare invocation and `--json` write no findings file.6768- **Where it goes.** `<memory root>/reviews/<branch-slug>/<UTC stamp>-suppressions.md`, the69 directory `/review:fanout` "Shared inputs" names. The memory root is `.work` under the repository70 root; when the project's instructions name another memory root, pass it with `--memory-dir`. A71 memory root with no `.gitignore` gets one holding `*`, and the run says so. An existing file is72 never overwritten: a second run in the same second takes a `-2` suffix.73- **No branch, no file.** On a detached HEAD or outside a git repository the run stops with exit 274 before scanning and says no findings file was written: the relay reads only a file whose75 `branch:` matches the current branch.76- **What becomes a row.** A justified suppression is no finding. An unjustified one is a row under77 one of two rules: `code-metrics/audit-suppressions/rule-no-reason` when the line carries no78 reason, and `code-metrics/audit-suppressions/rule-no-rule-id` when it carries a reason but no rule79 id and the tool can name one. Each `Finding` cell leads with the rule id and what fired (the tool,80 its rule ids, and the missing part); `Location` is the repo-relative `file:line`. `Tier`81 (`IMPORTANT`), `Confidence` (`high`) and the fact that neither rule is auto-applicable come from82 the two rules' rows in the detector-findings convention83 (<https://raw.githubusercontent.com/melodic-software/claude-code-plugins/main/docs/contracts/detector-findings/README.md>,84 "The severity crosswalk"), never from the finding. The `Action` names where this tool keeps its85 reason, and asks for a rule id only where the tool can name one and the line names none.86- **Coverage.** `## Surfaces` names the scope and how many suppressions were examined, and counts87 each rule's declined candidates by the evidence that declined them: a reason on the line, a rule88 id on the line, or a TypeScript directive, which cannot name an error. A run whose scope holds no89 file writes no findings file.9091Whether a suppression goes or gets its reason is a human's call, so no row is auto-applicable: the92fix pass surfaces the rows rather than applying them.9394## Correctness rules9596`suppressions.correctness_rules` lists the rule ids whose suppression the team wants to see first,97such as `no-floating-promises`, `SC2086` or `CA2000`. The plugin ships the list empty, because which98rules guard correctness is the repository's call. Set it in `docs/conventions/code-metrics.yaml`99(keys in `${CLAUDE_PLUGIN_ROOT}/reference/config.md`):100101```yaml102suppressions:103 correctness_rules: [no-floating-promises, SC2086, CA2000]104```105106A row is marked when one of its rule ids is listed, compared case-insensitively. A suppression that107names no rule is not matched; for a tool that can name one, it is already unjustified. An invalid108value (a scalar, a number in the list) is named with its file and key, and the key falls back to a109valid higher layer or the empty default; the run continues.110111## Freezing the count112113The scanner behind this skill, `scripts/suppression-scan.py`, prints the count on its own:114115```bash116python3 "${CLAUDE_SKILL_DIR}/scripts/suppression-scan.py" --count117# suppressions=<n>118# unjustified=<n>119```120121When `/toolchain:ratchet` is among the available skills, it can hold that count as a CI ceiling: it122vendors a copy of the scanner into the repository and ratchets the `suppressions` or `unjustified`123field. Without it, keep the `--json` document and compare counts by hand.124125The scanner reads no configuration: with no path it scans every tracked and untracked,126not-ignored file in the repository, and `suppressions.correctness_rules` marks nothing. The caller127passes the audit's resolved scope, so the frozen count and the report count the same files: name128the paths to count and give each `scope.exclude` glob with `--exclude <glob>` (repeatable), or129list the globs one per line in a file for `--exclude-from <file>`:130131```bash132python3 "${CLAUDE_SKILL_DIR}/scripts/suppression-scan.py" --count \133 --exclude 'vendor/' --exclude '**/generated/**' src/ tools/134```135136A glob matches the repository-relative path in the same gitignore dialect `scope.exclude` uses. With137no `--exclude` the count is unchanged and includes any path `scope.exclude` would drop.138139## Upstream syntax140141The marker catalog follows each tool's own directive syntax, read from these pages:142143- **Pointer:** [ESLint, disabling rules](https://eslint.org/docs/latest/use/configure/rules#disable-rules);144 [TypeScript 3.9, `@ts-expect-error`](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-9.html);145 [flake8, in-line ignoring](https://flake8.pycqa.org/en/latest/user/violations.html);146 [Ruff, error suppression](https://docs.astral.sh/ruff/linter/#error-suppression);147 [mypy, silencing the checker](https://mypy.readthedocs.io/en/stable/common_issues.html);148 [pylint, message control](https://pylint.readthedocs.io/en/stable/user_guide/messages/message_control.html);149 [Pyright, comments](https://github.com/microsoft/pyright/blob/main/docs/comments.md);150 [ShellCheck, directives](https://www.shellcheck.net/wiki/Directive);151 [C# `#pragma warning`](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/preprocessor-directives);152 [.NET, suppressing code analysis warnings](https://learn.microsoft.com/en-us/dotnet/fundamentals/code-analysis/suppress-warnings);153 [golangci-lint, false positives](https://golangci-lint.run/docs/linters/false-positives/);154 [PSScriptAnalyzer, suppressing rules](https://learn.microsoft.com/en-us/powershell/utility-modules/psscriptanalyzer/using-scriptanalyzer);155 [markdownlint, configuration](https://github.com/DavidAnson/markdownlint#configuration);156 [RuboCop, source code directives](https://docs.rubocop.org/rubocop/latest/usage/source_code_directives.html);157 [Java `SuppressWarnings`](https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/lang/SuppressWarnings.html);158 [istanbul, ignoring code for coverage](https://github.com/istanbuljs/nyc#parsing-hints-ignoring-lines);159 [c8, ignoring lines](https://github.com/bcoe/c8#ignoring-uncovered-lines-functions-and-blocks);160 [coverage.py, excluding code](https://coverage.readthedocs.io/en/latest/excluding.html);161 [Stryker, disable mutants](https://stryker-mutator.io/docs/stryker-js/disable-mutants/);162 [Bandit, suppressing individual lines](https://bandit.readthedocs.io/en/latest/config.html#suppressing-individual-lines);163 [Semgrep, ignore code through `nosemgrep`](https://docs.semgrep.dev/ignoring-files-folders-code);164 [Gitleaks, inline allow](https://github.com/gitleaks/gitleaks#gitleaksallow).165- **As of:** 2026-11-03.166- **Recheck trigger:** a tool on the list adds a suppression form, a reason syntax, or a way to name167 a rule; or a team reports a real suppression the report missed.168169## What this skill does not do170171- It does not remove, rewrite or approve a suppression, and it runs no linter.172- It is not the finding-suppression record in `docs/contracts/finding-suppression/`, which holds173 review findings a team chose to dismiss; this skill reads source comments and attributes.174- It does not judge: no count here is a bar. `/code-metrics:principles` explains what each number175 in this plugin can and cannot tell you.176177## Next178179- Hold the count in CI so it only falls: /toolchain:ratchet.180- Work through the rows a `--findings` run wrote: /review:fanout fix.181- A count needs reading before anyone acts on it: /code-metrics:principles.182183## Gotchas184185- The change scope needs a merge-base with the default branch; outside a git repository, or with no186 default-branch ancestor, pass paths or `--all` (the usage error says which).187- A multi-line C#, PowerShell or Java attribute is read up to ten lines past its opening line; a188 longer one is reported with the rule ids and reason it showed in that span.189- A coverage, Stryker or Gitleaks directive is read only in the comment forms of the languages the190 scanner knows; a coverage exclusion kept in a tool's configuration file (a path list, an exclusion191 regex) is not reported. Bandit rule ids are read as test ids (`B` and digits); a test name after192 `nosec` reads as the reason.193- A tool not on the list (Stylelint, Clippy, SwiftLint) is not reported; nothing in the report says194 a file had none of its markers.195- The scanner needs Python 3.11 or later, above the plugin's 3.9 floor; below it the scanner196 exits 2 with a one-line message.197- File type comes from the extension, or the shebang for a file without one; a shell script named198 `*.txt` is not read as shell.