afv-library/skills/creating-sf-skill/references/validation_rules.md

Validation Rules Reference

Complete reference for all validation checks enforced by scripts/validate-skills.ts. The validator runs structure checks first (before reading SKILL.md), then content checks.

Structure Checks

These run on every entry in skills/ before SKILL.md is read. A fatal error aborts all content checks for that entry.

1. Entry Must Be a Directory

• Severity: Error (fatal)
• Rule: No loose files in skills/ — only directories.
• Fix: Move the file into a skill directory or remove it.

2. Must Contain SKILL.md

• Severity: Error (fatal)
• Rule: Every skill directory must have a SKILL.md file.
• Fix: Create SKILL.md with proper frontmatter and body.

3. Name Must Be Kebab-Case

• Severity: Error
• Pattern: ^[a-z0-9]+(-[a-z0-9]+)*$
• Allowed: lowercase letters, digits, hyphens
• Not allowed: uppercase, underscores, dots, spaces
• Examples:
  • generating-apex (valid)
  • Generating-Apex (invalid — uppercase)
  • generating_apex (invalid — underscore)

4. Name <= 64 Characters

• Severity: Error
• Rule: Directory name must not exceed 64 characters.

5. Gerund First Word

• Severity: Warning (not blocking)
• Rule: First word of the skill name should end in -ing.
• Rationale: Convention for consistency (e.g., generating-, building-, deploying-).
• Examples:
  • generating-apex (pass)
  • agentforce-development (warning — "agentforce" doesn't end in -ing)

6. No Nested Skills

• Severity: Error
• Rule: No subdirectory of a skill may contain its own SKILL.md.
• Fix: Flatten nested skills to be siblings under skills/.

Content Checks

These run after SKILL.md is read successfully.

7. Valid YAML Frontmatter Block

• Severity: Error (fatal)
• Rule: SKILL.md must start with ---\n...\n--- YAML frontmatter.
• Fix: Add frontmatter between --- delimiters at the top of the file.

8. JSON-Compatible YAML

• Severity: Error
• Rule: Frontmatter must parse with js-yaml JSON_SCHEMA.
• Common cause: Unquoted values containing : (colon + space).
• Fix: Wrap values in single or double quotes.

  # BAD
  description: Primary skill: generates Apex classes
  
  # GOOD
  description: "Primary skill: generates Apex classes"
  

9. name Matches Directory

• Severity: Error
• Rule: The name field in frontmatter must exactly match the directory name.
• Fix: Ensure name: generating-apex if the directory is skills/generating-apex/.

10. description Present and Non-Empty

• Severity: Error
• Rule: Frontmatter must include a description field with content.

11. Body Non-Empty

• Severity: Error
• Rule: There must be content after the frontmatter block.

12. Description >= 20 Words

• Severity: Error
• Rule: Description must contain at least 20 words.
• Rationale: Short descriptions don't provide enough trigger context.

13. Description <= 1024 Characters

• Severity: Error
• Rule: Description must not exceed 1024 characters.

14. Description Contains "use"

• Severity: Error
• Rule: Description must include the word "use" (case-insensitive).
• Rationale: Enforces trigger/activation language.
• Fix: Include phrases like "Use when...", "Use this skill for...", "Used to...".

15. Body <= 500 Lines

• Severity: Warning (not blocking)
• Rule: Skill body should be under 500 lines for context efficiency.
• Fix: Extract detailed content into references/ with conditional load instructions.

Running Validation

# Validate all skills
npm run validate:skills

# Validate only changed skills (CI mode)
npm run validate:skills -- --changed --base=origin/main

# Validate a specific skill (filter output)
npx tsx scripts/validate-skills.ts 2>&1 | grep -A5 "<skill-name>"