SKILL.md Lint

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

The description adds significant behavioral context beyond annotations: it explains error handling ('never raises a protocol error — it returns an error object'), reaffirms idempotency and read-only nature, and provides example output. Annotations already indicate readOnlyHint, idempotentHint, and destructiveHint, but the description enriches understanding.

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 concise (approximately 150 words) and well-structured: purpose first, then example, usage guidance, and error behavior. Every sentence contributes meaning, with no redundancy. The 'FREE' is minor but not distracting.

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?

Given the tool's simplicity (one parameter, clear annotations, output schema exists), the description is complete. It provides example output, error handling details, and usage context, leaving no gaps for an agent to determine how to invoke the tool correctly.

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?

The input schema covers the parameter with a detailed description (100% coverage). The description adds value with an example and clarifies the expected cron variant ('Assumes 5-field cron; not for 6-field or seconds-precision variants'), which informs valid parameter values. This goes beyond the schema baseline of 3.

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 clearly states the tool explains a 5-field cron expression in plain English and flags mistakes. The verb 'explain' and resource 'cron expression' are specific, and the tool is distinct from unrelated siblings.

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?

The description provides explicit usage guidance: 'Use to read a schedule back in plain English before trusting it.' It also clearly states when not to use: 'not for 6-field or seconds-precision variants.' This is sufficient given no similar sibling tools exist.

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. The description reinforces these and adds important behaviors: diff capped at 400 lines, specific error response format without protocol errors, and the retry guarantee. No contradictions.

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 a single coherent paragraph that front-loads the core purpose, then logically covers usage, an example return, limits, alternative tool, and error handling. Every sentence serves a purpose, though it could be slightly more compact without losing information.

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?

With a fully described input schema, an output schema present, detailed annotations, and a description covering behavioral cap, error format, and retry safety, the tool is well-specified. Minor omissions (e.g., what happens if diff exceeds 400 lines) keep it from a 5.

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 for each parameter. The description adds value by providing a typical input example ({'a': '<old text>', 'b': '<new text>'}) and confirming the maxLength constraint, which helps the agent understand usage beyond 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?

The description clearly states 'Produce a unified diff between two texts' with a specific verb and resource. It distinguishes itself from sibling tools (validation utilities) by being a diff tool, and the 'FREE' note adds helpful context. No ambiguity.

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?

Explicitly provides a concrete use case ('comparing two SKILL.md versions') and an explicit exclusion: 'Not for judging the risk of a code change - the codereview server's review_diff does that.' Also explains error handling and retry safety, guiding correct invocation.

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 provide readOnlyHint, idempotentHint, destructiveHint, making basic behavioral profile clear. The description adds valuable detail: explains error handling behavior (never raises protocol error, returns structured error), idempotency ('read-only and idempotent'), and the constraint that it reports structure not conformance. Loses a point because it doesn't disclose the return format beyond the example (e.g., the structure format for deeply nested JSON).

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?

Well-structured with a clear opening sentence, example usage, usage guidance, and error handling details. Slightly verbose with the error example inline, but overall efficient. Could condense the error paragraph slightly.

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?

Given the tool is simple (1 param, read-only, rich annotations), the description is complete enough. It covers purpose, usage, input format, output format, error handling, and safety guarantees. No gaps remain for an agent to select and invoke it correctly.

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 a good description for the single 'text' parameter. The description adds minimal extra meaning beyond the schema — it provides an example of valid input format but does not elaborate on edge cases like whitespace or encoding. Baseline 3 is appropriate as 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 clearly states the tool's purpose: 'Validate JSON text and summarize its structure.' It specifies the resource (JSON text), action (validate and summarize), and differentiates it from siblings like regex_test by mentioning 'Not for testing a pattern.'

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?

Explicitly advises when to use: 'Use when JSON may be malformed or its shape is unknown.' Provides a clear when-not-to-use by saying 'Not for testing a pattern (regex_test).' Also tells the agent what to do on errors: 'after correcting the input it is always safe to retry.'

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=true, idempotentHint=true, and destructiveHint=false. The description adds rich behavioral details: error handling (returns error object, never protocol error), idempotency (safe to retry), and input constraints, going well beyond annotations.

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 core action and additional info, but slightly verbose with example output details that could be shifted to an external doc. Still, every sentence adds value and the structure is clear.

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?

Given the single parameter, rich annotations, and output schema, the description fully covers input, output, error handling, and idempotency. No gaps remain for an agent to misuse this tool.

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 a clear description for content. The description adds value by specifying the input format ('full SKILL.md text'), typical usage example, and what happens with invalid input, which is beyond 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?

The description clearly states it lints one SKILL.md file, lists what it checks (YAML frontmatter, fields, etc.), and distinguishes it from the sibling packaging_check, which is about the archive layout.

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?

Explicitly says 'Use on the full text of one SKILL.md' and 'Not for the surrounding archive layout (packaging_check)', providing a direct alternative and clarifying scope.

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 provide readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description reinforces this by stating 'Every call is read-only and idempotent, so after correcting the input it is always safe to retry.' It also explicitly describes error behavior: 'this tool never raises a protocol error — it returns {"error": ...}'. This adds meaningful context beyond the annotations.

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 moderately long but well-structured: it starts with the main purpose, then gives a typical input/output, followed by usage guidance and error behavior. Each sentence adds distinct information. While not extremely concise, it is efficient given the complexity of the tool.

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 description covers the main use case, error behavior, and return format (verdict, issues, skill_files_found). Given that an output schema exists, the description does not need to duplicate that. It also explains the two marketplace rule sets. Minor gaps (e.g., exact definition of junk files) exist but do not significantly impair completeness.

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 parameters are well-documented already. The description adds value by providing a concrete example ('Typical input {"file_paths": ["my-skill/SKILL.md"], "marketplace": "agensi"}') and clarifying the rules for marketplace values and error handling. This enhances understanding beyond the schema alone.

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 starts with a specific verb and resource: 'Validate a zip layout plan for a skill marketplace before packaging.' It also explicitly distinguishes itself from the sibling 'lint_skill' tool by stating 'Not for the content of a skill file (lint_skill).' This makes the purpose clear and distinct.

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?

The description says 'Use on a planned file layout, before zipping.' It also explicitly states what not to use it for: 'Not for the content of a skill file (lint_skill).' Additionally, it mentions that errors return a helpful message and that the tool is safe to retry, guiding the agent on correct invocation.

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?

The description goes well beyond annotations by providing rich behavioral context: error handling (returns error objects instead of raising protocol errors), return format with full examples, the fact that it is read-only and idempotent (matching but extending annotations), and scope details (only first 50 samples evaluated). There is no contradiction with the annotations.

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 concise and well-structured. It starts with a one-sentence summary, gives a compact example, explains usage context, error behavior, and idempotency. Every sentence serves a purpose (purpose, usage, error handling, safety). No wasted words.

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?

Given the tool's moderate complexity (2 parameters, no nested objects, has output schema), the description is completely comprehensive. It covers inputs, outputs, error handling, usage guidance, and safety. The output schema exists, so return values are detailed there, but the description still provides a full example. Nothing is missing for an agent to correctly select and invoke this tool.

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% and both parameters have descriptions in the schema (pattern with an example, samples with a limit note). The description adds a typical usage example showing how to use them, which reinforces but does not significantly expand beyond schema information. Baseline 3 is appropriate as 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 clearly states it tests a regular expression against sample strings, using the verb 'test' and specifying the resource 'regular expression'. It provides a typical input/output example that leaves no ambiguity about what the tool does, and it distinguishes itself from sibling tools like json_validate by explicitly naming it as something else.

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?

The description gives explicit guidance: 'Use to confirm a pattern matches what you expect before shipping it.' It also tells when not to use it with 'Not for validating JSON (json_validate).' It even explains behavior on errors, stating it never raises a protocol error, which informs the agent how to handle failures.

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