moai-adk 0.35.1__py3-none-any.whl

moai_adk/templates/.claude/skills/moai-formats-data/modules/README.md

@@ -0,0 +1,98 @@
+# MoAI Data Format Skill Modules
+
+This directory contains the detailed implementation modules for the moai-formats-data skill, following Claude Code's progressive disclosure pattern.
+
+## Module Structure
+
+Each module focuses on a specific aspect of data format handling:
+
+### Core Modules
+
+- [`toon-encoding.md`](./toon-encoding.md)
+ - Complete TOON (Token-Optimized Object Notation) implementation
+ - 40-60% token reduction vs JSON for LLM communication
+ - Type markers, encoding/decoding, and performance characteristics
+
+- [`json-optimization.md`](./json-optimization.md)
+ - High-performance JSON and YAML processing
+ - Ultra-fast serialization with orjson
+ - Streaming processing for large datasets
+ - Memory management and batch processing
+
+- [`data-validation.md`](./data-validation.md)
+ - Comprehensive data validation system
+ - Schema management and evolution
+ - Advanced validation patterns and cross-field validation
+ - Performance-optimized batch validation
+
+- [`caching-performance.md`](./caching-performance.md)
+ - Intelligent caching strategies
+ - Multi-level caching with memory management
+ - Cache invalidation and warming strategies
+ - Performance monitoring and optimization
+
+## Usage
+
+These modules are referenced from the main skill file for detailed implementation examples and advanced use cases. Each module follows a consistent structure:
+
+1. Module header with complexity, time, and dependencies
+2. Core implementation with complete code examples
+3. Advanced features and extensions
+4. Performance characteristics and best practices
+5. Cross-references to related modules
+
+## Integration
+
+All modules work together seamlessly:
+
+```python
+# Example of integrating multiple modules
+from moai_formats_data import (
+ TOONEncoder, # from toon-encoding module
+ JSONOptimizer, # from json-optimization module
+ DataValidator, # from data-validation module
+ SmartCache # from caching-performance module
+)
+
+# Combine TOON encoding with validation and caching
+encoder = TOONEncoder()
+validator = DataValidator()
+cache = SmartCache()
+
+@cache.cache.cache_result(ttl=1800)
+def process_and_validate_data(data: Dict) -> str:
+ # Validate first
+ schema = validator.create_schema({
+ "user": {"type": "string", "required": True},
+ "value": {"type": "number", "required": True}
+ })
+
+ result = validator.validate(data, schema)
+ if not result['valid']:
+ raise ValueError(f"Invalid data: {result['errors']}")
+
+ # Encode optimized format
+ return encoder.encode(result['sanitized_data'])
+```
+
+## Performance Characteristics
+
+- TOON Encoding: 40-60% token reduction vs JSON
+- JSON Processing: 2-5x faster with orjson
+- Validation: Optimized batch processing with pattern compilation
+- Caching: Intelligent LRU eviction with memory pressure awareness
+
+## Dependencies
+
+Core requirements:
+- Python 3.8+
+- `typing`, `dataclasses`, `enum`, `re`, `datetime`
+
+Performance libraries (optional):
+- `orjson` - Ultra-fast JSON processing
+- `PyYAML` - High-performance YAML handling
+- `ijson` - Streaming JSON parser
+
+Validation libraries (optional):
+- `jsonschema` - JSON Schema validation
+- `pydantic` - Type hint based validation

moai_adk/templates/.claude/skills/moai-formats-data/modules/SKILL-MODULARIZATION-TEMPLATE.md

@@ -0,0 +1,278 @@
+# Skill Modularization Template
+
+> Purpose: Template for restructuring oversized skills (>500 lines) into compliant Claude Code format
+> Target: Progressive disclosure with modules/ directory structure
+> Compliance: <500 lines main SKILL.md, detailed modules for implementation
+
+## When to Use This Template
+
+Apply to skills that exceed 500 lines:
+- Current skill has >500 lines (violates Claude Code standards)
+- Contains multiple distinct technical areas
+- Has extensive implementation examples
+- Requires progressive disclosure for optimal user experience
+
+Typical candidates:
+- Domain skills with multiple subdomains
+- Implementation-heavy skills with extensive code examples
+- Skills covering multiple technologies or approaches
+
+## Modularization Process
+
+### 1. Analysis Phase
+
+Identify distinct technical areas:
+```python
+# Example for moai-formats-data:
+technical_areas = [
+ "TOON encoding implementation",
+ "JSON/YAML optimization",
+ "Data validation system",
+ "Caching and performance"
+]
+```
+
+Map content structure:
+- Quick Reference content (keep in main SKILL.md)
+- Implementation basics (keep in main SKILL.md)
+- Advanced features (move to modules)
+- Extended code examples (move to modules)
+
+### 2. Main SKILL.md Structure
+
+YAML Header (required):
+```yaml
+---
+name: skill-name
+description: Clear, concise description (under 80 chars)
+version: 1.0.0
+category: library|domain|integration|workflow
+tags: [3-7 relevant tags]
+updated: YYYY-MM-DD
+status: active|development|deprecated
+author: MoAI-ADK Team
+---
+```
+
+Progressive Disclosure Sections:
+
+1. Quick Reference (30 seconds) - Essential overview
+ - Core capabilities (3-6 bullet points with emojis)
+ - When to use (3-5 bullet points)
+ - Quick start code snippet (5-10 lines max)
+
+2. Implementation Guide (5 minutes) - Practical basics
+ - Core concepts (brief explanations)
+ - Basic implementation examples
+ - Common use cases with short examples
+
+3. Advanced Features (10+ minutes) - Extended usage
+ - Advanced patterns and techniques
+ - Integration examples
+ - Performance considerations
+
+Cross-references to modules:
+```markdown
+## Module References
+
+Core Implementation Modules:
+- [`modules/module-name.md`](./modules/module-name.md) - Brief description
+```
+
+### 3. Module Structure
+
+Each module follows this template:
+
+```markdown
+# Module Title
+
+> Module: Core area description
+> Complexity: Basic|Intermediate|Advanced
+> Time: X+ minutes
+> Dependencies: List of required libraries
+
+## Core Implementation
+
+Complete code implementation with:
+- Full class/function definitions
+- Comprehensive examples
+- Error handling
+- Performance characteristics
+
+## Advanced Features
+
+Extended functionality:
+- Custom extensions
+- Integration patterns
+- Performance optimization
+- Edge case handling
+
+## Best Practices
+
+Guidelines for production use:
+- Performance tips
+- Security considerations
+- Maintenance recommendations
+
+---
+
+Module: `modules/module-name.md`
+Related: [Other Module](./other-module.md) | [Related Module](./related-module.md)
+```
+
+### 4. Content Distribution Rules
+
+Keep in main SKILL.md:
+- Quick Reference section (30 seconds)
+- Basic Implementation (5 minutes)
+- Essential code examples (under 20 lines each)
+- Overview and integration patterns
+- Module cross-references
+
+Move to modules:
+- Complete implementation classes (>50 lines)
+- Extended examples and use cases
+- Advanced features and patterns
+- Performance optimization details
+- Complex integration examples
+
+### 5. Validation Checklist
+
+Main SKILL.md compliance:
+- [ ] Under 500 lines total
+- [ ] Complete YAML metadata
+- [ ] Progressive disclosure sections
+- [ ] Quick Reference (30s) present and concise
+- [ ] Implementation Guide (5min) covers basics
+- [ ] Module cross-references use forward slashes
+- [ ] No duplicate content with modules
+
+Module structure compliance:
+- [ ] Clear module headers with metadata
+- [ ] Focused on single technical area
+- [ ] Complete implementation examples
+- [ ] Cross-references to related modules
+- [ ] Consistent formatting across modules
+
+Content quality:
+- [ ] No information lost during modularization
+- [ ] Clear navigation between main and modules
+- [ ] Proper forward slashes in all paths
+- [ ] Consistent code formatting
+- [ ] Comprehensive examples in modules
+
+## Template Application Example
+
+### Before (832 lines - Non-compliant)
+```markdown
+# Skill Name
+# ... 832 lines of mixed content
+# Basic overview mixed with advanced implementation
+# No clear progression from simple to complex
+```
+
+### After (Compliant Structure)
+
+Main SKILL.md (490 lines):
+```markdown
+---
+name: moai-formats-data
+# ... YAML metadata
+---
+
+# Data Format Specialist
+
+## Quick Reference (30 seconds)
+Quick overview with 3-6 key capabilities
+When to use bullets
+Quick start example (5-10 lines)
+
+## Implementation Guide (5 minutes)
+Core concepts
+Basic implementation examples
+Common use cases
+
+## Advanced Features (10+ minutes)
+Advanced patterns
+Integration examples
+
+## Module References
+- [`modules/toon-encoding.md`](./modules/toon-encoding.md) - TOON implementation
+- [`modules/json-optimization.md`](./modules/json-optimization.md) - JSON optimization
+# ... other module references
+```
+
+modules/TOON-encoding.md (200+ lines):
+```markdown
+# TOON Encoding Implementation
+
+> Module: Core TOON implementation
+> Complexity: Advanced
+> Time: 15+ minutes
+> Dependencies: Python 3.8+, typing, datetime
+
+## Core Implementation
+[Complete TOON implementation code]
+
+## Advanced Features
+[Custom type handlers, streaming, etc.]
+
+---
+
+Module: `modules/toon-encoding.md`
+Related: [JSON Optimization](./json-optimization.md)
+```
+
+## Benefits of Modularization
+
+For Users:
+- Progressive disclosure respects their time investment
+- Clear path from basic to advanced usage
+- Focused modules for specific learning goals
+- Better navigation and information architecture
+
+For Maintainers:
+- Easier to update specific areas
+- Reduced cognitive load when reviewing changes
+- Better code organization and reuse
+- Simplified testing and validation
+
+For Compliance:
+- Meets Claude Code <500 line requirement
+- Follows progressive disclosure best practices
+- Maintains complete functionality
+- Improves token efficiency and loading performance
+
+## Automated Validation
+
+Use this script to validate compliance:
+```python
+def validate_skill_modularization(skill_path: str) -> dict:
+ """Validate skill meets Claude Code modularization standards."""
+ main_file = f"{skill_path}/SKILL.md"
+ modules_dir = f"{skill_path}/modules"
+
+ # Check main file length
+ with open(main_file, 'r') as f:
+ main_lines = len(f.readlines())
+
+ # Check for required sections
+ with open(main_file, 'r') as f:
+ content = f.read()
+ has_quick_ref = "Quick Reference" in content
+ has_implementation = "Implementation Guide" in content
+ has_modules = "Module References" in content
+
+ return {
+ "main_file_lines": main_lines,
+ "under_500_lines": main_lines < 500,
+ "has_required_sections": has_quick_ref and has_modules,
+ "compliant": main_lines < 500 and has_quick_ref and has_modules
+ }
+```
+
+---
+
+Template Version: 1.0.0
+Last Updated: 2025-11-30
+Purpose: Claude Code skill compliance and progressive disclosure