content-inline-tool-examples

Detect consecutive code-block examples that all invoke the same tool

Severity	info (disabled)
Autofix	-
Since	v0.19.0
Category	Content Intelligence

Why

Modern context engineering recommends prioritizing clear interface definitions over repetitive example-driven prompting. A wall of near-identical example invocations consumes context tokens and implicitly over-constrains model exploration; a clear description of the tool's parameters, types, and constraints covers the full capability space in far fewer tokens.

The rule looks at fenced (and indented) code blocks whose content is call-syntax invocations of a single tool or function — search(...), client.messages.create(...) — and flags a run of min-consecutive or more adjacent blocks that all invoke the same callee. Usually the calls differ only in their arguments; byte-identical example blocks are also flagged, with the message saying the invocation repeats. Blocks separated by a heading, or by more than max-lines-between non-blank prose lines (caption lines like "Another example:" don't break the run; HTML comments aren't counted), are not considered adjacent. Fences containing ordinary code — imports, control flow, calls to more than one function — never participate.

The rule is opt-in: tutorial-style skills legitimately walk through usage examples, and only the author knows whether a file is a tutorial or an interface reference.

Examples

Bad (three examples, one tool, only the arguments change):

## Using the search tool

When you need to find a symbol, use the search tool. For example:

    search(query="TransferFunds", type="symbol")

Another example, searching for a file:

    search(query="ledger.go", type="file")

A third example, searching text:

    search(query="fixed-point", type="text")

Good (one description of the interface):

## Using the search tool

Search with `search(query, type)` — `type` is one of `symbol`, `file`,
or `text`. Queries are literal strings, not regexes.

How to fix

1. Replace the run of examples with a description of the tool's interface: parameter names, accepted values or types, and any constraints ("queries are literal, not regex").
2. Keep at most one example if the calling convention is genuinely non-obvious — one is enough to show the syntax.
3. If the file is a tutorial that deliberately walks through several invocations, leave it as is — this rule is opt-in precisely because that style is sometimes the point.

Tune the rule in .skillsaw.yaml:

rules:
  content-inline-tool-examples:
    enabled: true
    min-consecutive: 3    # flag runs of 3+ same-tool example blocks
    max-lines-between: 2  # prose lines allowed between blocks in a run

Configuration

rules:
  content-inline-tool-examples:
    enabled: false  # true | false | auto
    severity: info

Parameter	Description	Default
min-consecutive	Minimum number of consecutive code blocks invoking the same tool or function before the run is flagged	3
max-lines-between	Maximum number of non-blank prose lines allowed between two adjacent code blocks (caption lines like 'Another example:') before the run is considered broken; a heading always breaks the run, and HTML comments are not counted	2

Run skillsaw explain content-inline-tool-examples to see this documentation and the rule's effective configuration in your terminal.