How the Description Field Format Enforces Trigger-Only Usage in Claude Skills

The description field format enforces trigger-only usage by requiring a mandatory "Use when" prefix defined in CLAUDE.md and validated automatically by the DescriptionFormatChecker class in scripts/validate-skills.py, ensuring skills only declare invocation conditions rather than implementation details.

In the Jeffallan/claude-skills repository, the description field format serves as a critical guardrail for skill discovery. This open-source framework employs a rigorous two-layer enforcement system that combines explicit documentation conventions with automated linting to guarantee that every skill's description functions exclusively as a trigger condition.

The "Use When" Convention in CLAUDE.md

The foundation of trigger-only enforcement begins with explicit documentation. According to the project configuration in CLAUDE.md (lines 25-30), every skill's description must adhere to a strict pattern: it must start with "Use when" and exclusively state the conditions that should cause the skill to be invoked.

This convention explicitly forbids including workflow steps, implementation details, or procedural instructions within the description field. By mandating that descriptions only declare when to use a skill rather than how to execute it, the repository maintains a clean separation between trigger logic and execution logic.

Automated Validation with DescriptionFormatChecker

While conventions provide guidance, automated validation ensures compliance. The scripts/validate-skills.py file implements the DescriptionFormatChecker class (lines 25-34), which performs static analysis on every SKILL.md file in the repository.

During the validate-skills execution, the checker extracts the YAML front-matter from each skill file, locates the description field, and verifies that it begins with the required "Use when" prefix. If a skill's description violates this format—such as containing workflow steps instead of trigger conditions—the validator emits a specific warning that identifies the non-conforming skill.

CI Pipeline Fail-Fast Protection

The validation script integrates into the continuous integration pipeline through the project's Release Checklist, creating a fail-fast mechanism that prevents non-compliant skills from reaching production. Because the validate-skills check runs automatically during CI, any skill lacking the proper "Use when" prefix blocks the release process.

This integration ensures that the trigger-only rule cannot be bypassed silently. Developers receive immediate feedback during the build process, enforcing the convention at the point of code integration rather than during manual review.

Correct vs. Incorrect Description Examples

Understanding the enforcement mechanism requires examining valid and invalid implementations. The following examples demonstrate how the DescriptionFormatChecker distinguishes between compliant trigger-only descriptions and prohibited workflow descriptions.

Valid trigger-only description:

---
name: bug-investigator
description: Use when encountering bugs, errors, or unexpected behavior requiring investigation.
license: MIT
metadata:
  author: https://github.com/Jeffallan
  version: "1.0.0"
  domain: quality
  triggers: bug, error
  role: specialist
  scope: investigation
  output-format: code
  related-skills: test-master, devops-engineer
---

Invalid workflow-containing description:

---
name: bug-investigator
description: First run the diagnostics, then collect logs, finally suggest a fix.
license: MIT
metadata:
  author: https://github.com/Jeffallan
  version: "1.0.0"
---

Running python scripts/validate-skills.py against the invalid example produces:

Warning: Description should start with 'Use when' (trigger-only format) – skill: bug-investigator

Summary

• The description field format in Jeffallan/claude-skills enforces trigger-only usage through a combination of documentation standards and automated validation.
• CLAUDE.md defines the "Use when" convention that restricts descriptions to invocation conditions only (lines 25-30).
• DescriptionFormatChecker in scripts/validate-skills.py automatically verifies the "Use when" prefix during CI runs (lines 25-34).
• CI integration ensures non-compliant skills trigger warnings and block releases, preventing workflow steps from entering the description field.

Frequently Asked Questions

What happens if a skill description does not start with "Use when"?

The DescriptionFormatChecker in scripts/validate-skills.py emits a warning message identifying the specific skill that violates the convention. Because this validation runs as part of the CI pipeline, the warning prevents the release from proceeding until the description is corrected to use the required "Use when" prefix.

Can the description field contain implementation details if they follow "Use when"?

No. According to the CLAUDE.md specification (lines 25-30), the description must only state the conditions that should cause the skill to be invoked. While the automated checker specifically validates the "Use when" prefix, the convention explicitly prohibits including workflow steps, procedural instructions, or implementation details regardless of the prefix presence.

Where is the description field located in a skill file?

The description field resides in the YAML front-matter of each SKILL.md file within the skill directories. The validate-skills.py script parses this front-matter to extract and validate the description value against the trigger-only format requirements.

Is the validation script manually executed or automatic?

The scripts/validate-skills.py script runs automatically as part of the continuous integration pipeline defined in the project's Release Checklist. While developers can run it locally using python scripts/validate-skills.py, its integration into CI ensures that every skill merged into the repository undergoes mandatory validation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}