claudecode-omc 4.3.4

package/skills/skill-debugger/SKILL.md

@@ -0,0 +1,333 @@
+---
+name: skill-debugger
+description: Debugs why Claude Code skills aren't triggering when expected, analyzing descriptions, trigger conditions, and skill discovery issues
+---
+
+# Skill Debugger
+
+Systematic debugging tool for Claude Code skills that aren't triggering as expected. Identifies root causes like poor descriptions, missing trigger words, naming issues, or skill discovery problems.
+
+## Agent Workflow
+
+To debug effectively, follow this **Hybrid Workflow**:
+
+1.  **Fact Check (Hard Metrics)**: Use `Glob` and `Read` tools to verify the **target skill's** implementation.
+    *   Does the folder exist?
+    *   Does `SKILL.md` exist?
+    *   Is the YAML frontmatter valid?
+2.  **Context Analysis (Soft Metrics)**: Compare the **target skill's** description with the **user's recent prompts**.
+    *   *Agent Cognition*: "The user asked for 'finance help', but the skill description only says 'data analysis'. That's why it didn't trigger."
+3.  **Synthesize**: Report the factual findings (e.g., "File exists") + your semantic diagnosis (e.g., "Description is too vague").
+
+## Capabilities
+
+- **Trigger Analysis**: Examines why a skill isn't being invoked when it should be
+- **Description Evaluation**: Checks if skill description clearly communicates when to use it
+- **Keyword Detection**: Identifies missing or weak trigger keywords in descriptions
+- **Discovery Debugging**: Verifies Claude Code can find and load the skill
+- **Conflict Detection**: Identifies skills with overlapping triggers or descriptions
+- **YAML Validation**: Checks frontmatter format and required fields
+- **Interactive Diagnosis**: Guides through systematic debugging steps
+- **Fix Suggestions**: Provides specific improvements to enhance skill triggering
+
+## Common Skill Triggering Problems
+
+### Problem 1: Vague Description
+**Symptom**: Skill exists but Claude Code never uses it
+**Root Cause**: Description doesn't mention specific use cases or keywords
+**Example**:
+```yaml
+description: Helps with various tasks  ❌ Too vague
+description: Analyzes financial ratios from statement data for investment decisions  ✅ Specific
+```
+
+### Problem 2: No Clear Trigger Words
+**Symptom**: Need to explicitly mention skill name to invoke it
+**Root Cause**: Description lacks keywords that match user queries
+**Fix**: Add trigger keywords like "financial analysis", "investment", "ratios"
+
+### Problem 3: Skill Not Discovered
+**Symptom**: Claude Code says skill doesn't exist
+**Root Cause**: Wrong installation location or invalid SKILL.md
+**Check**: `~/.claude/skills/[name]/SKILL.md` or project-local `.claude/skills/[name]/SKILL.md`
+
+### Problem 4: Name Mismatch
+**Symptom**: Skill found but not loaded
+**Root Cause**: YAML `name` doesn't match folder name
+**Fix**: Ensure `name: skill-name` matches folder `skill-name/`
+
+### Problem 5: Overlapping Skills
+**Symptom**: Wrong skill triggers instead
+**Root Cause**: Multiple skills with similar descriptions
+**Fix**: Make each description unique and specific
+
+## Input Requirements
+
+**Basic Debugging**:
+- Skill name or path
+- Expected trigger scenario (what you asked that should have triggered it)
+
+**Deep Analysis**:
+- All installed skills paths (for conflict detection)
+- Recent conversation history (to see what Claude Code chose instead)
+
+## Output Formats
+
+**Quick Diagnosis**:
+```
+Skill: code-review
+Status: ❌ Not triggering
+Root Cause: Description too generic
+Fix: Add specific keywords like "review", "code quality", "pull request"
+```
+
+**Detailed Report**:
+```
+=== Skill Debugging Report ===
+
+Skill: financial-analyzer
+Path: ~/.claude/skills/financial-analyzer/
+Status: ⚠️ Rarely triggers
+
+Issues Found:
+1. [CRITICAL] Description missing use case keywords
+   - Current: "Analyzes financial data"
+   - Should mention: financial ratios, investment analysis, DCF, valuation
+
+2. [HIGH] No "When to Use" section in SKILL.md
+   - Claude Code can't determine clear triggering conditions
+
+3. [MEDIUM] Overlaps with "data-analyzer" skill
+   - Both mention "analyzes data"
+   - Make this one specific to finance
+
+Recommendations:
+1. Update description to: "Calculates financial ratios and performs DCF valuation analysis for investment decisions"
+2. Add "When to Use" section with examples: "when analyzing company financials", "for investment analysis"
+3. Differentiate from data-analyzer by focusing on financial metrics
+
+Expected Improvement: 90% better triggering with these fixes
+```
+
+**Conflict Matrix**:
+```
+Skills with Overlapping Triggers:
+
+code-review  ←→  quality-analyzer  (both mention "code quality")
+  Fix: code-review for PRs, quality-analyzer for metrics
+
+data-analyzer  ←→  financial-analyzer  (both mention "analysis")
+  Fix: Make financial-analyzer specific to finance keywords
+```
+
+## Debugging Workflow
+
+### Step 1: Verify Skill Exists
+
+```
+"Check if my code-review skill is installed correctly"
+"Is the financial-analyzer skill discoverable?"
+```
+
+Claude Code will:
+- Check file exists at expected location
+- Validate SKILL.md format
+- Verify YAML frontmatter
+
+### Step 2: Analyze Description Quality
+
+```
+"Why isn't my code-review skill triggering?"
+"Debug the financial-analyzer skill - I asked about ratios but it didn't trigger"
+```
+
+Claude Code will:
+- Examine description for specificity
+- Check for relevant keywords
+- Compare against your query
+
+### Step 3: Test Trigger Scenarios
+
+```
+"What should I ask to trigger the code-review skill?"
+"Give me 5 phrases that should invoke financial-analyzer"
+```
+
+Claude Code will:
+- Generate test queries based on description
+- Identify gaps between description and intended use
+- Suggest description improvements
+
+### Step 4: Check for Conflicts
+
+```
+"Do any of my skills conflict with code-review?"
+"Why does data-analyzer trigger instead of financial-analyzer?"
+```
+
+Claude Code will:
+- Compare all skill descriptions
+- Identify overlapping keywords
+- Suggest differentiation strategies
+
+## Systematic Debugging Questions
+
+When a skill isn't triggering, Claude Code will check:
+
+1. **Installation Check**
+   - "Is the skill at `~/.claude/skills/[name]/SKILL.md` or `.claude/skills/[name]/SKILL.md`?"
+   - "Does the skill folder exist?"
+
+2. **YAML Validation**
+   - "Is the YAML frontmatter properly formatted with `---` delimiters?"
+   - "Does the `name:` field match the folder name?"
+   - "Is there a `description:` field?"
+
+3. **Description Quality**
+   - "Does the description mention specific use cases?"
+   - "Does it include keywords you'd naturally use?"
+   - "Is it specific enough to avoid confusion with other skills?"
+
+4. **Content Analysis**
+   - "Is there a 'When to Use' or 'Use Cases' section?"
+   - "Are there clear usage examples?"
+   - "Does the first paragraph explain the purpose?"
+
+5. **Conflict Check**
+   - "Do other skills have similar descriptions?"
+   - "Which skill actually triggered instead?"
+   - "How can we differentiate this skill?"
+
+## How to Use
+
+**Quick Fix**:
+```
+"My code-review skill isn't working"
+"Why doesn't Claude Code use my financial-analyzer?"
+"Debug skill triggering for aws-solution-architect"
+```
+
+**Detailed Analysis**:
+```
+"I asked 'analyze this company's financials' but financial-analyzer didn't trigger. Debug it."
+"Compare my code-review and quality-analyzer skills - which should trigger when?"
+```
+
+**Preventive Check**:
+```
+"Before I install this skill, check if it will trigger correctly"
+"Will my new skill conflict with existing ones?"
+```
+
+## Common Fixes (By Root Cause)
+
+### Fix 1: Improve Description Specificity
+**Before**: `description: Helps with code analysis`
+**After**: `description: Performs static code quality analysis with metrics calculation and refactoring suggestions`
+
+### Fix 2: Add Trigger Keywords
+Add words users would naturally say:
+- Financial skill: "ratios", "valuation", "DCF", "investment"
+- Code skill: "review", "quality", "refactor", "analyze code"
+- Data skill: "visualization", "trends", "insights", "dashboard"
+
+### Fix 3: Add "When to Use" Section
+```markdown
+## When to Use
+
+Use this skill when you need to:
+- Analyze company financial statements
+- Calculate financial ratios (P/E, ROE, ROA, etc.)
+- Perform DCF valuation
+- Make investment decisions based on financial data
+```
+
+### Fix 4: Differentiate from Similar Skills
+If you have `data-analyzer` and `financial-analyzer`:
+- data-analyzer: "for general data analysis and visualization"
+- financial-analyzer: "specifically for financial statement analysis and investment metrics"
+
+### Fix 5: Fix Name Mismatch
+Ensure folder name matches YAML name:
+```
+Folder: ~/.claude/skills/code-review/
+YAML: name: code-review  ✅
+
+Folder: ~/.claude/skills/code-review/
+YAML: name: code_review  ❌ Mismatch!
+```
+
+## Diagnostic Checklist
+
+When debugging, Claude Code will check:
+
+- [ ] Skill file exists at correct location
+- [ ] SKILL.md has valid YAML frontmatter
+- [ ] `name` in YAML matches folder name
+- [ ] `description` is 50-150 characters
+- [ ] Description includes specific use case keywords
+- [ ] Description mentions when/what/who/why
+- [ ] No vague words (helps, assists, various, many)
+- [ ] "When to Use" or similar section exists
+- [ ] At least 3 usage examples present
+- [ ] No conflicts with other skill descriptions
+- [ ] Trigger keywords match natural language queries
+
+## Integration with Other Skills
+
+**Works with skill-quality-analyzer**:
+```
+"Run quality analysis on financial-analyzer then debug why it's not triggering"
+```
+
+**Works with skill-tester**:
+```
+"Test if code-review skill triggers for 'review this PR'"
+```
+
+**Workflow**:
+1. skill-debugger: Identify why not triggering
+2. skill-quality-analyzer: Check overall quality
+3. Fix issues
+4. skill-tester: Verify fix works
+
+## Limitations
+
+- **Cannot Read Claude Code's Internal Decision Process**: Can only infer based on descriptions
+- **No Real-Time Monitoring**: Can't watch skill selection in action
+- **Heuristic-Based**: Uses patterns, not guaranteed 100% accurate
+- **No Auto-Fix**: Provides recommendations but you must apply them
+- **Context-Dependent**: Triggering also depends on conversation context
+
+## When NOT to Use This Skill
+
+- **Skill Works Fine**: No debugging needed
+- **Skill Execution Errors**: Use skill-tester for runtime issues
+- **Documentation Issues**: Use documentation tools
+- **Quality Problems**: Use skill-quality-analyzer
+
+## Success Metrics
+
+After applying fixes, skill should trigger when:
+- User query contains description keywords
+- Use case matches "When to Use" section
+- No more specific skill exists for the query
+
+**Expected Trigger Rate**: 80-90% when query clearly matches intended use case
+
+## Pro Tips
+
+1. **Test Your Descriptions**: Ask "Would I say this naturally?"
+2. **Be Specific**: "financial ratio calculation" > "data analysis"
+3. **Avoid Overlaps**: Each skill should have unique keywords
+4. **Use Examples**: Add 5+ usage examples in SKILL.md
+5. **Think Like Users**: What would you actually ask?
+6. **Regular Audits**: Run debugger on all skills monthly
+7. **Version Descriptions**: Track what works over time
+
+## Claude Code Specific Notes
+
+- Skills are discovered from `~/.claude/skills/` and `.claude/skills/` in project root
+- Use `Glob` tool to search for skills: `Glob(pattern="**/SKILL.md")`
+- Use `Read` tool to examine skill content
+- Skill invocation uses the `Skill` tool with skill name parameter

package/skills/skill-quality-analyzer/HOW_TO_USE.md

@@ -0,0 +1,243 @@
+# How to Use Skill Quality Analyzer
+
+## Basic Usage
+
+### Single Skill Analysis
+
+```
+"Analyze the quality of my aws-solution-architect skill"
+"Check the quality score for ~/.codex/skills/code-review/"
+"Generate a quality report for the prompt-factory skill"
+```
+
+**What Codex will do**:
+1. Read the skill's SKILL.md file
+2. Evaluate across 6 dimensions
+3. Calculate overall score (0-100)
+4. List issues and recommendations
+
+### Detailed Report
+
+```
+"Give me a detailed quality analysis of skill-debugger with specific recommendations"
+"Analyze ~/.codex/skills/content-researcher/ and tell me what needs improvement"
+```
+
+**Output includes**:
+- Overall score and quality level
+- Dimension-by-dimension scores
+- Critical issues (severity-ranked)
+- Prioritized improvement recommendations
+- Comparison with Codex best practices
+
+## Advanced Usage
+
+### Batch Analysis
+
+```
+"Analyze all skills in ~/.codex/skills/ and rank them by quality"
+"Compare quality scores across all my custom skills"
+"Which of my skills need the most improvement?"
+```
+
+### Comparative Analysis
+
+```
+"Compare my code-review skill against Codex's official examples"
+"How does my skill-tester compare to best practices?"
+"Show me the quality difference between my top 3 and bottom 3 skills"
+```
+
+### Before Distribution
+
+```
+"I want to share my financial-analyzer skill. Is it ready?"
+"Run quality checks before I package this skill"
+"What should I fix before publishing to the skill marketplace?"
+```
+
+## Understanding the Output
+
+### Overall Score
+
+| Score | Quality Level | Meaning |
+|-------|---------------|---------|
+| 90-100 | Excellent | Ready for production, can be shared as example |
+| 80-89 | Good | Minor improvements, safe to deploy |
+| 70-79 | Acceptable | Address key issues before wide distribution |
+| 60-69 | Needs Work | Significant improvements required |
+| <60 | Poor | Major refactoring needed |
+
+### Six Dimensions Explained
+
+**1. Clarity (20%)**
+- Is the skill's purpose clear?
+- Are capabilities well-defined?
+- Is usage unambiguous?
+
+**Example Issue**: "Description uses vague words like 'helps' and 'various'"
+**Recommendation**: "Replace vague words with specific capabilities"
+
+**2. Structure (20%)**
+- Valid YAML frontmatter?
+- Required sections present?
+- Proper formatting?
+
+**Example Issue**: "Skill name not in kebab-case format"
+**Recommendation**: "Change name to kebab-case (e.g., skill-quality-analyzer)"
+
+**3. Examples (15%)**
+- Good usage examples?
+- Sample input data?
+- Expected output shown?
+
+**Example Issue**: "Missing sample_input.json file"
+**Recommendation**: "Add sample_input.json showing example input data"
+
+**4. Trigger Detection (15%)**
+- Clear when to invoke?
+- Specific keywords?
+- No overlap with other skills?
+
+**Example Issue**: "Description doesn't clearly state use case"
+**Recommendation**: "Add use case to description (e.g., 'for analyzing...' or 'when you need...')"
+
+**5. Best Practices (15%)**
+- Follows Codex guidelines?
+- README and HOW_TO_USE present?
+- No backup files or __pycache__?
+
+**Example Issue**: "Found 3 backup files (should be removed)"
+**Recommendation**: "Remove all backup files (.backup, .bak, .old)"
+
+**6. Maintainability (15%)**
+- Clean file structure?
+- Version information?
+- Well-commented code?
+
+**Example Issue**: "No version information found"
+**Recommendation**: "Add version number to README.md or SKILL.md"
+
+## Real-World Examples
+
+### Example 1: Quick Health Check
+
+**User**: "Is my code-review skill good enough to share?"
+
+**Codex**:
+```
+Analyzing ~/.codex/skills/code-review/...
+
+Overall Score: 87 (Good)
+
+✅ Strengths:
+- Excellent clarity (95) - Very clear purpose
+- Strong structure (90) - All sections present
+- Good examples (85) - Rich usage examples
+
+⚠️ Areas for Improvement:
+- Missing sample_input.json (affects Examples score)
+- No version information (affects Maintainability)
+
+Recommendation: Safe to share, but add sample_input.json and version info for best quality.
+```
+
+### Example 2: Identify Weaknesses
+
+**User**: "Why is my skill-tester score only 65?"
+
+**Codex**:
+```
+Quality Analysis: skill-tester (65 - Needs Work)
+
+Critical Issues:
+1. [CLARITY] Description too brief (< 20 chars) - Score: 55
+2. [STRUCTURE] Missing required sections: Input Requirements, Output Formats - Score: 60
+3. [EXAMPLES] No usage examples found - Score: 40
+
+High Priority Recommendations:
+1. Expand description to 50-100 characters with clear use case
+2. Add Input Requirements and Output Formats sections
+3. Add 3-5 concrete usage examples
+
+Fix these 3 issues to reach 80+ (Good quality).
+```
+
+### Example 3: Batch Comparison
+
+**User**: "Compare quality of all my skills"
+
+**Codex**:
+```
+Quality Analysis (5 skills):
+
+Excellent (90+):
+  - prompt-factory: 94
+  - aws-solution-architect: 92
+
+Good (80-89):
+  - code-review: 87
+  - content-researcher: 82
+
+Needs Work (60-69):
+  - skill-tester: 65
+
+Recommendation: Focus improvement effort on skill-tester.
+Common issues across all skills: Missing version information (4/5 skills).
+```
+
+## Integration with Your Workflow
+
+### Before Commit
+
+```bash
+# In your skill development workflow
+1. Create/modify skill
+2. Ask Codex: "Analyze quality of this skill"
+3. Fix critical issues (score < 80)
+4. Commit when score ≥ 80
+```
+
+### CI/CD Integration
+
+You can integrate quality checks into your workflow:
+
+```
+# Pre-commit hook idea
+"Check if any modified skills dropped below 80 quality score"
+```
+
+### Continuous Improvement
+
+```
+# Monthly quality review
+"Analyze all my skills and identify trends"
+"Which quality dimensions need attention across my skills?"
+```
+
+## Tips for High Quality Scores
+
+1. **Start with Templates**: Use Skill Factory templates (already high quality)
+2. **Be Specific**: Avoid vague words (helps, various, many)
+3. **Show Examples**: Include 3-5 concrete usage examples
+4. **Add Sample Data**: Include sample_input.json and expected_output.json
+5. **Clean Up**: Remove backup files and __pycache__ before analysis
+6. **Document Everything**: README, HOW_TO_USE, clear sections
+7. **Version Your Skills**: Add version info for maintainability
+8. **Follow Conventions**: Use kebab-case names, proper YAML
+9. **Target 80+**: Good quality threshold
+10. **Iterate**: Analyze → Fix → Re-analyze
+
+## Troubleshooting
+
+**Q: "Codex isn't using this skill when I ask about quality"**
+A: Try being more explicit: "Use the skill-quality-analyzer skill to analyze..."
+
+**Q: "The score seems too harsh"**
+A: Quality analyzer uses strict Codex standards. Score of 70+ is acceptable.
+
+**Q: "Can I customize the scoring weights?"**
+A: Not currently. Weights are based on Codex best practices (Clarity and Structure are most important at 20% each).
+
+**Q: "How do I improve my Trigger Detection score?"**
+A: Add clear "When to Use" section and mention specific use cases in the description.

package/skills/skill-quality-analyzer/README.md

@@ -0,0 +1,61 @@
+# Skill Quality Analyzer
+
+6-dimension quality analysis system for Codex skills, inspired by CodeDNA.
+
+## Quick Install
+
+```bash
+# User-level (all projects)
+cp -r skill-quality-analyzer ~/.codex/skills/
+
+# Project-level (current project only)
+cp -r skill-quality-analyzer .codex/skills/
+```
+
+## Usage
+
+Once installed, Codex will automatically use this skill when you ask about skill quality:
+
+```
+"Analyze the quality of my code-review skill"
+"What's the quality score for the aws-solution-architect skill?"
+"Generate a quality report for all my custom skills"
+```
+
+## What This Skill Does
+
+Evaluates skills across **6 dimensions** (inspired by CodeDNA):
+
+1. **Clarity** (20%) - How clear is the purpose and usage?
+2. **Structure** (20%) - Proper YAML, sections, formatting?
+3. **Examples** (15%) - Good usage examples and sample data?
+4. **Trigger Detection** (15%) - Clear when to invoke?
+5. **Best Practices** (15%) - Follows Codex guidelines?
+6. **Maintainability** (15%) - Easy to update and maintain?
+
+## Output
+
+- Overall score (0-100)
+- Dimension-by-dimension breakdown
+- Critical issues list
+- Prioritized improvement recommendations
+- Quality level: Excellent (90+), Good (80-89), Acceptable (70-79), Needs Work (60-69), Poor (<60)
+
+## Files
+
+- `SKILL.md` - Main skill definition (read this first)
+- `README.md` - This file
+- `HOW_TO_USE.md` - Detailed usage examples
+- `sample_input.json` - Example skill to analyze
+- `expected_output.json` - Example quality report
+
+## No Python Required
+
+This skill is **documentation-driven**. Codex uses the SKILL.md instructions to analyze skills without needing Python implementation. Python modules can be added later if needed for automation.
+
+## Related Skills
+
+- `skill-debugger` - Debug why skills aren't triggering
+- `skill-tester` - Test skill functionality (TDD)
+- `skill-doc-generator` - Auto-generate documentation
+- `skill-template-generator` - Quick skill scaffolding (installed)