SKILL.md Lint by Moltline

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare read-only, idempotent, non-destructive behavior, but the description adds important error semantics: it never raises a protocol error and returns an error object with corrective guidance. It also describes the success response shape and issue reporting, going beyond the annotation metadata.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the purpose and example output, followed by usage constraints and error behavior. Most sentences carry weight, though the promotional "FREE." is unnecessary and the response example slightly overlaps the output schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has rich annotations, full schema coverage, and an output schema, and the description still fills remaining gaps around unsupported cron variants and error handling. An agent has enough information to invoke it correctly and understand what happens on bad input.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and the schema already documents that the input must be a non-empty standard 5-field cron string. The description reinforces the 5-field assumption and gives an example, but adds little parameter meaning beyond what the schema already provides, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: "Explain a 5-field cron expression in plain English and flag mistakes." It also explicitly excludes 6-field and seconds-precision variants, so an agent can distinguish the scope without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a clear use case: "Use to read a schedule back in plain English before trusting it." It also states the key exclusion: "Assumes 5-field cron; not for 6-field or seconds-precision variants." This covers both when to use it and when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare read-only, idempotent, and non-destructive behavior, but the description adds valuable details beyond them: the 400-line diff cap, the error contract (never raises protocol errors; returns a structured error object), example output shape, and retry safety. These additions help the agent predict behavior and handle failures.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose is front-loaded and the structure is logical. However, 'FREE.' is marketing noise, and the explicit 'read-only and idempotent' sentence redundantly repeats annotation hints, adding slight bloat without new value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple two-parameter diff tool with a rich schema, full annotations, and an output schema, the description covers purpose, usage, return shape, limits, error behavior, and safety. Nothing an agent needs to invoke it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with clear descriptions and maxLength constraints for both parameters. The description gives a typical input example ('a': old text, 'b': new text) but adds no semantic detail beyond what the schema already provides. Baseline 3 is appropriate when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Produce a unified diff between two texts.' It also contextualizes the use case ('comparing two SKILL.md versions') and explicitly distinguishes the tool from risk-judging alternatives. No sibling tool overlaps in function, so the agent can identify it unambiguously.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It states clear when-to-use guidance ('Use to show exactly what changed between two versions of a text') and explicit exclusions ('Not for judging the risk of a code change - the codereview server's review_diff does that'). This routes the agent correctly without inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Adds real behavior beyond annotations: it will not raise a protocol error, it returns a fix-oriented {"error": ...} payload, and retry after correction is safe. That said, "Every call is read-only and idempotent" restates readOnlyHint/idempotentHint verbatim and earns no credit, and the two different error representations ({"valid": false, "error", "line", "column"} vs. {"error"}) are never reconciled.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The lead sentence and the input/output example are well front-loaded, but "FREE." is marketing noise, and the error discussion appears twice with different shapes, forcing the reader to reconcile them. Size is defensible for a validate tool, but the redundancy costs clarity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers input format, success and failure returns, error payloads, and retry safety for a single-parameter tool, and an output schema exists so return values need not have been spelled out. The only real gap is that it never says which error shape applies to which failure class.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3, but the description adds meaning the schema does not: a concrete literal input shown with escaped quotes and the instruction that text must be passed as a raw string. The worked example disambiguates escaping in a way the schema cannot.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("Validate JSON text and summarize its structure") and immediately bounds the scope with "Reports structure, not conformance to a schema." That negatives the most likely misinterpretation and separates it from regex_test and lint_skill without the agent opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

"Use when JSON may be malformed or its shape is unknown" gives a positive trigger, and "Not for testing a pattern (regex_test)" names the sibling to route away to. Both a when-to-use and a when-not-to-use rule are explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered structurally. The description still adds real value: it commits to never raising a protocol error and specifies the exact error envelope shape and an example message, which no annotation conveys. It goes beyond the structured fields, so it earns more than a bare baseline.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the verb and scope, then checks, then return shape, then exclusions and error behavior — logical ordering with no truly wasted sentences. Slight redundancy between the input example and the error example keeps it just short of maximally tight, and the bare 'FREE' fragment adds little.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Return shape is described (though an output schema exists), error behavior on malformed input is spelled out, the input expectation is unambiguous, and the alternative tool is named. Nothing an agent needs in order to call this correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% for the single 'content' parameter, so the schema already documents type, minLength, and requiredness, and the baseline of 3 applies. The description's 'Typical input {"content": "<full SKILL.md text>"}' is a concrete example that confirms the whole-file expectation, a marginal addition on top of the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('lint one SKILL.md file') and enumerates exactly what is checked: frontmatter fields, description quality, body structure, secret leakage, injection phrasing, size budget. It also names the sibling it is not for (packaging_check), so an agent can route without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit scope ('Use on the full text of one SKILL.md') plus an exclusion and the alternative to use instead ('Not for the surrounding archive layout (packaging_check)'). No inference required to pick this tool over its siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly/idempotent/non-destructive/openWorld=false, but the description adds a real contract on top: invalid or missing input never raises a protocol error and instead returns {"error": "<what is wrong and how to fix it>"}, with a worked example. It also states retry is always safe after correction, which directly supports error recovery behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose, then example, then usage and error semantics — good ordering with no filler sentences. It is somewhat long for a two-parameter validator, and the error-handling paragraph repeats the retry point twice, which trims it below maximum efficiency.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers everything an agent needs: what it does, when to use it, what it does not do, the shape of success and failure returns, and cost ('FREE'). With an output schema present, the description need not explain verdict fields further, and it doesn't over-explain them.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds a concrete example input that shows the expected relative-path format ('my-skill/SKILL.md') and a marketplace value, plus the returned skill_files_found echoing matched skill paths. It does not, however, explain the marketplace rule-set tradeoff beyond restating what the schema already documents.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Validate a zip layout plan for a skill marketplace before packaging') with a concrete boundary: it checks layout, not skill content. It explicitly names the sibling it is not (lint_skill), so an agent can separate the two without inspecting schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit timing ('Use on a planned file layout, before zipping') and an explicit exclusion pointing to the alternative ('Not for the content of a skill file (lint_skill)'). Both the when and the when-not are stated, leaving nothing to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the annotations, it discloses execution isolation (short-lived, CPU-capped child process that stops catastrophic backtracking), the error contract (never raises a protocol error, returns {"error": ...} with a concrete example), and retry safety. The only redundancy is restating read-only/idempotent, which the annotations already cover.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose and the sibling exclusion are front-loaded, and the sandbox/error paragraph earns its place. However, the full input/output example is partially redundant given an output schema exists, and the read-only/idempotent sentence repeats the annotations.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Complete for a two-parameter read-only tool: purpose, alternative, sandboxing limits, input caps, and the exact error shape are all covered, and return values are handled by the output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so both parameters are already documented, but the worked example input clarifies how pattern and samples combine in practice. It adds modest value rather than new syntax or format detail.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("Test a regular expression against sample strings") and explicitly names the sibling it is not for (json_validate), so an agent can distinguish it from siblings without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit use case ("confirm a pattern matches what you expect before shipping it") and an explicit exclusion with the alternative tool named ("Not for validating JSON (json_validate)"). Nothing is left to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.