Quality Rules

10 quality rules for skill definitions and agent configuration files.

Rules

Rule ID	Severity	Description
QA_001	WARN	Missing description field
QA_002	WARN	Name doesn't match directory name
QA_003	WARN	Description too short (< 20 characters)
QA_004	WARN	Skill body is empty
QA_005	INFO	Thin skill body (< 50 characters after stripping code blocks)
QA_006	INFO	Missing tools list
QA_007	WARN	Invalid name format
QA_008	WARN	Oversized file (> 50KB)
QA_009	HIGH	File exceeds maximum scannable size (1MB)
QA_010	HIGH	Binary file content detected

Why It Matters

Rules QA_001 through QA_007 apply specifically to SKILL.md files with YAML frontmatter. They enforce consistent naming, meaningful descriptions, and non-trivial skill bodies so that agents can discover and invoke skills reliably. Rules QA_008 (oversized file), QA_009 (max scannable size), and QA_010 (binary content) apply to all supported file types -- they are general file health checks, not SKILL.md-specific.

A well-formed SKILL.md looks like this:

---
name: my-skill
description: A helpful skill that does something specific and useful
tools:
  - Read
  - Write
  - Bash
---

Detailed instructions for the skill go here...

Rule Details

QA_001: Missing Description

Checks that required frontmatter fields (name and description) exist. If either field is absent, the rule fires.

Applies to: SKILL.md only. Severity: WARN.

Examples

Flagged in SKILL.md -- missing description:

---
name: my-skill
---

Instructions here...

Flagged in SKILL.md -- missing name:

---
description: A helpful skill
---

Instructions here...

Correct -- both fields present:

---
name: my-skill
description: A helpful skill that does something specific and useful
---

Instructions here...

QA_002: Name Doesn't Match Directory Name

Checks that the name field in frontmatter matches the directory name where the skill lives. For example, a skill at .claude/skills/code-review/SKILL.md must have name: code-review in its frontmatter.

Applies to: SKILL.md only. Severity: WARN.

Examples

Flagged -- skill lives in .claude/skills/code-review/SKILL.md but name doesn't match:

---
name: review-helper
description: Reviews code for quality issues
---

Instructions here...

Correct -- name matches the directory:

---
name: code-review
description: Reviews code for quality issues
---

Instructions here...

QA_003: Description Too Short

Flags descriptions shorter than a minimum character threshold. Short descriptions provide little value for skill discovery.

Applies to: SKILL.md only. Severity: WARN.

Configurable parameters:

Param	Default	Description
min_description_length	20	Minimum number of characters required in the description field

rules:
  QA_003:
    params:
      min_description_length: 30

Examples

Flagged in SKILL.md -- description is only 7 characters:

---
name: my-skill
description: A skill
---

Instructions here...

Correct -- description is descriptive and meets the minimum length:

---
name: my-skill
description: A helpful skill that does something specific and useful
---

Instructions here...

QA_004: Skill Body Is Empty

Fires when the SKILL.md file has valid frontmatter but no body content at all after the closing ---.

Applies to: SKILL.md only. Severity: WARN.

Examples

Flagged in SKILL.md -- no body after frontmatter:

---
name: my-skill
description: A helpful skill that does something specific and useful
---

Correct -- body contains instructions:

---
name: my-skill
description: A helpful skill that does something specific and useful
---

When the user asks for help, follow these steps:

1. Read the relevant files
2. Analyze the code
3. Suggest improvements

QA_005: Thin Skill Body

Fires when the body content has fewer than 50 characters of prose after stripping code blocks. A body that consists almost entirely of code fences with minimal explanatory text is likely insufficient as a skill definition.

Applies to: SKILL.md only. Severity: INFO.

Examples

Flagged in SKILL.md -- body is too thin (only a few words of prose):

---
name: my-skill
description: A helpful skill that does something specific and useful
---

Do this.

Correct -- body has substantial instructions:

---
name: my-skill
description: A helpful skill that does something specific and useful
---

When the user asks for help with code review, follow these steps:

1. Read all changed files using the Read tool
2. Analyze each file for common issues including bugs, style violations, and security concerns
3. Provide clear, actionable feedback

QA_006: Missing Tools List

Flags SKILL.md files where the tools field is absent from frontmatter or present but empty. Declaring tools helps agents and humans understand what capabilities a skill requires.

Applies to: SKILL.md only. Severity: INFO.

Examples

Flagged in SKILL.md -- no tools field:

---
name: my-skill
description: A helpful skill that does something specific and useful
---

Instructions here...

Flagged in SKILL.md -- tools is present but empty:

---
name: my-skill
description: A helpful skill that does something specific and useful
tools:
---

Instructions here...

Correct -- tools list is populated:

---
name: my-skill
description: A helpful skill that does something specific and useful
tools:
  - Read
  - Write
  - Bash
---

Instructions here...

QA_007: Invalid Name Format

Enforces a strict naming format. Names must be at most 64 characters and match the pattern ^[a-z0-9]([a-z0-9:-]*[a-z0-9])?$ -- lowercase letters, numbers, hyphens, and colons only. Names must start and end with a letter or digit. Colons support namespaced skills (e.g., compound-engineering:review).

Applies to: SKILL.md only. Severity: WARN.

Examples

Flagged -- uppercase letters:

---
name: My-Skill
description: A helpful skill that does something specific and useful
---

Flagged -- underscores are not allowed (use hyphens instead):

---
name: my_skill
description: A helpful skill that does something specific and useful
---

Flagged -- spaces are not allowed:

---
name: my skill
description: A helpful skill that does something specific and useful
---

Flagged -- special characters are not allowed:

---
name: my-skill!
description: A helpful skill that does something specific and useful
---

Flagged -- name longer than 64 characters.

Correct -- valid names: my-skill, code-review-helper, deploy-v2, compound-engineering:review.

QA_008: Oversized File

Flags files larger than a configurable size threshold. Very large configuration files are difficult to review and may indicate that binary or generated content has been committed by mistake.

Applies to: All file types. Severity: WARN.

Configurable parameters:

Param	Default	Description
max_file_size_kb	50	Maximum file size in kilobytes before the rule fires

rules:
  QA_008:
    params:
      max_file_size_kb: 100

Examples

Flagged -- any supported file type exceeding 50KB (or the configured threshold).

Not flagged -- a file under the size limit, regardless of content.

QA_009: File Exceeds Maximum Scannable Size

Fires when a file exceeds the hard 1MB maximum scannable size. Files this large cannot be parsed and are reported as a parse error with reason content_too_large.

Applies to: All file types. Severity: HIGH.

Examples

Flagged -- any supported file type exceeding 1MB. This is a hard limit and is not configurable.

Not flagged -- files under 1MB are parsed normally (though they may still trigger QA_008 if they exceed the oversized threshold).

QA_010: Binary File Content Detected

Fires when a file contains binary content instead of text. Binary files cannot be meaningfully scanned for agent configuration issues and are reported as a parse error with reason binary_content.

Applies to: All file types. Severity: HIGH.

Examples

Flagged -- a file named CLAUDE.md that actually contains binary data (e.g., an image was accidentally saved with a .md extension).

Not flagged -- any file containing valid text content.