oh-my-codex-cli 0.1.0

package/.agent/skills/skill-quality-analyzer/analyzer.py

@@ -0,0 +1,209 @@
+#!/usr/bin/env python3
+import os
+import sys
+import yaml
+import json
+import re
+import argparse
+from pathlib import Path
+
+def load_skill_yaml(skill_path):
+    """Loads SKILL.md and parses frontmatter."""
+    skill_md_path = skill_path / "SKILL.md"
+    if not skill_md_path.exists():
+        return None, None
+    
+    try:
+        content = skill_md_path.read_text(encoding="utf-8")
+        parts = content.split("---")
+        if len(parts) < 3:
+            return None, content # Malformed frontmatter
+        
+        yaml_content = parts[1]
+        markdown_content = "---".join(parts[2:])
+        data = yaml.safe_load(yaml_content)
+        return data, markdown_content
+    except Exception as e:
+        print(f"Error parsing SKILL.md: {e}")
+        return None, None
+
+def analyze_clarity(frontmatter, markdown):
+    """Analyzes clarity dimension."""
+    score = 100
+    issues = []
+    
+    if not frontmatter.get("description"):
+        score -= 40
+        issues.append("Missing description in frontmatter")
+    else:
+        desc_len = len(frontmatter["description"])
+        if desc_len < 20:
+            score -= 20
+            issues.append("Description is too short (< 20 chars)")
+        if re.search(r"\b(helps|various|many|stuff|things)\b", frontmatter["description"], re.IGNORECASE):
+            score -= 10
+            issues.append("Description uses vague words")
+
+    return max(0, score), issues
+
+def analyze_structure(skill_path, frontmatter, markdown):
+    """Analyzes structure dimension."""
+    score = 100
+    issues = []
+    
+    if not frontmatter:
+        return 0, ["Invalid or missing YAML frontmatter"]
+        
+    if "name" not in frontmatter:
+        score -= 20
+        issues.append("Missing 'name' in frontmatter")
+    elif not re.match(r"^[a-z0-9-]+$", frontmatter["name"]):
+        score -= 10
+        issues.append("Skill name should be kebab-case")
+
+    required_sections = ["Capabilities", "Input Requirements", "How to Use"] # approximate matches
+    for section in required_sections:
+        if not re.search(f"^#+.*{section}", markdown, re.MULTILINE | re.IGNORECASE):
+            score -= 15
+            issues.append(f"Missing section: {section}")
+
+    return max(0, score), issues
+
+def analyze_examples(skill_path, markdown):
+    """Analyzes examples dimension."""
+    score = 100
+    issues = []
+    
+    # Check for examples in markdown
+    code_blocks = re.findall(r"```.*?```", markdown, re.DOTALL)
+    if len(code_blocks) < 2:
+        score -= 20
+        issues.append("Few or no usage examples found in SKILL.md")
+        
+    # Check for sample files
+    if not (skill_path / "sample_input.json").exists():
+        score -= 15
+        issues.append("Missing sample_input.json")
+    if not (skill_path / "expected_output.json").exists():
+        score -= 15
+        issues.append("Missing expected_output.json")
+        
+    return max(0, score), issues
+
+def analyze_triggers(frontmatter, markdown):
+    """Analyzes trigger detection dimension."""
+    score = 100
+    issues = []
+    
+    usage_section = re.search(r"^#+.*(How to Use|When to Use)", markdown, re.MULTILINE | re.IGNORECASE)
+    if not usage_section:
+        score -= 20
+        issues.append("No clear 'How to Use' or 'When to Use' section")
+        
+    if frontmatter and "description" in frontmatter:
+        desc = frontmatter["description"].lower()
+        triggers = ["when", "use this", "trigger", "ask"]
+        if not any(t in desc for t in triggers):
+             # Less strict check, just looking for specificity
+             pass 
+    
+    return max(0, score), issues
+
+def analyze_best_practices(skill_path, frontmatter):
+    """Analyzes best practices dimension."""
+    score = 100
+    issues = []
+    
+    if not (skill_path / "README.md").exists():
+        score -= 10
+        issues.append("Missing README.md")
+    if not (skill_path / "HOW_TO_USE.md").exists():
+        score -= 10
+        issues.append("Missing HOW_TO_USE.md")
+        
+    # Check for garbage files
+    garbage = list(skill_path.glob("**/*.pyc")) + list(skill_path.glob("**/.DS_Store"))
+    if garbage:
+        score -= 5
+        issues.append(f"Found {len(garbage)} garbage files (.pyc, .DS_Store)")
+        
+    return max(0, score), issues
+
+def analyze_maintainability(skill_path, frontmatter):
+    """Analyzes maintainability dimension."""
+    score = 100
+    issues = []
+    
+    if frontmatter and "version" not in frontmatter:
+        score -= 10
+        issues.append("Missing version in frontmatter")
+        
+    file_count = len(list(skill_path.glob("**/*")))
+    if file_count > 20:
+        score -= 10
+        issues.append("High file count (>20), consider cleaning up")
+        
+    return max(0, score), issues
+
+def main():
+    parser = argparse.ArgumentParser(description="Skill Quality Analyzer")
+    parser.add_argument("--skill-path", required=True, help="Path to the skill directory")
+    args = parser.parse_args()
+    
+    skill_path = Path(args.skill_path).expanduser().resolve()
+    
+    if not skill_path.exists():
+        print(f"Error: Path {skill_path} does not exist")
+        sys.exit(1)
+        
+    frontmatter, markdown = load_skill_yaml(skill_path)
+    
+    if not frontmatter:
+        print(json.dumps({
+            "overall_score": 0,
+            "issues": ["Could not parse SKILL.md or invalid YAML frontmatter"],
+            "dimensions": {}
+        }, indent=2))
+        sys.exit(0)
+
+    # Calculate scores
+    scores = {}
+    total_score = 0
+    total_weight = 0
+    all_issues = []
+    
+    dimensions = [
+        ("clarity", lambda s, f, m: analyze_clarity(f, m), 20),
+        ("structure", lambda s, f, m: analyze_structure(s, f, m), 20),
+        ("examples", lambda s, f, m: analyze_examples(s, m), 15),
+        ("trigger_detection", lambda s, f, m: analyze_triggers(f, m), 15),
+        ("best_practices", lambda s, f, m: analyze_best_practices(s, f), 15),
+        ("maintainability", lambda s, f, m: analyze_maintainability(s, f), 15)
+    ]
+    
+    results = {}
+    
+    for name, func, weight in dimensions:
+        score, issues = func(skill_path, frontmatter, markdown)
+            
+        results[name] = {
+            "score": score,
+            "weight": weight,
+            "issues": issues
+        }
+        total_score += score * (weight / 100.0)
+        total_weight += weight
+        all_issues.extend(issues)
+
+    output = {
+        "skill_name": frontmatter.get("name", "unknown"),
+        "overall_score": int(total_score),
+        "dimensions": results,
+        "all_issues": all_issues,
+        "recommendations": [f"Fix: {issue}" for issue in all_issues] # Simple recommendation generation
+    }
+    
+    print(json.dumps(output, indent=2))
+
+if __name__ == "__main__":
+    main()

package/.agent/skills/skill-quality-analyzer/expected_output.json

@@ -0,0 +1,81 @@
+{
+  "skill_name": "example-skill",
+  "skill_path": "~/.claude/skills/example-skill/",
+  "overall_score": 85,
+  "quality_level": "Good",
+  "dimensions": {
+    "clarity": {
+      "score": 90,
+      "weight": 20,
+      "issues": [],
+      "recommendations": ["Consider adding more specific capability descriptions"],
+      "details": {
+        "description_length": 78,
+        "vague_words_count": 0,
+        "capabilities_count": 5
+      }
+    },
+    "structure": {
+      "score": 85,
+      "weight": 20,
+      "issues": ["Section ordering could be improved"],
+      "recommendations": ["Reorder sections to match Anthropic guidelines"],
+      "details": {
+        "missing_sections": [],
+        "section_order_similarity": 0.8
+      }
+    },
+    "examples": {
+      "score": 80,
+      "weight": 15,
+      "issues": ["Missing expected_output file"],
+      "recommendations": ["Add expected_output.json showing example output"],
+      "details": {
+        "usage_examples_count": 4,
+        "has_sample_input": true,
+        "has_expected_output": false
+      }
+    },
+    "trigger_detection": {
+      "score": 90,
+      "weight": 15,
+      "issues": [],
+      "recommendations": [],
+      "details": {
+        "trigger_indicators": 5,
+        "description_has_use_case": true
+      }
+    },
+    "best_practices": {
+      "score": 80,
+      "weight": 15,
+      "issues": ["Missing HOW_TO_USE.md"],
+      "recommendations": ["Add HOW_TO_USE.md with detailed usage examples"],
+      "details": {
+        "has_readme": true,
+        "has_how_to_use": false,
+        "backup_files_count": 0,
+        "has_pycache": false,
+        "python_files_count": 2
+      }
+    },
+    "maintainability": {
+      "score": 85,
+      "weight": 15,
+      "issues": ["No version information found"],
+      "recommendations": ["Add version number to README.md or SKILL.md"],
+      "details": {
+        "total_files": 8,
+        "has_version_info": false,
+        "has_scripts_documentation": true
+      }
+    }
+  },
+  "critical_issues": [],
+  "high_priority_recommendations": [
+    "Add expected_output.json showing example output",
+    "Add HOW_TO_USE.md with detailed usage examples",
+    "Add version number to README.md or SKILL.md"
+  ],
+  "comparison_notes": "Skill follows most Anthropic best practices. Minor improvements needed for examples and documentation."
+}

package/.agent/skills/skill-quality-analyzer/sample_input.json

@@ -0,0 +1,9 @@
+{
+  "skill_path": "~/.claude/skills/example-skill/",
+  "analysis_type": "detailed",
+  "options": {
+    "include_recommendations": true,
+    "compare_with_best_practices": true,
+    "generate_markdown_report": true
+  }
+}

package/.agent/skills/skill-tester/README.md

@@ -0,0 +1,46 @@
+# Skill Tester
+
+TDD tool for testing Claude Code skills functionality.
+
+## Quick Install
+
+```bash
+cp -r skill-tester ~/.claude/skills/
+```
+
+## Usage
+
+```
+"Test financial-analyzer skill"
+"Run full test suite on code-review"
+"Write tests for my new skill before implementing it"
+```
+
+## What It Does
+
+- ✅ Functional testing (correct outputs)
+- ✅ Trigger testing (skill activates when it should)
+- ✅ Edge case testing (handles unusual inputs)
+- ✅ Performance testing (execution time)
+- ✅ TDD workflow (write tests first)
+
+## Quick Example
+
+```
+User: "Test if financial-analyzer calculates P/E correctly"
+
+Claude:
+Test: P/E Calculation
+Input: price=100, eps=6.45
+Expected: 15.5
+Result: ✅ 15.504 (PASS)
+```
+
+## Files
+
+- `SKILL.md` - Testing methodology and patterns
+- `README.md` - This file
+
+## TDD Integration
+
+Works with TDD Guard to enforce test-first development for skills.

package/.agent/skills/skill-tester/SKILL.md

@@ -0,0 +1,345 @@
+---
+name: skill-tester
+description: Tests Codex skill functionality with TDD approach, verifying skills work correctly through automated test scenarios and validation
+---
+
+# Skill Tester
+
+Test-driven development tool for Codex skills. Verifies skill functionality, validates outputs, and ensures skills work correctly before distribution.
+
+## Capabilities
+
+- **Functional Testing**: Tests if skills produce expected outputs for given inputs
+- **Trigger Testing**: Verifies skills trigger when they should
+- **Regression Testing**: Ensures changes don't break existing functionality
+- **Integration Testing**: Tests skills work together correctly
+- **Performance Testing**: Measures skill execution time and resource usage
+- **TDD Workflow**: Write tests first, then validate skill meets requirements
+- **Test Coverage Analysis**: Identifies untested skill capabilities
+- **Automated Test Generation**: Creates test cases from skill examples
+
+## TDD for Skills
+
+### Red-Green-Refactor for Skills
+
+**Red Phase**: Write test showing skill doesn't work yet
+```
+Test: "Skill should calculate P/E ratio from price and EPS"
+Result: ❌ Skill doesn't have this capability
+```
+
+**Green Phase**: Implement skill to pass test
+```
+Test: "Skill should calculate P/E ratio from price and EPS"
+Result: ✅ Skill correctly calculates 15.5 from price=$100, EPS=$6.45
+```
+
+**Refactor Phase**: Improve skill quality
+```
+Test: "Skill should handle edge cases (zero EPS, negative values)"
+Result: ✅ All edge cases handled correctly
+```
+
+## Input Requirements
+
+**Basic Test**:
+- Skill name or path
+- Test scenario (what should happen)
+- Expected outcome
+
+**Comprehensive Test Suite**:
+- Skill path
+- Test cases (inputs + expected outputs)
+- Success criteria
+- Edge cases to verify
+
+**Example Test Case**:
+```json
+{
+  "skill": "financial-analyzer",
+  "test": "Calculate P/E ratio",
+  "input": {"price": 100, "eps": 6.45},
+  "expected_output": {"pe_ratio": 15.5},
+  "tolerance": 0.1
+}
+```
+
+## Output Formats
+
+**Quick Test Result**:
+```
+Testing: financial-analyzer
+Test: "Calculate P/E ratio"
+Result: ✅ PASS (output: 15.5, expected: 15.5)
+```
+
+**Detailed Test Report**:
+```
+=== Skill Test Report ===
+
+Skill: financial-analyzer
+Tests Run: 12
+Passed: 10 ✅
+Failed: 2 ❌
+Coverage: 83%
+
+Failures:
+1. ❌ Edge case: Zero EPS
+   Input: {price: 100, eps: 0}
+   Expected: Error or infinity
+   Got: Division error
+
+2. ❌ Negative values
+   Input: {price: -50, eps: 5}
+   Expected: Error message
+   Got: Calculated -10
+
+Recommendations:
+- Add error handling for zero/negative values
+- Validate inputs before calculation
+- Add edge case tests to skill documentation
+```
+
+**Test Coverage Map**:
+```
+Capability Coverage:
+
+✅ Calculate P/E ratio - 100% (4/4 tests pass)
+✅ Calculate ROE - 100% (3/3 tests pass)
+⚠️  Calculate debt ratio - 67% (2/3 tests pass, missing edge case)
+❌ DCF valuation - 0% (Not implemented)
+
+Overall: 75% coverage
+```
+
+## Test Types
+
+### 1. Trigger Tests
+**Purpose**: Verify skill triggers when it should
+
+**Test**: "Financial-analyzer should trigger for 'calculate P/E ratio'"
+```
+Query: "Calculate P/E ratio for this stock"
+Expected: financial-analyzer skill activates
+Result: ✅ Triggered correctly
+```
+
+### 2. Functional Tests
+**Purpose**: Verify correct outputs
+
+**Test**: "Should calculate correct P/E ratio"
+```
+Input: price=100, eps=6.45
+Expected: 15.5
+Result: ✅ Output: 15.504 (within tolerance)
+```
+
+### 3. Edge Case Tests
+**Purpose**: Handle unusual inputs
+
+**Test**: "Should handle zero EPS gracefully"
+```
+Input: price=100, eps=0
+Expected: Error message or infinity with warning
+Result: ❌ Division error (needs fix)
+```
+
+### 4. Integration Tests
+**Purpose**: Skills work together
+
+**Test**: "Quality-analyzer should use skill-tester"
+```
+Scenario: Analyze skill quality
+Expected: Skill-tester used to verify examples
+Result: ✅ Integration works
+```
+
+### 5. Performance Tests
+**Purpose**: Execution within acceptable time
+
+**Test**: "Should complete analysis within 5 seconds"
+```
+Input: Large dataset
+Expected: < 5 seconds
+Result: ✅ 2.3 seconds
+```
+
+## How to Use
+
+**Quick Test**:
+```
+"Test if financial-analyzer calculates P/E ratio correctly"
+"Verify code-review skill works for pull requests"
+"Test skill-quality-analyzer on itself"
+```
+
+**Comprehensive Test Suite**:
+```
+"Run full test suite on financial-analyzer with all edge cases"
+"Test all capabilities of aws-solution-architect skill"
+```
+
+**TDD Workflow**:
+```
+"Write tests for a new skill that should calculate financial ratios"
+"Create test cases for photo-enhancer before implementing it"
+```
+
+**Regression Testing**:
+```
+"Test if my skill changes broke anything"
+"Run regression tests on code-review after updates"
+```
+
+## Test Case Structure
+
+```yaml
+test_cases:
+  - name: "Basic P/E calculation"
+    input:
+      price: 100
+      eps: 6.45
+    expected_output:
+      pe_ratio: 15.5
+    tolerance: 0.1
+    priority: HIGH
+
+  - name: "Zero EPS edge case"
+    input:
+      price: 100
+      eps: 0
+    expected_error: "EPS cannot be zero"
+    priority: CRITICAL
+
+  - name: "Negative price edge case"
+    input:
+      price: -50
+      eps: 5
+    expected_error: "Price must be positive"
+    priority: HIGH
+```
+
+## Test Coverage Goals
+
+| Skill Type | Target Coverage |
+|-------------|----------------|
+| Critical (financial, security) | 95%+ |
+| Production (widely used) | 80%+ |
+| Experimental (new features) | 60%+ |
+| Utility (simple tools) | 50%+ |
+
+## Integration with Development Workflow
+
+### Phase 1: TDD (Before Implementation)
+```
+1. Write test cases based on requirements
+2. Document expected outputs
+3. Run tests (all should fail - RED phase)
+4. Implement skill
+5. Run tests (should pass - GREEN phase)
+6. Refactor and optimize
+```
+
+### Phase 2: Continuous Testing
+```
+1. Run tests after every skill change
+2. Add tests for new capabilities
+3. Update tests when requirements change
+4. Track coverage over time
+```
+
+### Phase 3: Pre-Release
+```
+1. Full test suite (100% of capabilities)
+2. Edge case validation
+3. Performance benchmarks
+4. Integration tests
+5. User acceptance testing
+```
+
+## Best Practices
+
+1. **Write Tests First**: TDD approach prevents bugs
+2. **Test Edge Cases**: Zero, negative, null, empty, very large values
+3. **Use Realistic Data**: Test with actual use case data
+4. **Automate Testing**: Run tests automatically on changes
+5. **Track Coverage**: Aim for 80%+ for production skills
+6. **Document Test Results**: Keep test reports for regression checking
+7. **Test Integrations**: Verify skills work together
+8. **Performance Benchmarks**: Set and monitor time limits
+
+## Common Test Patterns
+
+### Pattern 1: Golden Master Testing
+```
+Input: Known input
+Expected: Known correct output (golden master)
+Verify: Output matches golden master exactly
+```
+
+### Pattern 2: Property-Based Testing
+```
+Property: "P/E ratio should always be price / EPS"
+Test: Generate random valid inputs
+Verify: Formula holds for all inputs
+```
+
+### Pattern 3: Snapshot Testing
+```
+Input: Complex data structure
+Expected: Snapshot of previous correct output
+Verify: Current output matches snapshot
+```
+
+## Limitations
+
+- **Manual Test Creation**: Tests need to be written (not fully automatic)
+- **No Runtime Monitoring**: Can't test skills during actual use
+- **Static Testing**: Tests predefined scenarios, not all possible inputs
+- **No User Testing**: Can't test user satisfaction or UX
+- **Coverage Gaps**: Can't guarantee 100% coverage of all code paths
+
+## When NOT to Use This Skill
+
+- **Quick Experiments**: Testing adds overhead for throwaway skills
+- **Debugging**: Use skill-debugger for trigger/discovery issues
+- **Documentation**: Use skill-doc-generator for doc generation
+- **Quality Analysis**: Use skill-quality-analyzer for static analysis
+
+## Success Criteria
+
+A well-tested skill should:
+- ✅ Pass 100% of critical test cases
+- ✅ Handle all documented edge cases
+- ✅ Work within performance limits
+- ✅ Integrate correctly with other skills
+- ✅ Have 80%+ test coverage for production skills
+
+## Example Test Session
+
+```
+User: "Test the financial-analyzer skill"
+
+Claude: "Running test suite for financial-analyzer...
+
+Test Results:
+✅ Basic calculations (4/4 passed)
+✅ Error handling (3/3 passed)
+⚠️  Edge cases (2/3 passed)
+   - Failed: Handling of extremely large numbers
+
+✅ Integration tests (2/2 passed)
+✅ Performance (under 3 seconds)
+
+Overall: 11/12 tests passed (92%)
+
+Recommendation: Fix large number handling before production release.
+Would you like detailed failure analysis?"
+```
+
+## Related Skills
+
+- Works with **skill-quality-analyzer**: Test quality after static analysis
+- Works with **skill-debugger**: Test after fixing trigger issues
+- Works with **skill-doc-generator**: Test examples in generated docs
+- Complements **TDD Guard**: Enforces test-first development