feat: Add CI workflows and quality assurance infrastructure

Add comprehensive CI/CD validation and documentation from global .claude/:

**GitHub Actions Workflows** (.github/workflows/):
- validate-dates.yml: Prevents future dates in skill 'Last Updated' fields
- smoke-tests.yml: Two-job validation pipeline
  - validate-code-blocks: Python/Swift/Zig syntax validation
  - validate-frontmatter: YAML frontmatter compliance (name, description)

**Test Infrastructure** (tests/):
- validate_code_blocks.py: Extracts and validates code blocks by language
  - Python: AST parsing for syntax validation
  - Swift: swiftc -parse (if available)
  - Zig: zig ast-check (if available)
  - JavaScript/TypeScript: Basic validation

**Documentation**:
- ENHANCEMENT_PLAN.md: Roadmap for splitting 89 skills >500 lines
- ENHANCEMENTS_SUMMARY.md: Summary of quality improvements
- SKILLS_USAGE_GUIDE.md: Guide for using skills effectively

**Updated Files**:
- CLAUDE.md: Added quality assurance section (as of 2025-10-18)
  - Step 4: Updated discovery workflow with meta skills emphasis
  - Section 9: Added Quality Standards and Skill Quality Assurance
  - Enforcement Checklist: Added Skills Quality Standards
  - References to CI validation, frontmatter compliance, size guidelines
- skills/api/api-error-handling.md: Updated timestamps to 2025-10-18

**Quality Standards Enforced**:
✅ All 132 skills have YAML frontmatter (name, description)
✅ All dates validated (no future dates allowed)
✅ Python code blocks validated for syntax
✅ Size optimization tracked (89 skills >500 lines identified)

**CI Benefits**:
- Prevents invalid skill updates (future dates, broken code, missing frontmatter)
- Automated quality checks on every PR and push to main
- Ensures agent compatibility via consistent frontmatter format
- Tracks technical debt (large skills to be split)

Author: rand

.github/workflows/smoke-tests.yml

@@ -0,0 +1,103 @@
+name: Smoke Tests
+
+on:
+  pull_request:
+    paths:
+      - 'skills/**/*.md'
+      - 'tests/**'
+      - '.github/workflows/smoke-tests.yml'
+  push:
+    branches:
+      - main
+
+jobs:
+  validate-code-blocks:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Validate Python code blocks
+        run: |
+          python3 tests/validate_code_blocks.py
+
+  validate-frontmatter:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Validate YAML frontmatter
+        run: |
+          python3 << 'EOF'
+          import re
+          import sys
+          from pathlib import Path
+
+          print("="*60)
+          print("VALIDATING YAML FRONTMATTER")
+          print("="*60)
+
+          errors = []
+          checked = 0
+
+          for skill_file in Path(".").rglob("*.md"):
+              # Skip archived and meta files
+              if "_archive" in str(skill_file):
+                  continue
+              if skill_file.name in ["MIGRATION_GUIDE.md", "REFACTORING_SUMMARY.md", "_INDEX.md", "README.md", "ENHANCEMENT_PLAN.md"]:
+                  continue
+
+              content = skill_file.read_text(encoding='utf-8')
+              checked += 1
+
+              # Check for frontmatter
+              if not content.strip().startswith('---\n'):
+                  errors.append(f"{skill_file}: Missing YAML frontmatter")
+                  continue
+
+              # Parse frontmatter
+              parts = content.split('---\n', 2)
+              if len(parts) < 3:
+                  errors.append(f"{skill_file}: Invalid frontmatter format")
+                  continue
+
+              frontmatter = parts[1]
+
+              # Check required fields
+              if not re.search(r'^name:\s*\S+', frontmatter, re.MULTILINE):
+                  errors.append(f"{skill_file}: Missing 'name' field")
+
+              if not re.search(r'^description:\s*.+', frontmatter, re.MULTILINE):
+                  errors.append(f"{skill_file}: Missing 'description' field")
+
+              # Validate name format (hyphen-case)
+              name_match = re.search(r'^name:\s*(\S+)', frontmatter, re.MULTILINE)
+              if name_match:
+                  name = name_match.group(1)
+                  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")
+
+          if errors:
+              print("❌ FAILED: Found frontmatter errors:\n")
+              for error in errors:
+                  print(f"  • {error}")
+              print(f"\n{len(errors)} error(s) found")
+              print("="*60)
+              sys.exit(1)
+          else:
+              print("✅ SUCCESS: All frontmatter is valid")
+              print("="*60)
+          EOF

.github/workflows/validate-dates.yml

@@ -0,0 +1,73 @@
+name: Validate Dates
+
+on:
+  pull_request:
+    paths:
+      - 'skills/**/*.md'
+      - '.github/workflows/validate-dates.yml'
+  push:
+    branches:
+      - main
+    paths:
+      - 'skills/**/*.md'
+
+jobs:
+  check-dates:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Check for future dates
+        run: |
+          python3 << 'EOF'
+          import re
+          import sys
+          from pathlib import Path
+          from datetime import datetime
+
+          print("="*60)
+          print("VALIDATING 'Last Updated' DATES")
+          print("="*60)
+
+          today = datetime.now().date()
+          print(f"Today's date: {today}\n")
+
+          errors = []
+          checked = 0
+
+          # Check skills directory
+          for skill_file in Path(".").rglob("*.md"):
+              # Skip archived files and meta files
+              if "_archive" in str(skill_file):
+                  continue
+              if skill_file.name in ["MIGRATION_GUIDE.md", "REFACTORING_SUMMARY.md", "_INDEX.md", "README.md"]:
+                  continue
+
+              content = skill_file.read_text(encoding='utf-8')
+              matches = re.findall(r'\*\*Last Updated\*\*:\s*(\d{4}-\d{2}-\d{2})', content)
+
+              for match in matches:
+                  checked += 1
+                  date = datetime.strptime(match, "%Y-%m-%d").date()
+                  if date > today:
+                      errors.append(f"{skill_file}: Future date {match} (today is {today})")
+
+          print(f"Checked {checked} dates across skill files\n")
+
+          if errors:
+              print("❌ FAILED: Found future dates:\n")
+              for error in errors:
+                  print(f"  • {error}")
+              print(f"\n{len(errors)} future date(s) found")
+              print("="*60)
+              sys.exit(1)
+          else:
+              print("✅ SUCCESS: All dates are valid")
+              print("="*60)
+          EOF

CLAUDE.md

@@ -219,19 +219,25 @@ Mobile → Swift (iOS native) or React Native (cross-platform)
 CLI/TUI → Go (Bubble Tea) or Rust (Ratatui)
 ```
 
-### Step 4: Discover Relevant Skills
+### Step 4: Discover Relevant Skills (UPDATED 2025-10-18)
 Before starting specialized work:
 1. **New repository?** Use `skill-repo-discovery.md` to analyze tech stack → Activate identified skills
 2. **User prompt/request?** Use `skill-prompt-discovery.md` to extract intent → Activate identified skills
 3. **Manual search?** Check `skills/_INDEX.md` or search by pattern: `modal-*.md`, `swiftui-*.md`, `zig-*.md`
 4. Read only relevant skills (don't read all skills upfront)
 5. Compose multiple skills for complex workflows
 
-**Meta skills enable intelligent discovery**:
+**Meta skills enable intelligent discovery** (all have YAML frontmatter for agent compatibility):
 - Repository onboarding: `skill-repo-discovery.md` analyzes codebase → maps to existing skills
 - Prompt analysis: `skill-prompt-discovery.md` extracts tech signals → activates relevant skills
 - Gap identification: `skill-repo-planning.md` or `skill-prompt-planning.md` → plans missing skills
 
+**Quality assurance**: All 132 skills are validated by CI for:
+- YAML frontmatter compliance (agent_skills_spec.md)
+- Date accuracy (no future dates)
+- Code syntax (Python blocks validated)
+- Size optimization (target <500 lines)
+
 ### Step 5: Project Structure
 ```
 Language → Init Command → Structure
@@ -426,15 +432,25 @@ open https://ui.shadcn.com/themes
 ## 9. Skills System
 
 ### Philosophy: Atomic Skills
-**Old approach**: Monolithic skills `/zig-dev`, `/modal-dev` (too large)  
-**New approach**: Atomic, composable skills (260 lines avg)
+**Old approach**: Monolithic skills `/zig-dev`, `/modal-dev` (too large)
+**New approach**: Atomic, composable skills (~300 lines avg, <500 line guideline)
+
+### Quality Standards (as of 2025-10-18)
+- ✅ **132 skills** with YAML frontmatter (agent_skills_spec.md compliant)
+- ✅ **0 future dates** - all dates validated by CI
+- ✅ **Automated testing** - code syntax validation in CI
+- 🔄 **Size optimization** - 89 skills >500 lines identified for splitting
 
 ### Discovery Pattern
 ```bash
-# 1. Identify domain
+# 0. AUTOMATIC DISCOVERY (Recommended)
+# For new repos: Use skill-repo-discovery.md to analyze codebase → activates relevant skills
+# For user requests: Use skill-prompt-discovery.md to extract intent → activates skills
+
+# 1. Manual: Identify domain
 "I need Zig memory management" → zig-memory-management.md
 
-# 2. Search by pattern
+# 2. Manual: Search by pattern
 ls skills/zig-*.md
 ls skills/modal-*.md
 ls skills/swiftui-*.md
@@ -450,7 +466,7 @@ ls skills/deployment/*.md
 ls skills/math/*.md
 ls skills/mobile/*.md
 
-# 3. Read relevant skills only
+# 3. Read relevant skills only (NOT all upfront)
 Read zig-memory-management.md, zig-testing-patterns.md
 
 # 4. Compose for complex workflows
@@ -513,20 +529,28 @@ Mobile:         mobile/react-native-*.md (4)
 ```
 
 ### Key Principles
-1. **Discover**: Search by pattern or category directory
+1. **Discover**: Use automated discovery skills OR search by pattern/category
 2. **Compose**: Combine skills for complex workflows
 3. **Apply**: Read only what you need, when you need it
 4. **Iterate**: Add more skills during work as requirements emerge
+5. **Validate**: Skills are CI-tested for syntax and frontmatter compliance
 
-### Discovery Workflow
+### Discovery Workflow (UPDATED 2025-10-18)
 0. **New repo/codebase?** Run `skill-repo-discovery.md` → Activate identified skills
 1. **User request?** Run `skill-prompt-discovery.md` → Activate identified skills
-2. **Quick task?** Use Quick Category Reference above (lines 488-504) for pattern matching
+2. **Quick task?** Use Quick Category Reference for pattern matching
 3. **Need workflow?** Check `skills/_INDEX.md` → "Skill Combination Examples"
 4. **Deep dive?** Search `skills/_INDEX.md` by technology/task/problem domain
 5. **Emergency?** Read relevant skill directly: `skills/api-*.md`, `skills/cicd/*.md`
 
-**Full catalog**: `skills/_INDEX.md` (129 skills, workflows, search patterns, combinations)
+**Full catalog**: `skills/_INDEX.md` (132 skills, workflows, search patterns, combinations)
+
+### Skill Quality Assurance
+All skills now include:
+- **YAML frontmatter** with `name` and `description` (enables programmatic discovery)
+- **Accurate dates** validated by CI (no future dates allowed)
+- **Code validation** via smoke tests (Python syntax checked automatically)
+- **Size guidelines** (<500 lines recommended; see `ENHANCEMENT_PLAN.md` for split plans)
 
 ---
 
@@ -677,7 +701,8 @@ Execute
 
 Before completing ANY task:
 ```
-[ ] Searched/read relevant atomic skills (check skills/_INDEX.md)
+[ ] Discovered relevant skills (use skill-repo-discovery.md or skill-prompt-discovery.md)
+[ ] Read atomic skills from skills/ directory (check skills/_INDEX.md)
 [ ] Challenged vague requirements
 [ ] Confirmed tech stack and deployment
 [ ] Followed correct package manager (uv, cargo, etc.)
@@ -693,6 +718,15 @@ Before completing ANY task:
 
 **If ANY checkbox unchecked, stop and address it.**
 
+### Skills Quality Standards (Updated 2025-10-18)
+```
+[ ] All skills have YAML frontmatter (name, description)
+[ ] No future-dated "Last Updated" fields
+[ ] Code blocks are syntactically valid
+[ ] New skills should be <500 lines (guideline from skill-creation.md)
+[ ] CI workflows validate quality on every commit
+```
+
 ---
 
 ## Conclusion