oh-my-codex-cli 0.1.0

package/.agent/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/.agent/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)

package/.agent/skills/skill-quality-analyzer/SKILL.md

@@ -0,0 +1,247 @@
+---
+name: skill-quality-analyzer
+description: Analyzes Codex skill quality with 6-dimension scoring system similar to CodeDNA, providing actionable improvement recommendations
+---
+
+# Skill Quality Analyzer
+
+Comprehensive quality analysis system for Codex skills using a 6-dimension scoring framework inspired by CodeDNA. Identifies quality issues, provides improvement recommendations, and generates detailed quality reports.
+
+## Agent Workflow
+
+To perform a high-quality analysis, follow this **Hybrid Workflow**:
+
+1.  **Run Static Analysis**: Execute `python3 analyzer.py --skill-path [TARGET_SKILL_PATH]` to get objective metrics for the **target skill**.
+2.  **Read Target Skill Content**: Use `view_file` to read the `SKILL.md` and `HOW_TO_USE.md` of the **skill you are analyzing** (the target skill). *Do not read this analyzer skill's own files.*
+3.  **Synthesize Report**: Combine the script's findings (hard metrics) with your manual review of the **target skill's content** (soft metrics) to generate the final report.
+    *   *Script says*: "Description too short." -> *You check*: "Is it just short, or is it actual nonsense?"
+    *   *Script says*: "100/100 score." -> *You check*: "Format is perfect, but does the logic make sense?"
+
+## Capabilities
+
+- **6-Dimension Quality Scoring**: Evaluates skills across Clarity, Structure, Examples, Trigger Detection, Best Practices, and Maintainability (0-100 scale)
+- **Automated Issue Detection**: Identifies common problems like missing examples, unclear descriptions, poor structure, and missing trigger words
+- **Improvement Recommendations**: Provides specific, actionable suggestions for each quality dimension
+- **Comparative Analysis**: Compares skills against best practices from official Antigravity examples
+- **Quality Report Generation**: Creates detailed markdown reports with scores, issues, and recommendations
+- **Batch Analysis**: Analyzes multiple skills at once for consistency checking
+
+## Input Requirements
+
+**Single Skill Analysis**:
+- Skill folder path (e.g., `~/.codex/skills/my-skill/`)
+- Or SKILL.md file path directly
+
+**Batch Analysis**:
+- Directory containing multiple skills
+- Or list of skill paths
+
+**Data Requirements**:
+- Valid SKILL.md file with YAML frontmatter
+- Optional: Python files, README.md, HOW_TO_USE.md
+
+## Output Formats
+
+**Quality Score Card** (JSON):
+```json
+{
+  "overall_score": 85,
+  "dimensions": {
+    "clarity": {"score": 90, "weight": 20},
+    "structure": {"score": 85, "weight": 20},
+    "examples": {"score": 80, "weight": 15},
+    "trigger_detection": {"score": 90, "weight": 15},
+    "best_practices": {"score": 80, "weight": 15},
+    "maintainability": {"score": 85, "weight": 15}
+  },
+  "issues": ["Missing usage examples", "No sample inputs"],
+  "recommendations": ["Add 3-5 concrete usage examples", "Include sample_input.json"]
+}
+```
+
+**Quality Report** (Markdown):
+- Executive summary with overall score
+- Dimension-by-dimension breakdown
+- Critical issues list (severity-ranked)
+- Improvement recommendations (prioritized)
+- Comparison with best practices
+- Before/After improvement potential
+
+## Six Quality Dimensions
+
+### 1. Clarity (20%)
+- **What it measures**: How clearly the skill's purpose, capabilities, and usage are communicated
+- **Key indicators**:
+  - Description specificity (not vague)
+  - Clear capability statements
+  - Unambiguous usage instructions
+  - No jargon without explanation
+- **Scoring**:
+  - 90-100: Crystal clear, no ambiguity
+  - 70-89: Mostly clear, minor improvements needed
+  - 50-69: Some confusion possible
+  - <50: Unclear purpose or usage
+
+### 2. Structure (20%)
+- **What it measures**: Organizational quality and consistency with Anthropic standards
+- **Key indicators**:
+  - Valid YAML frontmatter (name in kebab-case, concise description)
+  - Required sections present (Capabilities, Input/Output, How to Use)
+  - Logical section ordering
+  - Proper markdown formatting
+- **Scoring**:
+  - 90-100: Perfect structure, all sections present
+  - 70-89: Minor structural issues
+  - 50-69: Missing key sections
+  - <50: Severely malformed
+
+### 3. Examples (15%)
+- **What it measures**: Quality and quantity of usage examples
+- **Key indicators**:
+  - 3-5 concrete usage examples
+  - sample_input.json present
+  - expected_output.json present
+  - Examples cover major use cases
+- **Scoring**:
+  - 90-100: Rich examples with sample data
+  - 70-89: Good examples, missing sample files
+  - 50-69: Minimal examples
+  - <50: No examples or sample data
+
+### 4. Trigger Detection (15%)
+- **What it measures**: How easily Codex can determine when to invoke this skill
+- **Key indicators**:
+  - Clear "When to use" section
+  - Specific trigger keywords identified
+  - Description mentions use cases
+  - No overlap with existing skills
+- **Scoring**:
+  - 90-100: Crystal clear triggers
+  - 70-89: Mostly clear when to use
+  - 50-69: Ambiguous triggering conditions
+  - <50: No clear triggers
+
+### 5. Best Practices (15%)
+- **What it measures**: Adherence to Codex skill development standards
+- **Key indicators**:
+  - Follows Codex naming conventions
+  - Proper Python structure (if applicable)
+  - README.md and HOW_TO_USE.md present
+  - No backup files or __pycache__
+  - Proper file organization
+- **Scoring**:
+  - 90-100: Exemplary adherence
+  - 70-89: Minor deviations
+  - 50-69: Several best practice violations
+  - <50: Major violations
+
+### 6. Maintainability (15%)
+- **What it measures**: How easy it is to update and maintain the skill
+- **Key indicators**:
+  - Clear code comments (if Python files)
+  - Modular design
+  - No hard-coded values
+  - Version information present
+  - Clean file structure (no clutter)
+- **Scoring**:
+  - 90-100: Highly maintainable
+  - 70-89: Generally maintainable
+  - 50-69: Some maintenance challenges
+  - <50: Difficult to maintain
+
+## How to Use
+
+**Basic Analysis**:
+```
+"Analyze the quality of my skill-creator skill"
+"What's the quality score for ~/.codex/skills/code-review/"
+"Run quality analysis on the aws-solution-architect skill"
+```
+
+**Detailed Report**:
+```
+"Generate a detailed quality report for skill-debugger"
+"Analyze ~/.codex/skills/prompt-factory/ and create improvement recommendations"
+```
+
+**Batch Analysis**:
+```
+"Analyze all skills in ~/.codex/skills/ and rank them by quality"
+"Compare quality scores across all my custom skills"
+```
+
+**Comparative Analysis**:
+```
+"Compare my code-review skill against Antigravity's best practices"
+"How does skill-tester compare to official skills in quality?"
+```
+
+## Scripts
+
+- `analyzer.py`: Core 6-dimension quality analysis engine
+  - Usage: `python3 analyzer.py --skill-path /path/to/skill`
+- `validator.py`: YAML frontmatter and structure validation (merged into analyzer.py)
+- `best_practices_checker.py`: Checks adherence to Codex standards (merged into analyzer.py)
+
+## Best Practices
+
+1. **Run Before Distribution**: Always analyze skills before sharing or installing
+2. **Target 80+ Score**: Aim for overall scores of 80 or higher for production skills
+3. **Fix Critical Issues First**: Address issues flagged as "Critical" or "High" severity
+4. **Iterate**: Re-analyze after improvements to track progress
+5. **Batch Analysis for Consistency**: Use batch mode to ensure consistent quality across all your skills
+6. **Compare Against Examples**: Use comparative analysis to learn from official skills
+
+## Integration with Quality Systems
+
+**Agent-KB Integration**:
+- Automatically records quality patterns from high-scoring skills
+- Learns common issues from low-scoring skills
+- Suggests improvements based on historical data
+
+**CodeDNA Alignment**:
+- Uses similar 6-dimension framework
+- Consistent scoring methodology
+- Shares best practices database
+
+**CI/CD Integration**:
+- Can be used in pre-commit hooks
+- Quality gates for skill deployment
+- Automated quality regression testing
+
+## Limitations
+
+- **Static Analysis Only**: Does not test skill execution or effectiveness
+- **No Runtime Testing**: Cannot verify if Python code works correctly
+- **Pattern-Based**: Relies on known patterns and best practices
+- **English-Focused**: May not handle non-English skills as effectively
+- **No Context Understanding**: Cannot judge if a skill's purpose is valuable
+- **File-Based**: Requires access to skill files (cannot analyze from description alone)
+
+## When NOT to Use This Skill
+
+- **Testing Functional Correctness**: Use skill-tester instead
+- **Runtime Debugging**: Use skill-debugger for execution issues
+- **Documentation Generation**: Use skill-doc-generator for creating docs
+- **Initial Skill Creation**: Use skill-creator or templates first, then analyze
+
+## Quality Thresholds
+
+| Score Range | Quality Level | Action |
+|-------------|---------------|--------|
+| 90-100 | Excellent | Ready for production, share 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 |
+
+## Comparison with CodeDNA
+
+| Dimension | CodeDNA (Code) | Skill Quality Analyzer (Skills) |
+|-----------|----------------|----------------------------------|
+| Clarity | Comments & naming | Description & documentation |
+| Structure | Code organization | Section organization & YAML |
+| Examples | Test coverage | Usage examples & sample data |
+| Patterns | Design patterns | Trigger detection |
+| Standards | Coding standards | Codex best practices |
+| Maintenance | Cyclomatic complexity | File cleanliness & modularity |