mcp-skills

# Skill Update Dates Research - Document Index **Research Date:** December 31, 2025 **Status:** Complete and Ready for Implementation **Total Size:** 36 KB across 4 documents ## Document Guide ### 1. Main Research Document (18 KB) **File:** `skill-update-dates-implementation-2025-12-31.md` **Contains:** - Executive summary of approach - Current architecture analysis with file locations - Data source comparison (mtime vs git commit date) - Detailed implementation approach with 3 phases - Architecture diagrams - Performance implications - Risk assessment matrix - Complete file modification checklist - Related code patterns in codebase **Best for:** Complete understanding of the system and long-term implementation strategy **Key sections:** - Current Architecture (explains 4 main components) - Data Sources (pros/cons of each approach) - Implementation Approach (detailed steps) - Files to Modify (all 3 files listed) - Performance Analysis - Risk Assessment --- ### 2. Quick Reference Guide (5 KB) **File:** `skill-update-dates-quick-reference-2025-12-31.md` **Contains:** - Key code locations with file paths and line numbers - Import statements to add - Backward compatibility notes - Testing locations - ChromaDB query examples - Files to modify summary table - Phase 1 checklist - Expected impact assessment **Best for:** Quick lookup during implementation **Key information:** - Where to add the datetime field (which file, which class) - Where to capture the date (which function, which line) - Where to store the date (ChromaDB metadata format) - What tests need updating --- ### 3. Detailed Code Changes (13 KB) **File:** `skill-update-dates-code-changes-2025-12-31.md` **Contains:** - Exact code changes for all 3 files - Line-by-line before/after examples - 9 specific code changes for skill.py - 3 specific code changes for skill_manager.py - 1 specific code change for vector_store.py - Import statement requirements - Testing requirements summary **Best for:** Implementation - copy/paste ready code changes **How to use:** 1. Open each file mentioned 2. Find the section for that file 3. Follow the "Current" to "Change to" examples 4. Make the modifications 5. Run tests --- ## Quick Start Path 1. **First read:** Quick Reference (5 minutes) - Understand scope and locations 2. **Review:** Main Research (15 minutes) - Understand why this approach - Review architecture - Check risk assessment 3. **Implement:** Code Changes (1-2 hours) - Follow the detailed examples - Run provided tests - Verify with actual SKILL.md files --- ## Key Findings Summary ### Best Approach: File Modification Time (mtime) - **Why:** Simple, no dependencies, works everywhere - **How:** `file_path.stat().st_mtime` - **Where:** SkillManager._parse_skill_file() - **Format:** Python datetime with UTC timezone ### Architecture Overview ``` SKILL.md file (contains skill definition) ↓ SkillManager._parse_skill_file() ↓ (capture mtime here) Skill dataclass ↓ IndexingEngine.index_skill() ↓ (routes to two stores) ├─ VectorStore (store in ChromaDB metadata) └─ GraphStore (optional for Phase 2) ``` ### Implementation Scope - **Files to modify:** 3 - **Lines to add:** ~20 - **Lines to modify:** ~15 - **Breaking changes:** None - **New dependencies:** None (datetime is stdlib) - **Backward compatible:** Yes ### Phase 1 (Recommended First) - Add field to Skill model - Capture mtime in SkillManager - Store in ChromaDB metadata - Update serialization - Time: 2-3 hours - Risk: Minimal ### Phase 2 (Optional) - Date-based filtering - Sort by recency - CLI flags - Time: 2-3 hours - Risk: Low ### Phase 3 (Future Enhancement) - Git commit date extraction - Update notifications - Skill freshness scoring - Time: 4+ hours - Risk: Medium --- ## Files Analyzed (Codebase Research) ### Core Files: 1. `src/mcp_skills/models/skill.py` - Skill data models 2. `src/mcp_skills/services/skill_manager.py` - Skill lifecycle 3. `src/mcp_skills/services/indexing/engine.py` - Indexing orchestration 4. `src/mcp_skills/services/indexing/vector_store.py` - ChromaDB integration ### Supporting Files: 5. `src/mcp_skills/models/repository.py` - Date pattern reference 6. `src/mcp_skills/services/repository_manager.py` - Git integration reference 7. `tests/test_indexing_engine.py` - Existing test structure --- ## Current ChromaDB Metadata **Currently stored:** - `skill_id` - Unique identifier - `name` - Skill name - `category` - For filtering - `tags` - Comma-separated - `repo_id` - Repository identifier **Will add:** - `updated_at` - ISO format datetime string --- ## Existing Patterns in Codebase The Repository model already implements datetime tracking: - **File:** `src/mcp_skills/models/repository.py` - **Field:** `last_updated: datetime` - **Pattern:** Uses `datetime.now(UTC)` from `datetime` module - **Serialization:** `.isoformat()` to string - **Deserialization:** `datetime.fromisoformat()` from string **Recommendation:** Follow the exact same pattern for Skill model. --- ## Import Statements Needed **In skill.py:** ```python from datetime import datetime ``` **In skill_manager.py:** ```python from datetime import UTC, datetime # Add UTC to existing imports ``` --- ## Testing Locations **Existing test fixtures:** - `/Users/masa/Projects/mcp-skillset/tests/test_indexing_engine.py` (line 25-71) **New tests needed:** 1. Datetime serialization/deserialization 2. Mtime capture in _parse_skill_file() 3. ChromaDB metadata verification --- ## Phase 1 Checklist - [ ] Add datetime import to skill.py - [ ] Add updated_at field to Skill dataclass - [ ] Add updated_at field to SkillMetadata dataclass - [ ] Update Pydantic models (SkillModel, SkillMetadataModel) - [ ] Update to_dict() methods for serialization - [ ] Update from_dict() methods for deserialization - [ ] Add UTC import to skill_manager.py - [ ] Capture mtime in _parse_skill_file() - [ ] Add updated_at to skill_data dict - [ ] Pass updated_at to Skill constructor - [ ] Update metadata dict in vector_store.py - [ ] Update test fixtures - [ ] Write serialization tests - [ ] Write mtime capture tests - [ ] Run full test suite - [ ] Test with actual skill files --- ## Related Linear Tickets **Create ticket with reference to this research:** - Title: "Add update timestamps to skills" - Description: Include link to this research documentation - Checklist: Use the Phase 1 checklist above - Estimate: 2-3 hours for Phase 1 --- ## Future Enhancements **Phase 2: Query Support** - Add date filter parameters to search - Implement date range filtering - Add sorting by date - Add CLI flags (--updated-after, --updated-before) **Phase 3: Advanced Features** - Git commit date extraction (more accurate) - Skill update notifications - "Recently updated" recommendations - Migration script for existing indices --- ## Performance Impact - **Speed:** Negligible (<1% overhead) - **Memory:** ~56 bytes per skill (datetime object) - **Storage:** ~30 bytes per skill (ISO string in ChromaDB) - **Indexing:** No impact on embedding generation - **Search:** Optional filters add minimal overhead --- ## Backward Compatibility - **Field is optional:** `updated_at: datetime | None = None` - **Existing skills:** Will have None value (graceful handling) - **No API breaks:** Fully backward compatible - **Migration:** Can add dates to existing skills later if needed --- ## Risk Assessment **Low Risk:** - Optional field (no breaking changes) - File mtime always available - Follows existing patterns - No external dependencies **Medium Risk:** - Serialization edge cases (handle None) - Timezone consistency (use UTC) - ChromaDB query syntax **Mitigation:** - Comprehensive unit tests - Clear None handling - Documentation - Gradual rollout --- ## Success Criteria Phase 1 is complete when: 1. All 3 files modified with correct datetime handling 2. Updated_at field populated for new skills 3. ChromaDB metadata includes updated_at 4. Serialization/deserialization round-trips work 5. All existing tests pass with updated fixtures 6. New tests for datetime handling pass 7. Manual testing with actual SKILL.md files succeeds --- ## Contact & Questions If questions arise during implementation: 1. Check the main research document for context 2. Review the code changes document for exact syntax 3. Check the quick reference for locations 4. Verify against existing Repository model pattern --- **Next Step:** Start with Phase 1 implementation using the code changes document.