start-vibing 1.1.2 → 1.1.4

package/template/.claude/skills/codebase-knowledge/domains/claude-system.md

@@ -1,321 +1,260 @@
-# Claude System
-
-## Last Update
-
-- **Date:** 2024-12-19
-- **Commit:** pending
-- **Session:** Created start-vibing npm package for easy Claude setup
-
-## Files
-
-### Agents
-
-- `.claude/agents/analyzer.md` - Analyzes change impact, approves files
-- `.claude/agents/research.md` - **NEW** Researches best practices (2024-2025) before implementation
-- `.claude/agents/commit-manager.md` - Manages git commits, runs complete-task
-- `.claude/agents/documenter.md` - Creates/updates documentation
-- `.claude/agents/domain-updater.md` - Updates domain knowledge after sessions
-- `.claude/agents/final-validator.md` - Final validation with VETO power
-- `.claude/agents/orchestrator.md` - Coordinates entire workflow
-- `.claude/agents/quality-checker.md` - Runs quality gates
-- `.claude/agents/security-auditor.md` - Security audit with VETO power
-- `.claude/agents/tester.md` - Creates unit and E2E tests
-- `.claude/agents/ui-ux-reviewer.md` - Reviews UI/UX patterns
-
-### Hooks
-
-- `.claude/hooks/pre-tool-use.py` - Blocks unapproved file modifications
-- `.claude/hooks/post-tool-use.py` - Tracks file modifications
-- `.claude/hooks/stop-validation.py` - Blocks incomplete workflows
-- `.claude/hooks/user-prompt-submit.py` - Runs on user prompt
-- `.claude/hooks/workflow-manager.py` - CLI for state tracking
-
-### Skills
-
-- `.claude/skills/codebase-knowledge/` - Domain mapping system
-- `.claude/skills/research-cache/` - **NEW** Best practices research cache
-- `.claude/skills/docs-tracker/` - Documentation tracking
-- `.claude/skills/final-check/` - Final validation rules
-- `.claude/skills/quality-gate/` - Quality gate definitions
-- `.claude/skills/security-scan/` - Security audit rules
-- `.claude/skills/test-coverage/` - Test coverage tracking
-- `.claude/skills/ui-ux-audit/` - UI/UX audit rules
-
-### Configuration
-
-- `.claude/settings.json` - Agent registration, flows, rules
-- `.claude/workflow-state.json` - Current task state
-- `.claude/CLAUDE.md` - System documentation
-
-### Config Files (NEW - 2024-12-19)
-
-- `.claude/config/project-config.json` - Stack, structure, commands
-- `.claude/config/domain-mapping.json` - File patterns to domains
-- `.claude/config/quality-gates.json` - Quality check commands
-- `.claude/config/testing-config.json` - Test framework config
-- `.claude/config/security-rules.json` - Security audit rules
-- `.claude/config/README.md` - Config documentation
-
-### Root Files
-
-- `CLAUDE.md` - Development rules (generalist)
-- `PROJECT.md` - Project-specific details (your project)
-
-## Connections
-
-- **All domains:** domain-updater reads/updates domain files after sessions
-- **Infrastructure:** Hooks enforce workflow rules project-wide
-
-## Recent Commits
-
-| Hash | Date | Description |
-| ---- | ---- | ----------- |
-| de8cda9 | 2024-12-18 | feat(hooks): add domain-updater agent and enhance Task tool guidance |
-| e9b4ad3 | 2024-12-18 | fix(claude-system): move complete-task from commit-manager to domain-updater |
-| 251dfad | 2024-12-18 | feat(claude-system): add domain-updater agent as final workflow step |
-
-## Problems & Solutions
-
-### 2024-12-18 - Hook Blocking File Edits
-
-**Problem:**
-Tried to write files without starting a task first. PreToolUse hook blocked with "No active task in workflow-state.json"
-
-**Root Cause:**
-The pre-tool-use hook requires:
-1. Active task started via workflow-manager.py
-2. Analyzer executed
-3. Files approved for modification
-
-**Solution:**
-Run these commands before editing:
-```bash
-python .claude/hooks/workflow-manager.py start-task --type feature --description "..."
-python .claude/hooks/workflow-manager.py approve-files --files "path/to/file"
-python .claude/hooks/workflow-manager.py agent-executed --agent analyzer --result approved
-```
-
-**Prevention:**
-Always follow the workflow: start-task → approve-files → analyzer → implement
-
----
-
-### 2024-12-18 - Stop Hook Counting .claude/ as Source Files
-
-**Problem:**
-Stop hook blocked with "Modified 2 source file(s) but no tests created" for .claude/ config files
-
-**Root Cause:**
-The source file filter didn't exclude `.claude/` directory - only excluded test, spec, .md, and docs/
-
-**Solution:**
-Added `.claude/` to the exclusion list in stop-validation.py line 68
-
-**Prevention:**
-Config files in `.claude/` don't need unit tests - they're configuration, not source code
-
----
-
-### 2024-12-18 - complete-task Running Before domain-updater
-
-**Problem:**
-commit-manager ran `complete-task` which archived the workflow, then domain-updater couldn't edit files (no active task)
-
-**Root Cause:**
-Workflow order was wrong - complete-task was in commit-manager, but should run AFTER domain-updater
-
-**Solution:**
-- Removed `complete-task` from commit-manager
-- Added Step 6 to domain-updater with `complete-task`
-- New flow: commit-manager → domain-updater → complete-task
-
-**Prevention:**
-~~domain-updater is now responsible for `complete-task`~~ - OUTDATED: See workflow order fix below
-
----
-
-### 2024-12-18 - Workflow Order for Clean Git (FINAL FIX)
-
-**Problem:**
-Git tree stayed dirty after commit because domain updates happened AFTER the commit
-
-**Root Cause:**
-Old flow: commit-manager → domain-updater → complete-task
-This meant domain files were modified AFTER the commit, leaving uncommitted changes
-
-**Solution:**
-New flow: domain-updater → commit-manager → complete-task
-- domain-updater now runs BEFORE commit-manager
-- commit-manager is the FINAL agent (runs complete-task)
-- All changes are included in the commit
-- Git tree is clean after session ends
-
-**Prevention:**
-- domain-updater priority: 9 (runs after final-validator)
-- commit-manager priority: 10 (FINAL step)
-- Stop hook enforces both must run before session ends
-
----
-
-### 2024-12-18 - domain-updater Not Available as Subagent
-
-**Problem:**
-Tried to invoke domain-updater via Task tool but got "Agent type 'domain-updater' not found"
-
-**Root Cause:**
-Agents defined in `.claude/agents/*.md` are instructions for Claude to follow, not subagent_types in Claude Code system
-
-**Solution:**
-Execute domain-updater logic manually or use documenter agent which has similar capabilities
-
-**Prevention:**
-To make an agent invokable via Task tool, it needs to be registered in Claude Code's internal system (separate from .claude/agents/)
-
-## Attention Points
-
-- [2024-12-18] **Workflow is enforced by hooks** - Cannot skip steps, hooks will block
-- [2024-12-18] **domain-updater is MANDATORY** - Stop hook blocks if not executed
-- [2024-12-18] **10 agents total** - domain-updater added as final step (priority 10)
-- [2024-12-18] **Config files (.claude/*) don't require tests** - Excluded from source file checks
-- [2024-12-18] ~~**domain-updater runs complete-task**~~ - OUTDATED: commit-manager now runs complete-task
-- [2024-12-18] **.claude/agents/ vs subagent_type** - Agents in .claude/agents/ are instructions, not Claude Code subagents
-- [2024-12-18] **Never bypass workflow manually** - Follow the agents properly, don't mark as executed without running
-- [2024-12-18] **Use Task tool for agents** - UserPromptSubmit now reminds to use Task(subagent_type="agent-name") instead of manual execution
-- [2024-12-18] **Workflow order fixed** - domain-updater runs BEFORE commit-manager (not after) for clean git
-- [2024-12-18] **commit-manager is FINAL** - It runs complete-task, not domain-updater
-- [2024-12-18] **Stop hook enforces commit** - Blocks if domain-updater ran but commit-manager didn't
-- [2024-12-18] **Research agent added** - Mandatory for features/fixes, runs after analyzer
-- [2024-12-18] **11 agents total** - research added (priority 3)
-- [2024-12-18] **workflow-state.json in .gitignore** - Transient state, not tracked in git
-- [2024-12-19] **Config files for project specifics** - Agents read from `.claude/config/*.json` instead of hardcoding
-- [2024-12-19] **CLAUDE.md < 300 lines** - Best practice from Anthropic, ideally < 60 lines
-- [2024-12-19] **PROJECT.md for project details** - Separate from generic CLAUDE.md
-- [2024-12-19] **Pre-tool-use wildcard issue** - Pattern `.claude/config/*` doesn't match absolute paths, use specific files
-- [2024-12-19] **Tester agent v3.0** - Complete Playwright E2E architecture with fixture-based cleanup
-- [2024-12-19] **E2E cleanup is MANDATORY** - Track all created IDs, delete ONLY tracked data after tests
-- [2024-12-19] **Multi-viewport testing** - Desktop (1280x800), Tablet (768x1024), iPhone SE (375x667) required
-- [2024-12-19] **DB validation in E2E** - Always verify database state after UI actions
-- [2024-12-19] **Real auth only** - Never mock authentication in E2E tests
-- [2024-12-19] **data-testid required** - All interactive elements must have data-testid attributes
-- [2024-12-19] **SKILL.md YAML frontmatter** - ALL skills MUST have `---` frontmatter with name, description
-- [2024-12-19] **Skill name format** - max 64 chars, lowercase, letters/numbers/hyphens only
-- [2024-12-19] **Skill description** - max 1024 chars, describes WHAT skill does and WHEN to use it
-- [2024-12-19] **allowed-tools optional** - Comma-separated tool names to restrict skill capabilities
-- [2024-12-19] **Hooks config correct** - settings.json hooks format is valid, uses command type with python scripts
-- [2024-12-19] **start-vibing npm package** - CLI para copiar .claude para qualquer projeto
-- [2024-12-19] **npx/bunx CLI** - package.json bin field aponta para dist/cli.js com shebang
-- [2024-12-19] **Smart copy** - Preserva domains e cache, sobrescreve agents e hooks
-
-## Problems & Solutions (2024-12-19)
-
-### 2024-12-19 - CLAUDE.md Too Long and Specific
-
-**Problem:**
-CLAUDE.md had 594 lines, 95% project-specific. Too long for Claude to follow consistently.
-
-**Root Cause:**
-Project-specific details (workers, docker config, path aliases examples) mixed with universal rules.
-
-**Solution:**
-1. Reduced CLAUDE.md to 115 lines (universal rules only)
-2. Created `PROJECT.md` with project-specific details
-3. Created `.claude/config/` with JSON configs for project specifics
-4. Updated agents to read from config files
-
-**Prevention:**
-- Keep CLAUDE.md under 300 lines (ideally < 60)
-- Put project specifics in PROJECT.md
-- Use `.claude/config/` for things agents need to adapt to
-
----
-
-### 2024-12-19 - Pre-Tool-Use Wildcard Pattern Not Working
-
-**Problem:**
-Approved files with pattern `.claude/config/*` but hook still blocked edits to `.claude/config/project-config.json`
-
-**Root Cause:**
-Hook checks `file_path.startswith(approved[:-1])` but file_path is absolute path `C:/Users/.../` while approved is relative `.claude/config/*`
-
-**Solution:**
-Approve each file individually instead of using wildcard patterns
-
-**Prevention:**
-When using approve-files, list specific files rather than wildcards if path matching issues occur
-
----
-
-### 2024-12-19 - E2E Test Data Pollution
-
-**Problem:**
-E2E tests created data in the database but didn't clean up, causing test pollution and confusion with real data.
-
-**Root Cause:**
-Tests were creating users, items, etc. but not tracking or deleting them after completion.
-
-**Solution:**
-Implemented fixture-based cleanup pattern:
-1. `createdIds` fixture tracks all created document IDs by collection
-2. `trackCreated(collection, id)` function to register created data
-3. Auto-cleanup runs after each test, even on failure
-4. Only deletes tracked IDs, never affects real data
-
-**Prevention:**
-- Always use `trackCreated()` immediately after creating data
-- Use the custom `test` from fixtures, not base Playwright `test`
-- Verify cleanup is working with DB inspection
-
----
-
-### 2024-12-19 - Tester Agent Missing E2E Architecture
-
-**Problem:**
-Tester agent didn't have comprehensive E2E testing patterns for Playwright.
-
-**Root Cause:**
-Previous version focused on unit tests, lacked E2E architecture.
-
-**Solution:**
-Rewrote tester.md with complete Playwright architecture:
-- Fixture-based cleanup pattern
-- Multi-viewport testing (desktop, tablet, mobile)
-- Database validation after UI actions
-- API testing (REST and tRPC)
-- Real authentication flows
-- Storage state for session reuse
-- Security testing (forbidden requests, rate limiting)
-
-**Prevention:**
-- Always test all viewports
-- Always verify DB state, don't trust UI alone
-- Use real auth, never mock it
-
----
-
-### 2024-12-19 - Skills Missing YAML Frontmatter
-
-**Problem:**
-All SKILL.md files started with `# Title` instead of YAML frontmatter, making them undiscoverable by Claude Code.
-
-**Root Cause:**
-Skills were created as plain markdown without the required YAML frontmatter that Claude Code uses to discover and load skills.
-
-**Solution:**
-Added YAML frontmatter to all 8 SKILL.md files:
-```yaml
----
-name: skill-name-lowercase
-description: What skill does and when to use it
-allowed-tools: Tool1, Tool2  # optional
----
-```
-
-**Fixed Files:**
-- quality-gate, security-scan, codebase-knowledge, docs-tracker
-- final-check, ui-ux-audit, research-cache, test-coverage
-
-**Prevention:**
-- Quality-checker now validates SKILL.md format
-- All new skills MUST start with YAML frontmatter
-- name: lowercase-with-hyphens, max 64 chars
-- description: non-empty, max 1024 chars
+# Claude System
+
+## Last Update
+
+- **Date:** 2024-12-19
+- **Commit:** pending
+- **Session:** Fixed all skills to use YAML frontmatter format
+
+## Files
+
+### Agents
+
+- `.claude/agents/analyzer.md` - Analyzes change impact, approves files
+- `.claude/agents/research.md` - **NEW** Researches best practices (2024-2025) before implementation
+- `.claude/agents/commit-manager.md` - Manages git commits, runs complete-task
+- `.claude/agents/documenter.md` - Creates/updates documentation
+- `.claude/agents/domain-updater.md` - Updates domain knowledge after sessions
+- `.claude/agents/final-validator.md` - Final validation with VETO power
+- `.claude/agents/orchestrator.md` - Coordinates entire workflow
+- `.claude/agents/quality-checker.md` - Runs quality gates
+- `.claude/agents/security-auditor.md` - Security audit with VETO power
+- `.claude/agents/tester.md` - Creates unit and E2E tests
+- `.claude/agents/ui-ux-reviewer.md` - Reviews UI/UX patterns
+
+### Hooks
+
+- `.claude/hooks/user-prompt-submit.py` - Agent selection guidance before prompt processing
+
+### Skills
+
+- `.claude/skills/codebase-knowledge/` - Domain mapping system
+- `.claude/skills/research-cache/` - **NEW** Best practices research cache
+- `.claude/skills/docs-tracker/` - Documentation tracking
+- `.claude/skills/final-check/` - Final validation rules
+- `.claude/skills/quality-gate/` - Quality gate definitions
+- `.claude/skills/security-scan/` - Security audit rules
+- `.claude/skills/test-coverage/` - Test coverage tracking
+- `.claude/skills/ui-ux-audit/` - UI/UX audit rules
+
+### Configuration
+
+- `.claude/settings.json` - Agent registration, flows, rules
+- `.claude/workflow-state.json` - Current task state
+- `.claude/CLAUDE.md` - System documentation
+
+### Config Files (NEW - 2024-12-19)
+
+- `.claude/config/project-config.json` - Stack, structure, commands
+- `.claude/config/domain-mapping.json` - File patterns to domains
+- `.claude/config/quality-gates.json` - Quality check commands
+- `.claude/config/testing-config.json` - Test framework config
+- `.claude/config/security-rules.json` - Security audit rules
+- `.claude/config/README.md` - Config documentation
+
+### Root Files
+
+- `CLAUDE.md` - Development rules (115 lines, generalist)
+- `PROJECT.md` - Project-specific details (Solana Listeners)
+
+## Connections
+
+- **All domains:** domain-updater reads/updates domain files after sessions
+- **Infrastructure:** Hooks enforce workflow rules project-wide
+
+## Recent Commits
+
+| Hash | Date | Description |
+| ---- | ---- | ----------- |
+| de8cda9 | 2024-12-18 | feat(hooks): add domain-updater agent and enhance Task tool guidance |
+| e9b4ad3 | 2024-12-18 | fix(claude-system): move complete-task from commit-manager to domain-updater |
+| 251dfad | 2024-12-18 | feat(claude-system): add domain-updater agent as final workflow step |
+
+## Problems & Solutions
+
+### 2024-12-19 - Workflow Manager Removed
+
+**Problem:**
+The workflow-manager.py script and enforcement hooks (pre-tool-use.py, post-tool-use.py, stop-validation.py) were blocking operations and adding unnecessary complexity.
+
+**Root Cause:**
+The system was designed with strict workflow enforcement that prevented Claude from working flexibly.
+
+**Solution:**
+- Deleted workflow-manager.py, pre-tool-use.py, post-tool-use.py, stop-validation.py
+- Removed references from all documentation
+- Simplified settings.local.json to only keep UserPromptSubmit hook
+- Agents now work independently without state tracking requirements
+
+**Prevention:**
+Trust agents to coordinate naturally through Task tool invocation rather than enforcing artificial state machine.
+
+---
+- Git tree is clean after session ends
+
+**Prevention:**
+- domain-updater priority: 9 (runs after final-validator)
+- commit-manager priority: 10 (FINAL step)
+- Stop hook enforces both must run before session ends
+
+---
+
+### 2024-12-18 - domain-updater Not Available as Subagent
+
+**Problem:**
+Tried to invoke domain-updater via Task tool but got "Agent type 'domain-updater' not found"
+
+**Root Cause:**
+Agents defined in `.claude/agents/*.md` are instructions for Claude to follow, not subagent_types in Claude Code system
+
+**Solution:**
+Execute domain-updater logic manually or use documenter agent which has similar capabilities
+
+**Prevention:**
+To make an agent invokable via Task tool, it needs to be registered in Claude Code's internal system (separate from .claude/agents/)
+
+## Attention Points
+
+- [2024-12-18] **Workflow is enforced by hooks** - Cannot skip steps, hooks will block
+- [2024-12-18] **domain-updater is MANDATORY** - Stop hook blocks if not executed
+- [2024-12-18] **10 agents total** - domain-updater added as final step (priority 10)
+- [2024-12-18] **Config files (.claude/*) don't require tests** - Excluded from source file checks
+- [2024-12-18] ~~**domain-updater runs complete-task**~~ - OUTDATED: commit-manager now runs complete-task
+- [2024-12-18] **.claude/agents/ vs subagent_type** - Agents in .claude/agents/ are instructions, not Claude Code subagents
+- [2024-12-18] **Never bypass workflow manually** - Follow the agents properly, don't mark as executed without running
+- [2024-12-18] **Use Task tool for agents** - UserPromptSubmit now reminds to use Task(subagent_type="agent-name") instead of manual execution
+- [2024-12-18] **Workflow order fixed** - domain-updater runs BEFORE commit-manager (not after) for clean git
+- [2024-12-18] **commit-manager is FINAL** - It runs complete-task, not domain-updater
+- [2024-12-18] **Stop hook enforces commit** - Blocks if domain-updater ran but commit-manager didn't
+- [2024-12-18] **Research agent added** - Mandatory for features/fixes, runs after analyzer
+- [2024-12-18] **11 agents total** - research added (priority 3)
+- [2024-12-18] **workflow-state.json in .gitignore** - Transient state, not tracked in git
+- [2024-12-19] **Config files for project specifics** - Agents read from `.claude/config/*.json` instead of hardcoding
+- [2024-12-19] **CLAUDE.md < 300 lines** - Best practice from Anthropic, ideally < 60 lines
+- [2024-12-19] **PROJECT.md for project details** - Separate from generic CLAUDE.md
+- [2024-12-19] **Pre-tool-use wildcard issue** - Pattern `.claude/config/*` doesn't match absolute paths, use specific files
+- [2024-12-19] **Tester agent v3.0** - Complete Playwright E2E architecture with fixture-based cleanup
+- [2024-12-19] **E2E cleanup is MANDATORY** - Track all created IDs, delete ONLY tracked data after tests
+- [2024-12-19] **Multi-viewport testing** - Desktop (1280x800), Tablet (768x1024), iPhone SE (375x667) required
+- [2024-12-19] **DB validation in E2E** - Always verify database state after UI actions
+- [2024-12-19] **Real auth only** - Never mock authentication in E2E tests
+- [2024-12-19] **data-testid required** - All interactive elements must have data-testid attributes
+- [2024-12-19] **SKILL.md YAML frontmatter** - ALL skills MUST have `---` frontmatter with name, description
+- [2024-12-19] **Skill name format** - max 64 chars, lowercase, letters/numbers/hyphens only
+- [2024-12-19] **Skill description** - max 1024 chars, describes WHAT skill does and WHEN to use it
+- [2024-12-19] **allowed-tools optional** - Comma-separated tool names to restrict skill capabilities
+- [2024-12-19] **Hooks config correct** - settings.json hooks format is valid, uses command type with python scripts
+
+## Problems & Solutions (2024-12-19)
+
+### 2024-12-19 - CLAUDE.md Too Long and Specific
+
+**Problem:**
+CLAUDE.md had 594 lines, 95% specific to Solana Listeners project. Too long for Claude to follow consistently.
+
+**Root Cause:**
+Project-specific details (workers, docker config, path aliases examples) mixed with universal rules.
+
+**Solution:**
+1. Reduced CLAUDE.md to 115 lines (universal rules only)
+2. Created `PROJECT.md` with project-specific details
+3. Created `.claude/config/` with JSON configs for project specifics
+4. Updated agents to read from config files
+
+**Prevention:**
+- Keep CLAUDE.md under 300 lines (ideally < 60)
+- Put project specifics in PROJECT.md
+- Use `.claude/config/` for things agents need to adapt to
+
+---
+
+### 2024-12-19 - Pre-Tool-Use Wildcard Pattern Not Working
+
+**Problem:**
+Approved files with pattern `.claude/config/*` but hook still blocked edits to `.claude/config/project-config.json`
+
+**Root Cause:**
+Hook checks `file_path.startswith(approved[:-1])` but file_path is absolute path `C:/Users/.../` while approved is relative `.claude/config/*`
+
+**Solution:**
+Approve each file individually instead of using wildcard patterns
+
+**Prevention:**
+When using approve-files, list specific files rather than wildcards if path matching issues occur
+
+---
+
+### 2024-12-19 - E2E Test Data Pollution
+
+**Problem:**
+E2E tests created data in the database but didn't clean up, causing test pollution and confusion with real data.
+
+**Root Cause:**
+Tests were creating users, items, etc. but not tracking or deleting them after completion.
+
+**Solution:**
+Implemented fixture-based cleanup pattern:
+1. `createdIds` fixture tracks all created document IDs by collection
+2. `trackCreated(collection, id)` function to register created data
+3. Auto-cleanup runs after each test, even on failure
+4. Only deletes tracked IDs, never affects real data
+
+**Prevention:**
+- Always use `trackCreated()` immediately after creating data
+- Use the custom `test` from fixtures, not base Playwright `test`
+- Verify cleanup is working with DB inspection
+
+---
+
+### 2024-12-19 - Tester Agent Missing E2E Architecture
+
+**Problem:**
+Tester agent didn't have comprehensive E2E testing patterns for Playwright.
+
+**Root Cause:**
+Previous version focused on unit tests, lacked E2E architecture.
+
+**Solution:**
+Rewrote tester.md with complete Playwright architecture:
+- Fixture-based cleanup pattern
+- Multi-viewport testing (desktop, tablet, mobile)
+- Database validation after UI actions
+- API testing (REST and tRPC)
+- Real authentication flows
+- Storage state for session reuse
+- Security testing (forbidden requests, rate limiting)
+
+**Prevention:**
+- Always test all viewports
+- Always verify DB state, don't trust UI alone
+- Use real auth, never mock it
+
+---
+
+### 2024-12-19 - Skills Missing YAML Frontmatter
+
+**Problem:**
+All SKILL.md files started with `# Title` instead of YAML frontmatter, making them undiscoverable by Claude Code.
+
+**Root Cause:**
+Skills were created as plain markdown without the required YAML frontmatter that Claude Code uses to discover and load skills.
+
+**Solution:**
+Added YAML frontmatter to all 8 SKILL.md files:
+```yaml
+---
+name: skill-name-lowercase
+description: What skill does and when to use it
+allowed-tools: Tool1, Tool2  # optional
+---
+```
+
+**Fixed Files:**
+- quality-gate, security-scan, codebase-knowledge, docs-tracker
+- final-check, ui-ux-audit, research-cache, test-coverage
+
+**Prevention:**
+- Quality-checker now validates SKILL.md format
+- All new skills MUST start with YAML frontmatter
+- name: lowercase-with-hyphens, max 64 chars
+- description: non-empty, max 1024 chars