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

> Understand how the Claude Skills description format enforces trigger-only usage with a mandatory Use when prefix. Learn more about skill invocation conditions.

- Repository: [Jeffallan/claude-skills](https://github.com/jeffallan/claude-skills)
- Tags: internals
- Published: 2026-02-19

---

**The `description` field format enforces trigger-only usage by requiring a mandatory "Use when" prefix defined in [`CLAUDE.md`](https://github.com/Jeffallan/claude-skills/blob/main/CLAUDE.md) and validated automatically by the `DescriptionFormatChecker` class in [`scripts/validate-skills.py`](https://github.com/Jeffallan/claude-skills/blob/main/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`](https://github.com/Jeffallan/claude-skills/blob/main/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`](https://github.com/Jeffallan/claude-skills/blob/main/scripts/validate-skills.py) file implements the `DescriptionFormatChecker` class (lines 25-34), which performs static analysis on every [`SKILL.md`](https://github.com/Jeffallan/claude-skills/blob/main/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:**

```yaml
---
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:**

```yaml
---
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:

```text
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`](https://github.com/Jeffallan/claude-skills/blob/main/CLAUDE.md)** defines the "Use when" convention that restricts descriptions to invocation conditions only (lines 25-30).
- **`DescriptionFormatChecker`** in [`scripts/validate-skills.py`](https://github.com/Jeffallan/claude-skills/blob/main/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`](https://github.com/Jeffallan/claude-skills/blob/main/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`](https://github.com/Jeffallan/claude-skills/blob/main/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`](https://github.com/Jeffallan/claude-skills/blob/main/SKILL.md) file within the skill directories. The [`validate-skills.py`](https://github.com/Jeffallan/claude-skills/blob/main/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`](https://github.com/Jeffallan/claude-skills/blob/main/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.