ci: Update validation workflows to skip supporting documentation files

Improved YAML frontmatter and date validation to properly exclude files
that don't need validation:

1. **Depth-based exclusion**: Skip files at depth 3+ in skills/ directory
   - skills/skill/references/*.md (reference files)
   - skills/skill/foundation/*.md (foundation guides)
   - skills/skill/interactive/*.md (interactive guides)
   - skills/skill/implementation/*.md (implementation guides)

2. **Name-based exclusion**: Skip specific documentation files
   - README.md, SUMMARY.txt (across all directories)
   - CLAUDE_MD_UPDATES.md (supporting documentation)
   - Existing meta files (_INDEX.md, MIGRATION_GUIDE.md, etc.)

3. **Improved output**: Show both checked and skipped file counts

This aligns with the skill structure where only SKILL.md files (main entry
points) require YAML frontmatter and date validation, while supporting
documentation files in subdirectories are optional.

Results:
- Frontmatter validation: 135 skill files checked, 32 skipped
- Date validation: 163 dates checked across skill files, 32 skipped

Author: claude

.github/workflows/smoke-tests.yml

@@ -50,14 +50,42 @@ jobs:
 
           errors = []
           checked = 0
+          skipped = 0
+
+          # Meta files that don't need frontmatter (by name)
+          SKIP_FILES = {
+              "MIGRATION_GUIDE.md", "REFACTORING_SUMMARY.md", "_INDEX.md",
+              "README.md", "ENHANCEMENT_PLAN.md", "ENHANCEMENTS_SUMMARY.md",
+              "SKILLS_USAGE_GUIDE.md", "CLAUDE.md", "SUMMARY.txt",
+              "CLAUDE_MD_UPDATES.md"  # Supporting documentation
+          }
 
           for skill_file in Path(".").rglob("*.md"):
-              # Skip archived and meta files
+              # Skip archived files
               if "_archive" in str(skill_file):
+                  skipped += 1
                   continue
-              if skill_file.name in ["MIGRATION_GUIDE.md", "REFACTORING_SUMMARY.md", "_INDEX.md", "README.md", "ENHANCEMENT_PLAN.md", "ENHANCEMENTS_SUMMARY.md", "SKILLS_USAGE_GUIDE.md", "CLAUDE.md"]:
+
+              # Skip meta files by name
+              if skill_file.name in SKIP_FILES:
+                  skipped += 1
                   continue
 
+              # Calculate depth (number of slashes after skills/)
+              # skills/file.md = depth 1 ✓
+              # skills/category/file.md = depth 2 ✓
+              # skills/skill/SKILL.md = depth 2 ✓
+              # skills/skill/references/file.md = depth 3 ✗ (supporting files)
+              parts = skill_file.parts
+              if "skills" in parts:
+                  skills_idx = parts.index("skills")
+                  depth = len(parts) - skills_idx - 1
+
+                  # Skip files at depth 3+ (these are reference/foundation/implementation files)
+                  if depth >= 3:
+                      skipped += 1
+                      continue
+
               content = skill_file.read_text(encoding='utf-8')
               checked += 1
 
@@ -88,7 +116,8 @@ jobs:
                   if not re.match(r'^[a-z0-9-]+$', name):
                       errors.append(f"{skill_file}: Invalid name format '{name}' (must be hyphen-case)")
 
-          print(f"Checked {checked} skill files\n")
+          print(f"Checked: {checked} skill files")
+          print(f"Skipped: {skipped} supporting/meta files\n")
 
           if errors:
               print("❌ FAILED: Found frontmatter errors:\n")
@@ -98,6 +127,6 @@ jobs:
               print("="*60)
               sys.exit(1)
           else:
-              print("✅ SUCCESS: All frontmatter is valid")
+              print("✅ SUCCESS: All skill files have valid frontmatter")
               print("="*60)
           EOF

.github/workflows/validate-dates.yml

@@ -40,15 +40,39 @@ jobs:
 
           errors = []
           checked = 0
+          skipped = 0
+
+          # Meta files that don't need date validation (by name)
+          SKIP_FILES = {
+              "MIGRATION_GUIDE.md", "REFACTORING_SUMMARY.md", "_INDEX.md",
+              "README.md", "ENHANCEMENT_PLAN.md", "ENHANCEMENTS_SUMMARY.md",
+              "SKILLS_USAGE_GUIDE.md", "CLAUDE.md", "SUMMARY.txt",
+              "CLAUDE_MD_UPDATES.md"  # Supporting documentation
+          }
 
           # Check skills directory
           for skill_file in Path(".").rglob("*.md"):
-              # Skip archived files and meta files
+              # Skip archived files
               if "_archive" in str(skill_file):
+                  skipped += 1
                   continue
-              if skill_file.name in ["MIGRATION_GUIDE.md", "REFACTORING_SUMMARY.md", "_INDEX.md", "README.md", "ENHANCEMENT_PLAN.md", "ENHANCEMENTS_SUMMARY.md", "SKILLS_USAGE_GUIDE.md", "CLAUDE.md"]:
+
+              # Skip meta files by name
+              if skill_file.name in SKIP_FILES:
+                  skipped += 1
                   continue
 
+              # Calculate depth (number of slashes after skills/)
+              # Skip files at depth 3+ (these are reference/foundation/implementation files)
+              parts = skill_file.parts
+              if "skills" in parts:
+                  skills_idx = parts.index("skills")
+                  depth = len(parts) - skills_idx - 1
+
+                  if depth >= 3:
+                      skipped += 1
+                      continue
+
               content = skill_file.read_text(encoding='utf-8')
               matches = re.findall(r'\*\*Last Updated\*\*:\s*(\d{4}-\d{2}-\d{2})', content)
 
@@ -58,7 +82,8 @@ jobs:
                   if date > today:
                       errors.append(f"{skill_file}: Future date {match} (today is {today})")
 
-          print(f"Checked {checked} dates across skill files\n")
+          print(f"Checked: {checked} dates")
+          print(f"Skipped: {skipped} supporting/meta files\n")
 
           if errors:
               print("❌ FAILED: Found future dates:\n")